opentraces-schema 0.3.0

Schema models for the opentraces.ai agent trace JSONL format

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.3.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.3.0 adds the current 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.3.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
• RATIONALE-0.3.0.md - Current 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