trace-manifest.json

A portable record of intent, build, and proof

A trace-manifest is one JSON file that records a project's traceability matrix: every durable requirement ID, what proves it, what carries it as open work, and whether the whole chain from intent to build to proof holds. An emitter writes it; a viewer renders it; the file itself is the record.

The format is deliberately vendor-neutral. format: "trace-manifest" plus schemaVersion are the interop contract — any tool honoring the schema can write one, and any viewer can read the result without knowing which tool wrote it.

Versions

Version	Status	Spec	JSON Schema
v4	stable	/spec/v4/	/schema/v4.json
v5	beta — interop rev	/spec/v5/	/schema/v5.json

v5 is additive: every new field is optional, and a valid v4 file is a valid v5 file minus the new fields. The rev exists to open the format to emitters whose models differ from the reference implementation — explicit tier and parents edges instead of ID-prefix conventions, a generalized origin for ledger-minted IDs, durable code anchors, and an ext escape hatch. Writing an emitter? Start with the conformance checklist.

The smallest honest manifest

{
  "format": "trace-manifest",
  "schemaVersion": 5,
  "emitter": { "name": "your-tool", "version": "1.0.0" },
  "gate": { "ok": true, "failures": [] },
  "rows": [
    {
      "id": "AC-SYNC-01",
      "tier": "criterion",
      "parents": ["FR-SYNC-01"],
      "status": "proven",
      "statement": "Offline edits reconcile without loss.",
      "proofs": [{ "name": "test_AC_SYNC_01_reconcile", "path": "tests/sync_test.py", "line": 51 }]
    }
  ]
}

Status core

Four values, fixed across versions. Viewers key color on status and nothing else; emitters with a different native model map onto it and may record their own term in nativeStatus.

Status	Meaning
`proven`	A named carrier exists — not "tests ran green"
`tracked-debt`	Work started, proof missing, excused by an open task
`GAP`	A criterion with neither proof nor open debt — the gate refuses
`backlog`	Planning altitude; visible, not a silent gap

Files

Samples — valid manifests, small to real-world, in both the v4 and v5 dialects.
JSON Schemas: v4 · v5 — suitable for $schema references and CI validation. Every sample on this site validates against its schema.

Who writes it, who reads it

SpecAssay — reference emitter. Its Gate 2 writes a manifest on every run, including refusals.
Loupe — reference viewer. Reads the manifest only; it never re-scans the target.
A second, external emitter is in the works — the v5 rev is shaped with it.

The practice lineage is the software requirements-traceability matrix — not OMG ReqIF, not OSLC, not a certification claim. One file, one shape, readable at rest.