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 XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as XSD., but the wire format must not be part of its identity.

Decision​

An Element's exchange format (JSON Schema or XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as XSD.) is not part of its identity. The CORE URNCORE URNThe global identity Model Management assigns to every model artifact: a unique, stable and versionable URN that exists independently of storage location, file names or registry technology. 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 XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as XSD. can be served as JSON Schema, and a JSON Schema can be referenced from an XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as XSD.. The format therefore belongs to a version, not to the identity.
  • Formats are per version, so an Element may be authored as XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element 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 XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as 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 XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as XSD. versions.
  • Cross-format links: an XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as XSD. xs:import namespace="<CORE-URN>" links any Element (resolved directly to that URN); a JSON $ref to an XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as XSD.-backed Element resolves through on-read conversion. There is no JSON→XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as XSD. converter.

Consequences​

A schema read accepts an optional format (json-schema | xsd; default = authored format; xsd fails when the version stores no XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as XSD.). The format list filter treats json-schema as available (includes XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as 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 XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as XSD. eagerly at first import and works on JSON Schema internally