opentraces-schema

Pydantic v2 models for the opentraces.ai JSONL trace format.

Install

pip install opentraces-schema

Usage

from opentraces_schema import TraceRecord, SCHEMA_VERSION

record = TraceRecord(
    trace_id="abc-123",
    session_id="sess-456",
    agent={"name": "claude-code", "version": "1.0.32"},
)
line = record.to_jsonl_line()

Version

The schema version (0.9.0) lives in src/opentraces_schema/version.py as the single source of truth. See VERSION-POLICY.md for semver semantics and the bump checklist.

0.9.0 adds the additive schema home for dataset-run metadata scope facets (issue #212, external-review fix for PR #218): DatasetCandidateQuery.facets (dict[str, str], default empty) and DatasetRunRecord.facet_resolution (dict[str, Any] | None, default absent). Both fields are optional and this bump only touches the local dataset-lifecycle models; the TraceRecord wire shape is untouched entirely. See RATIONALE-0.9.0.md for the design notes.

0.8.0 adds the additive schema home for exact dependency pins plus interpreter/CPU identity on Environment (issue #200, seal-family M3): the PinRecord and Interpreter nested models, and Environment.resolved_dependencies / .interpreter / .arch / .platform / .abi_tag, all optional and absent by default. This is a home for pins, not a resolver or a trust lift, see RATIONALE-0.8.0.md for the honesty boundary.

0.7.0 adds the additive dataset security policy contract (WorkflowSecurityContract, DatasetSecurityPolicy, DatasetManifest.security); the TraceRecord wire shape is unchanged from 0.6.0.

0.6.0 makes TraceRecord.patches[] the authoritative output spine for dev-time traces and removes the legacy unified-diff Outcome.patch field. Outcome.committed, Outcome.commit_sha, and TraceRecord.git_links remain reader-compatible projections derived from patch anchors. Full patch, trail, context, and source evidence lives in the private bucket companions (trail.jsonl.gz, context.jsonl.gz, sources.jsonl.gz) rather than being embedded into the JSONL row.

0.5.0 added Context Tree cross-reference fields: Step.context_node_id and TraceRecord.context_tree_summary.

0.4.0 introduced the local dataset/workflow contract used by the CLI's dataset and workflow commands plus the trace-index contract used by trace query, trace map, and trace slice.

0.3.0 added the commit-correlation surface: GitLink, TraceRecord.lifecycle, TraceRecord.generation_index, TraceRecord.git_links, Task.repository_url, Attribution.revision, Attribution.unaccounted_files, AttributionRange.original, AttributionRange.change_type, AttributionRange.contributor, and AttributionConversation.ids / .related.

Schema Rationale

Every version of the schema ships with a rationale document explaining why each model and field exists, grounded in public standards (ATIF, Agent Trace, ADP, OTel) and empirical observations from real agent traces.

The current rationale is RATIONALE-0.9.0.md. Each version has its own rationale file linked from the CHANGELOG.

Contributing

Schema feedback, questions, and proposals are welcome via GitHub Issues. When suggesting a schema change, please include:

• What field or model you would add, change, or remove
• Why it matters for your use case (training, analytics, attribution, etc.)
• How it relates to existing standards (ATIF, Agent Trace, ADP, OTel) if applicable

Breaking changes (field renames, removals, type changes) require a major version bump. New optional fields and models are minor bumps. See VERSION-POLICY.md for details.

Documentation

• CHANGELOG.md - What changed in each version
• VERSION-POLICY.md - What version numbers mean for a schema package
• FIELD-MAPPINGS.md - Field maps to ATIF, ADP, and OTel GenAI
• RATIONALE-0.9.0.md - Current rationale for v0.9.0 (dataset facet scoping)
• RATIONALE-0.8.0.md - Dependency pins + interpreter identity rationale
• RATIONALE-0.7.0.md - Dataset security policy rationale
• RATIONALE-0.6.0.md - Trace patch spine rationale
• RATIONALE-0.5.0.md - Context Tree cross-reference rationale
• RATIONALE-0.4.0.md - Dataset/workflow and trace-index rationale
• RATIONALE-0.3.0.md - Rationale for v0.3.0
• RATIONALE-0.2.0.md - Design rationale for v0.2.0
• RATIONALE-0.1.0.md - Design rationale for v0.1.0