ADR 053: x-core-ref as a typed foreign-key annotation
Date: 2026-07-15
Status: Accepted
Decision Makers: @derlinne, @luckey
Context
References between artifacts must be expressible in JSON Schema without embedding the target.
Decision
The x-core-ref keyword annotates a string field as a foreign key — its value is the CORE URN of another artifact, identified by the target type (urn:core:type:Element, …:Mapping, …). It is the counterpart to a JSON Schema $ref, which embeds the target. Every reference is a global URN.
x-core-ref is a non-validating annotation in pure JSON Schema (it records the target type); referential integrity — that a URN resolves to an existing artifact — is the concern of registry-aware services.
Rationale
- All artifacts have stable global URNs, so a reference is always a URN. The bundled view already makes a DataSet self-contained.
- Existence depends on the registry, which a pure JSON Schema validator cannot reach — so it belongs in a registry-aware layer.
Consequences
A concrete x-core-ref target (e.g. a specific Element URN) is a strongly-typed foreign key whose existence is enforced against the registry on import/update by ReferenceExistenceValidator (diagnostic unresolved-core-ref); urn:core:type:<Kind> category targets are not existence-checked.