Canonical JSON Schema

TrackForge uses deterministic JSON to make evidence and rating outputs reproducible. The same data, serialised with the same rules, must produce the same SHA-256 hash.

Serialisation Rule

json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=True)

Rules:

• Sort object keys lexicographically.
• Use no whitespace after separators.
• Escape non-ASCII characters.
• Encode the resulting string as UTF-8 before hashing.
• Do not append a trailing newline.

Current Rating Event JSON

Current certificate-facing output should identify the rating event and its proof contract:

{
  "rating_event_id": "...",
  "subject_type": "catalogue",
  "subject_id": "...",
  "rating": "BB",
  "rating_scale": "TRACKFORGE_AAA_D",
  "methodology_version": "v1.1",
  "methodology_hash": "...",
  "taxonomy_version": "v...",
  "workflow_version": "v...",
  "jurisdictional_scope": ["UK", "US"],
  "snapshot_run_id": "...",
  "snapshot_at": "...",
  "agreement_binding_summary": {
    "agreement_bound_count": 1042,
    "inferred_or_assumed_count": 38,
    "missing_or_conflicting_count": 0,
    "not_applicable_count": 0
  },
  "iswc_coverage_summary": {
    "present_count": 1061,
    "missing_count": 19,
    "conflict_count": 0,
    "not_applicable_count": 0
  },
  "leakage_vector_hash": "...",
  "evidence_packet_hash": "...",
  "merkle_root": "...",
  "ots_status": "pending"
}

Evidence Packet JSON

Evidence packets contain positive evidence and deterministic evaluation inputs. They should avoid duplicating finding narratives or mutable workflow state when a stable reference is enough.

Common blocks include:

• track
• identifiers
• sources
• society_registrations
• neighbouring_rights
• writers
• publishers
• findings_summary
• valuation_summary
• operator_review
• evaluation

The evidence packet hash is the SHA-256 hash of the canonical packet JSON.

Leakage Vector JSON

A leakage vector is a deterministic projection from the revenue leakage taxonomy:

{
  "taxonomy_item_id": "RL-...",
  "state": "active",
  "affected_revenue_pathway": "uk_performance",
  "affected_right_type": "composition",
  "evidence_references": ["snapshot:..."],
  "materiality_inputs": {
    "agreement_binding_state": "agreement_bound | inferred_or_assumed | not_applicable",
    "iswc_state": "present | missing | conflict | not_applicable"
  },
  "remediation_pointer": null
}

The vector hash should be computed from the ordered canonical representation used by the methodology version.

Legacy Canonical Track Records

Historical certification endpoints may still expose canonical track JSON and compatibility fields such as certification_tier, source_count, or platform identifiers. These are legacy or diagnostic fields unless a historical certificate explicitly binds them to its original methodology.

Current rating events should not treat platform source identifiers as rating-determinative by themselves.

Verification Procedure

To verify a current rating event:

1. Canonicalise the evidence packet and rating event JSON.
2. Recompute the evidence packet hash and rating input hash.
3. Rebuild the Merkle root from the committed leaf hashes.
4. Confirm the methodology hash, taxonomy version, workflow version, scope, and snapshot run ID match the certificate.
5. Verify OpenTimestamps proof files where status is confirmed.