Schema Versioning

The opentraces schema follows semantic versioning with pre-1.0 compatibility rules. The version lives in packages/opentraces-schema/src/opentraces_schema/version.py as the single source of truth.

Version Policy

Current Version

0.7.0

0.7.0 is additive: it introduces the dataset security policy contract (plan 092) without changing the TraceRecord wire shape, so existing trace parsers continue to work unchanged. 0.6.0 made TraceRecord.patches[] the authoritative output spine and removed Outcome.patch; consumers should join patch ids to the bucket Trail companion for full diff/history.

0.7.0

• WorkflowSecurityContract model — a dataset workflow's declared security posture (required_tools, optional_tools, default_enabled_tools, disallowed_tools, allow_disable_required).
• DatasetSecurityPolicy model — the resolved per-dataset policy stored on the manifest, seeded from a workflow contract and pinned to the source workflow digest.
• DatasetSecurityOverride model — an explicit recorded unsafe opt-out of a required security tool.
• DatasetManifest.security — additive optional field defaulting to an empty policy, so existing manifests load unchanged.
• SecurityToolName Literal and SECURITY_TOOL_ORDER tuple — the canonical security tool vocabulary mirroring the runtime tool registry.
• TraceRecord wire shape unchanged; migrate_record is a transparent no-op across the 0.6.0 -> 0.7.0 bump.

0.6.0

• Patch model.
• GitAnchor model.
• TraceRecord.patches[].
• Outcome.patch removed.
• Outcome.committed, Outcome.commit_sha, and TraceRecord.git_links are compatibility projections derived from patch anchors.

0.5.0

• Step.context_node_id.
• TraceRecord.context_tree_summary.

0.4.0

• Dataset/workflow manifest models.
• Dataset remotes, publication policy, schedules, and row index entries.
• Trace Index, Trace Map, and Candidate Packet contracts.

0.3.0

• TraceRecord.lifecycle.
• TraceRecord.git_links[].
• TraceRecord.generation_index.
• Richer attribution fields.
• Task.repository_url.
• Session-level prompt-cache aggregates.

Version Checks

HF dataset publication derives dataset_infos.json from the Pydantic models on every push. When the remote schema is newer than the local package, publication fails rather than overwriting the newer contract.

There is no public migration workflow today. A hidden diagnostic migration surface exists for local debugging, but schema evolution should be handled by registered migrations in the schema package when a breaking change is needed.

Security Pipeline Version

The security pipeline is versioned independently under src/opentraces/security/version.py.

SECURITY_VERSION = 0.6.0

opentraces doctor --security reports the active value and the enabled state of each optional tool.

Rationale Documents

Each schema version ships with a rationale document and a changelog entry in the schema package. See VERSION-POLICY.md and CHANGELOG.md.