Versioning

Status

Draft · v0.2.0 · 2026-06-30

This document defines the versioning scheme for the IOA-ORM, its compiled packages, the Pipecat adapter, and the event protocol. It covers format, compatibility rules, immutability guarantees, migration, deprecation, and runtime support policy.

---

1 Specification Version Format

1.1 Format

irVersion: "exam-runtime-ir/<major>.<minor>"

• Namespace: exam-runtime-ir — identifies the domain specification.
• Major: Incremented for breaking changes (incompatible schema changes, removed constructs, altered semantics).
• Minor: Incremented for backward-compatible additions (new optional fields, new enum values, new node types).
• No patch version. Bug fixes to the spec are tracked via documentation revisions, not version bumps. The specification version describes the schema contract, not the document.

1.2 Examples

Version	Meaning
exam-runtime-ir/0.1	Initial draft. Breaking changes expected.
exam-runtime-ir/0.5	Fifth backward-compatible iteration of the draft.
exam-runtime-ir/1.0	First stable release. Breaking changes require major bump.
exam-runtime-ir/1.3	Third backward-compatible addition to the stable release.
exam-runtime-ir/2.0	Second major version. Packages from 1.x need migration.

1.3 Pre-1.0 Stability

Versions 0.x are considered draft. Breaking changes MAY occur between minor versions during the 0.x phase. This is intentional: it allows rapid iteration before the first stable release.

Once 1.0 is reached, the compatibility rules in §2 become strictly binding.

---

2 Compatibility Rules

2.1 Semantic Versioning Contract

Change Type	Version Bump	Examples
Breaking	Major	Removing a field, changing a field type, altering node semantics, removing a node type, changing transition condition logic.
Backward-compatible addition	Minor	Adding an optional field, adding a new node type, adding a new transition condition type, adding a new enum value, adding a new event type.
Clarification / fix	None (doc revision)	Correcting a description, fixing an example, improving validation rule wording.

2.2 Forward Compatibility

A runtime that supports exam-runtime-ir/1.3 MUST also support:

• exam-runtime-ir/1.0 through exam-runtime-ir/1.3 (all minor versions within the same major).
• It SHOULD support exam-runtime-ir/0.x versions if those packages are still in active use.

2.3 What Constitutes a Breaking Change

The following are breaking changes that REQUIRE a major version bump:

1. Removing a required field from a node, transition, or package schema.
2. Changing the type of an existing field (e.g., string → number, object → array).
3. Renaming a field (unless the old name is preserved as a deprecated alias).
4. Removing a node type from the allowed enum.
5. Removing a transition condition type from the allowed enum.
6. Changing the semantics of an existing field (e.g., maxFollowUps shifts from “maximum” to “suggested”).
7. Changing the event schema in a way that breaks existing consumers.
8. Changing the evidence model (removing signal types, changing weight semantics).

2.4 What Constitutes a Non-Breaking Change

The following are non-breaking changes that require only a minor version bump:

1. Adding an optional field to any schema.
2. Adding a new node type (existing types unchanged).
3. Adding a new transition condition type (existing types unchanged).
4. Adding a new enum value to any existing enum.
5. Adding a new event type to the event protocol.
6. Adding a new recovery handler action.
7. Adding a new candidate command.
8. Tightening validation from MAY to SHOULD (not from SHOULD to MUST).

2.5 Assessment-Theoretic Breaking Changes

Some changes are schema-compatible but assessment-breaking. These do not require a major specification version bump, but they DO require re-validation of the assessment:

1. Changing evidence target descriptions in a way that alters what is assessed.
2. Changing follow-up policy (style, count, prompting levels) in a way that alters the interaction mode.
3. Changing time budgets significantly (>25% change).
4. Changing the examiner persona in a way that could affect face validity.
5. Removing or altering guardrails that protect assessment fairness.
6. Changing the assessment purpose (e.g., formative → summative).

Packages with assessment-theoretic changes MUST increment metadata.version and SHOULD include metadata.assessmentChangeLog (see §10.3).

---

3 Published Package Immutability

3.1 Core Rule

A published package is an immutable artifact. Once published, its content MUST NOT change. The irVersion, packageId, nodes, transitions, evidence targets, policies, and all other fields are frozen at publication time.

3.2 Rationale

• Auditability: Marking decisions must be reproducible. If a package could change after candidates have been assessed against it, marking integrity is compromised.
• Legal defensibility: In regulated assessment environments (medical, legal, professional certification), the assessment instrument must be provably unchanged.
• Session integrity: Runtime sessions reference a specific package version. Changing the package mid-flight would corrupt session state.

3.3 Versioning of Published Packages

If a lecturer needs to modify a published package:

1. Create a new package version with a new packageId and/or metadata.version.
2. The original package remains published and available for sessions that were started against it.
3. New sessions use the new package version.
4. In-flight sessions are NOT affected by the new version.

3.4 Package Version Lineage

Packages MAY include a metadata.supersedes field pointing to the packageId of the package it replaces. This enables:

• Tracking the evolution of an assessment.
• Redirecting new session starts to the latest version.
• Retaining historical versions for audit.

{
  "metadata": {
    "packageId": "pkg-2026-0506-002",
    "version": "2",
    "supersedes": "pkg-2026-0506-001",
    "title": "OSCE Station 2 - Lumbar Puncture (Revised)"
  }
}

---

4 Migration Rules

4.1 Migration Between Minor Versions

When a new minor version is released:

1. Existing published packages do not need re-publication. They remain valid under their original irVersion.
2. The runtime MUST support the new minor version alongside the previous versions.
3. The authoring studio MAY offer a “re-validate and upgrade” action that re-compiles a package under the new specification version. This produces a new package version (new packageId), not an in-place update.

4.2 Migration Between Major Versions

When a new major version is released:

1. Existing published packages remain valid under their original irVersion until end-of-life.
2. The runtime SHOULD support the old major version for a transition period (see §6 Runtime Support Policy).
3. The authoring studio MUST offer a migration tool that:
   • Identifies breaking changes between versions.
   • Produces a migration report listing required changes.
   • Generates a new package under the new irVersion where possible.
   • Highlights fields that require manual review.
4. Re-publication is required for packages migrated to a new major version.

4.3 Migration Tool Output

{
  "sourceVersion": "exam-runtime-ir/0.5",
  "targetVersion": "exam-runtime-ir/1.0",
  "packageId": "pkg-2026-0506-001",
  "autoMigrated": [
    {
      "change": "Added optional field `evidenceTarget.rubricDescriptor`",
      "action": "no_action_required",
      "nodeId": "q-osce-station-1"
    }
  ],
  "manualReviewRequired": [
    {
      "change": "`followUpPolicy.maxFollowUps` semantics changed from 'maximum' to 'hard limit with grace period'",
      "action": "review_and_adjust",
      "nodeId": "q-osce-station-2",
      "field": "followUpPolicy.maxFollowUps",
      "currentValue": 3,
      "note": "Verify that 3 is still appropriate under the new semantics."
    }
  ],
  "breakingChanges": [
    {
      "change": "`condition.type: 'auto_advance'` removed; use `evidence_sufficient` with `minCoverage: 1.0` instead",
      "action": "transform",
      "affectedTransitions": ["trn-001", "trn-003"]
    }
  ]
}

4.4 Data Migration

The Event Store and Evidence Ledger are NOT migrated between specification versions. Historical data remains under the schema of the specification version that produced it. The marking pipeline MUST be able to process evidence from any supported specification version.

---

5 Deprecation Policy

5.1 Deprecation Lifecycle

  Active          Deprecated        Removed
  (supported)     (warned)          (breaking change)
     │                │                  │
     ▼                ▼                  ▼
  [minor N]  ──►  [minor N+1]  ──►  [major M]
                      │
                      └── Minimum one minor version as deprecated

1. Announcement: When a field, enum value, or construct is deprecated, it is announced in the release notes for minor version N.
2. Deprecated phase: The construct is marked @deprecated in the schema. The runtime accepts it but logs a warning. This phase lasts at least one minor version.
3. Removal: The construct is removed in the next major version (M). Packages using the removed construct MUST be migrated.

5.2 Deprecation Annotations

In schema definitions, deprecated fields are annotated:

{
  "maxFollowUps": {
    "type": "integer",
    "minimum": 0,
    "deprecated": true,
    "deprecatedSince": "exam-runtime-ir/0.8",
    "replacedBy": "followUpPolicy.maxFollowUps",
    "removalTarget": "exam-runtime-ir/1.0"
  }
}

5.3 Runtime Behavior During Deprecation

Phase	Runtime Behavior
Active	Field is processed normally.
Deprecated	Field is processed normally. A deprecation warning is logged and emitted in the validation report.
Removed	Field is rejected. Validation error. Session cannot start.

---

6 Runtime Support Policy

6.1 Supported Versions

The runtime MUST support:

• The current specification version (latest minor within latest major).
• The previous major version (all its minor versions) for a transition period of at least 6 months after the new major version’s release.

The runtime SHOULD support:

• The two previous major versions if the deployment environment has long-lived packages (e.g., medical certification exams that span years).

6.2 Version Negotiation

When a session is initiated:

1. The runtime reads the package’s irVersion.
2. If supported, the session proceeds.
3. If unsupported, the session is rejected with:

{
  "error": "unsupported_ir_version",
  "packageIrVersion": "exam-runtime-ir/0.3",
  "supportedVersions": ["exam-runtime-ir/1.0", "exam-runtime-ir/1.1", "exam-runtime-ir/0.5"],
  "message": "This package was compiled with an unsupported specification version. Please re-publish the package under a supported version.",
  "migrationHint": "Use the migration tool to upgrade from 0.3 to 1.0."
}

6.3 End-of-Life Announcement

End-of-life for a specification version MUST be announced at least 3 months before the runtime stops supporting it. The announcement MUST include:

• The version being retired.
• The retirement date.
• The migration path.
• Contact information for support.

---

7 Adapter Versioning

7.1 Format

adapterVersion: "pipecat-adapter/<major>.<minor>"

The adapter version tracks the mapping logic between specification and Pipecat FlowConfig. It is independent of the specification version, though they are correlated.

7.2 When to Bump

Change	Bump
New specification field mapped to Pipecat construct	Minor
Changed system prompt template	Minor
Changed tool schema structure	Major
Changed metadata shape	Major
Bug fix in mapping logic	Minor
New tool added (e.g., report_evidence_signal)	Minor
Tool removed or renamed	Major

7.3 Co-Versioning with Specification

Specification Version Change	Adapter Version Impact
Minor (new optional field)	Adapter minor (map the new field if applicable).
Major (breaking change)	Adapter major (remap or restructure).
None (doc fix)	None.

7.4 Adapter Version in Compiled Output

Every compiled FlowConfig MUST include:

{
  "adapterVersion": "pipecat-adapter/0.2",
  "compiledFrom": "exam-runtime-ir/0.5",
  "compiledAt": "2026-05-06T02:00:00Z",
  "packageId": "pkg-2026-0506-001"
}

This enables debugging when a runtime issue is traced to a specific adapter version.

---

8 Event Protocol Versioning

8.1 Format

protocolVersion: "exam-events/<major>.<minor>"

8.2 Scope

The event protocol version covers:

• The event envelope structure (event, sessionId, timestamp, payload).
• The set of recognized event types.
• The schema of each event type’s payload.
• Data channel topic naming conventions.

8.3 Compatibility

Change	Version Bump
New event type added	Minor
New optional field in existing event payload	Minor
Removed event type	Major
Changed required field in event payload	Major
Changed event envelope structure	Major
Renamed event type	Major

8.4 Consumer Contract

Event consumers (frontend Exam Room, Event Store, marking pipeline) MUST:

1. Declare the protocol version(s) they support.
2. Ignore unrecognized event types gracefully (forward compatibility).
3. Reject events with an unsupported major version.
4. Log warnings for events with a newer minor version than expected.

8.5 Event Envelope

Every event emitted over the data channel or persisted to the Event Store MUST include the protocol version:

{
  "protocolVersion": "exam-events/0.3",
  "event": "node_entered",
  "sessionId": "sess-2026-0506-001",
  "timestamp": "2026-05-06T02:10:00Z",
  "payload": { ... }
}

---

9 Version Registry

The following table tracks all versions and their status:

Version	Status	Released	End-of-Life	Notes
exam-runtime-ir/0.1	Draft	—	—	Initial specification.
pipecat-adapter/0.1	Draft	—	—	Initial adapter mapping.
exam-events/0.1	Draft	—	—	Initial event protocol.

This table is maintained in the specification repository and updated with each release.

---

10 Assessment-Theoretic Versioning

The specification version tracks schema compatibility (§1–2). However, assessment theory introduces a second dimension of change: assessment semantics. A schema change that is backward-compatible (e.g., adding an optional field) may still alter the assessment’s validity, reliability, or fairness properties in ways that require review by assessment designers.

10.1 Assessment Change Classification

The following table classifies changes by their assessment-theoretic impact, independent of their schema impact:

Assessment Change	Schema Impact	Assessment Impact	Action Required
New evidence target added	Minor (additive)	Content validity may change	Assessment designer review
Follow-up style changed	None (config only)	Reliability may change (Joughin, 1998, §structure dimension)	Recalibrate inter-case consistency
Time budget adjusted	None (config only)	Fairness may change (Akimov & Malin, 2020: “rushed” exams)	Pilot with candidate cohort
Examiner persona changed	None (config only)	Face validity may change	Candidate survey
New candidate command added	Minor (additive)	Accessibility improves	Accessibility audit
Evidence signal taxonomy extended	Minor (additive)	Construct validity may change	Psychometric validation
Interaction mode changed (e.g., dialogue → presentation)	Minor or none	Reliability profile changes (Joughin, 1998, p. 376)	Full re-validation
Assessment purpose changed (summative → formative)	None	All validity claims affected	Full re-validation

10.2 Assessment Version Metadata

Published packages SHOULD declare their assessment-theoretic properties so that changes can be tracked independently of schema version:

{
  "metadata": {
    "assessmentProfile": {
      "interactionMode": "structured_dialogue",
      "contentTypes": ["knowledge_understanding", "applied_problem_solving"],
      "structureLevel": "semi-structured",
      "assessmentPurpose": "summative",
      "authenticityLevel": "simulated",
      "lastValidated": "2026-05-01",
      "validityEvidence": {
        "faceValidity": "candidate survey, n=45, 89% agreement",
        "contentValidity": "LO coverage map reviewed by panel",
        "interRaterReliability": "Cohen's κ = 0.82 (AI vs human marker)"
      }
    }
  }
}

10.3 When Assessment Properties Change

When a new package version changes assessment-theoretic properties (even if the schema is unchanged):

1. The package MUST increment metadata.version (per §3.3).
2. The package SHOULD include metadata.assessmentChangeLog describing what changed and why.
3. The package SHOULD reference prior validity evidence in metadata.assessmentProfile.validityEvidence and note whether it still holds.
4. For high-stakes exams, the changed properties SHOULD be re-validated before the new version is used for summative assessment.

This dual-versioning approach (schema version + assessment profile) ensures that assessment quality is tracked alongside technical compatibility.

---

11 Version Specification Summary

Component	Version Field	Example	Where It Appears
Specification Version	irVersion	exam-runtime-ir/0.1	Package root, validation reports
Pipecat Adapter	adapterVersion	pipecat-adapter/0.2	Compiled FlowConfig, audit logs
Event Protocol	protocolVersion	exam-events/0.3	Every event envelope
Package Version	metadata.version	2	Package metadata (per-package, not per-specification)
Package ID	metadata.packageId	pkg-2026-0506-001	Unique identifier for immutable published package
Assessment Profile	metadata.assessmentProfile	(see §10.2)	Package metadata; tracks assessment semantics

Revision History

Version	Date	Changes
v0.2.0	2026-06-30	Updated version format and compatibility rules for IOA-ORM. Updated terminology from ‘Exam Runtime IR’ to ‘IOA-ORM’.
v0.1.0	2026-05-06	Initial release.