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.0and as JSON-Schema-only inv2.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_formatis the authored format;artifact_representationstores(version_id, format)content with agenerationofstoredorgenerated. 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
jsonschemafor 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$refto 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-backendintegration 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