Skip to main content
Version: V2-Next

ADR 058: Format-agnostic Elements with versioned representations

Date: 2026-07-15

Status: Accepted

Decision Makers: @derlinne, @luckey

Context​

An Element may be authored as JSON Schema or XSD, but the wire format must not be part of its identity.

Decision​

An Element's exchange format (JSON Schema or XSD) is not part of its identity. The CORE URN always uses the element type; the format is recorded per version as a stored representation. Each version declares its authored primary_format, and artifact_representation holds one row per format (unique (version_id, format)).

Rationale​

  • An Element is the same domain concept regardless of the wire format: an XSD can be served as JSON Schema, and a JSON Schema can be referenced from an XSD. The format therefore belongs to a version, not to the identity.
  • Formats are per version, so an Element may be authored as XSD in v1.0.0 and as JSON-Schema-only in v2.0.0; a format change is just a new version.
  • Reads route through the stored representation formats instead of parsing the URN, so the persistence layer is the single source of truth.

Mechanism​

  • artifact_version.primary_format is the authored format; artifact_representation stores (version_id, format) content with a generation of stored or generated. A JSON Schema derived from an XSD is generated on read (cacheable); idempotency and versioning consider only authored (stored) content.
  • A version's readable formats are its stored representations plus the derivable jsonschema for XSD versions.
  • Cross-format links: an XSD xs:import namespace="<CORE-URN>" links any Element (resolved directly to that URN); a JSON $ref to an XSD-backed Element resolves through on-read conversion. There is no JSON→XSD converter.

Consequences​

A schema read accepts an optional format (json-schema | xsd; default = authored format; xsd fails when the version stores no XSD). The format list filter treats json-schema as available (includes XSD-authored Elements) and xsd as stored. Version-precise references build on this (ADR 059).

See also​

  • XML/XSD Integration
  • ADR 061: the portal-backend integration converts XSD eagerly at first import and works on JSON Schema internally