# Open Proficiency Model (OPM)

The Open Proficiency Model (OPM) is an open specification for quantifying an individual's familiarity with skills, capabilities, and other abilities. It provides a standardized, verifiable, and distributed system for tracking proficiency across knowledge domains through topics, proficiency scores, and signed transcript entries issued by verified entities.

The model enables portable proficiency records that are cryptographically signed by issuers (organizations with domain ownership), preventing tampering and ensuring records remain valid even if the issuer becomes unavailable. This allows knowledge and skills to be transferred across institutions without requiring repeated learning of already-mastered topics.

## Topic Definition

A Topic is the fundamental building block representing a unique area of knowledge. Topics can be atomic (standalone) or group topics (containing subtopics), and can reference prerequisite topics (pretopics) required before building proficiency.

```json
{
  "addition": {
    "description": "Combining two or more numbers to find their sum or total.",
    "pretopics": ["numbers"]
  },
  "subtraction": {
    "description": "Finding the difference between numbers by removing one quantity from another.",
    "pretopics": ["numbers"]
  },
  "arithmetic": {
    "description": "Fundamental operations: addition, subtraction, multiplication, and division.",
    "subtopics": ["addition", "subtraction", "multiplication", "division"]
  }
}
```

## Topic List Schema

A Topic List is a signed collection of topics defining a knowledge domain, issued by a verified entity. It requires owner, name, description, version, timestamp, certificate, and topics fields.

```json
{
  "$schema": "https://raw.githubusercontent.com/openproficiency/model/refs/heads/main/schemas/topic-list.schema.json",

  "owner": "example.com",
  "name": "binary-math",
  "description": "Mathematics in binary for electrical circuits.",
  "version": "0.1.0",
  "timestamp": "2026-01-26T01:00:00Z",
  "certificate": "-----BEGIN CERTIFICATE-----ABC123DEF456-----END CERTIFICATE-----",

  "topics": {
    "binary-addition": {
      "description": "Combining of 2 or more numbers.",
      "pretopics": ["std-math.addition"]
    },
    "binary-subtraction": {
      "description": "Taking one number or quantity away from another.",
      "pretopics": ["std-math.subtraction"]
    },
    "binary-arithmetic": {
      "description": "Application of electrical circuits to perform basic math operations.",
      "subtopics": [
        "binary-addition",
        "binary-subtraction",
        "binary-multiplication",
        "binary-division"
      ]
    }
  },

  "dependencies": {
    "std-math": "https://example.com/opm/topic-lists/math.json@0.1.0"
  }
}
```

## Proficiency Score

A Proficiency Score is a number between 0.0 and 1.0 indicating the degree of understanding for a specific topic. Scores propagate upward through subtopics (normalized sum) and downward to all subtopics equally.

```yaml
# Implicit Scoring Levels (default)
0.0: Unaware    # Does not know of the topic's existence
0.1: Aware      # Ability to recognize the topic
0.5: Familiar   # Theoretical understanding
0.8: Applied    # Has practically used the knowledge (minimum for pretopic)
1.0: Proficient # Used enough to consider "fundamental"

# Score Propagation Example
# arithmetic score = (0.8 + 0.8 + 0.5 + 0.1) / 4 = 0.55
arithmetic: 0.55
  - addition: 0.8
  - subtraction: 0.8
  - multiplication: 0.5
  - division: 0.1
```

## Transcript Entry Schema

A Transcript Entry is a permanent, signed record of a user's proficiency score for a single topic. Each entry is individually signed by the issuer for verification.

```json
{
  "$schema": "https://raw.githubusercontent.com/openproficiency/model/refs/heads/main/schemas/transcript-entry.schema.json",

  "userID": "first.last@example.com",
  "topic": "addition",
  "topicList": "https://example.com/math@0.1.0",
  "score": 0.8,
  "timestamp": "2026-01-01T01:01:01Z",
  "issuer": "example.com",
  "certificate": "-----BEGIN CERTIFICATE-----ABC123DEF456-----END CERTIFICATE-----"
}
```

## Transcript Collection

A Transcript is a convenience container holding multiple transcript entries for portability. It has no required format and no additional signing beyond the individual entries.

```json
[
  {
    "userID": "first.last@example.com",
    "topic": "addition",
    "topicList": "https://example.com/math@0.1.0",
    "score": 0.8,
    "timestamp": "2026-01-01T01:01:01Z",
    "issuer": "example.com",
    "certificate": "-----BEGIN CERTIFICATE-----ABC123DEF456-----END CERTIFICATE-----"
  },
  {
    "userID": "first.last@example.com",
    "topic": "subtraction",
    "topicList": "https://example.com/math@0.1.0",
    "score": 0.8,
    "timestamp": "2026-01-01T01:01:01Z",
    "issuer": "example.com",
    "certificate": "-----BEGIN CERTIFICATE-----ABC123DEF456-----END CERTIFICATE-----"
  }
]
```

## Proficiency Level Definition

A Proficiency Level provides a standardized interpretation of proficiency scores, typically representing job roles or achievement tiers. Levels can only have pretopics (no subtopics) and are "achieved" when all pretopics have a minimum score of 0.8.

```json
{
  "$schema": "https://raw.githubusercontent.com/openproficiency/model/refs/heads/main/schemas/proficiency-levels-list.schema.json",

  "owner": "example.com",
  "name": "math-teacher-levels",
  "description": "Proficiency levels for math teaching positions.",
  "version": "0.1.0",
  "timestamp": "2026-01-26T01:00:00Z",
  "certificate": "-----BEGIN CERTIFICATE-----ABC123DEF456-----END CERTIFICATE-----",

  "proficiency-levels": {
    "math-teacher-junior": {
      "pretopics": [
        "std-math.basic-math",
        "std-pedagogy.classroom-management"
      ]
    },
    "math-teacher": {
      "pretopics": [
        "std-pedagogy.lesson-planning",
        "std-pedagogy.lesson-customization"
      ]
    },
    "math-teacher-senior": {
      "pretopics": [
        "std-pedagogy.teacher-mentoring",
        "std-pedagogy.curriculum-development"
      ]
    }
  },

  "dependencies": {
    "std-math": "https://example.com/topics-lists/math.json@0.1.0",
    "std-pedagogy": "https://example.com/topics-lists/pedagogy.json@0.1.0"
  }
}
```

## Issuer Requirements

An Issuer is a verified entity that can create topic lists and issue transcript entries. Issuers must own a domain name and provide distributable certificates for signing documents.

```yaml
# Issuer Certificate Requirements
# 1. Embedded x.509 certificate provides the public key (issuer identity)
# 2. Embedded Ed25519 signature built from all protected fields

# Example Issuer Use Cases:

# Product/Service Provider
issuer: "3dprinting-company.com"
role: "Provide topic lists covering product features, tutorials, and maintenance"
outcome: "Users download transcripts for resumes"

# Educational Institution
issuer: "university.edu"
role: "Consume standard topic lists, map courses to topics"
outcome: "Issue transcript entries upon course completion"
```

## Topic List Dependencies

Topic lists can import topics from other lists by declaring them as dependencies. Imported topics can only be used as pretopics and are referenced using dot notation with a local namespace.

```yaml
owner: "example.com"
name: "binary-math"
description: "Mathematics in binary for electrical circuits."
version: "0.1.0"
timestamp: "2026-01-26T01:00:00Z"
certificate: "-----BEGIN CERTIFICATE-----ABC123DEF456-----END CERTIFICATE-----"

topics:
  binary-addition:
    description: Combining of 2 or more numbers.
    pretopics:
      - std-math.addition  # References imported topic
  binary-subtraction:
    description: Taking one number or quantity away from another.
    pretopics:
      - std-math.subtraction

dependencies:
  std-math: https://example.com/topics-lists/math.json@0.1.0
```

## Summary

The Open Proficiency Model is primarily designed for educational institutions, training providers, and organizations that need to track and verify skill proficiency. Key use cases include: portable academic transcripts that work across institutions, employee skill verification for HR systems, certification programs with verifiable credentials, and self-paced learning platforms that issue signed proficiency records.

Integration patterns typically involve consuming standard topic lists from recognized authorities, mapping internal courses or training modules to those topics, and issuing signed transcript entries as users complete learning activities. The cryptographic signing ensures records remain valid independently of the issuing organization, enabling true portability of demonstrated skills and knowledge across different platforms and institutions.