URN Format

Model Forge manages all model artifacts through global identities: every artifact has a unique, stable and versionable URN that exists independently of storage location, file names or registry technology (ADR 050).

The identities simultaneously serve as:

• Registry keys
• Reference targets for JSON Schema $ref
• Stored artifact references
• Foundation for the dependency graph

Structure

urn:core:<scope>:<owner>:<artifact-type>:<domain>:<name>:<disambiguator>:<version>

The parser enforces only the urn:core: prefix and the positional segment layout; the value sets below are the platform convention, not parser-level constraints.

Segment	Meaning	Examples
urn:core	CORE namespace	—
scope	Scope of validity	platform, tenant, standard, dataset, project
owner	Publisher	civitas, stadt-muenster, xoev
artifact-type	Artifact type	element, datastructure, mapping, pipeline, datasource, datasink, dataset
domain	Domain hierarchy (dot-separated)	common, mobility.parking, environment.air
name	Readable technical name	GeoPoint, ParkingSensor, WeatherObservation
disambiguator	Short token that keeps equal names from colliding, 10 base36 chars	k3f9a2b7qx
version	Semantic version	1.0.0, 1.1.0, 2.0.0

Examples

urn:core:platform:civitas:element:common:GeoPoint:k3f9a2b7qx:1.0.0
urn:core:platform:civitas:datastructure:common:WeatherModel:h7c2m1x9a0:1.0.0
urn:core:tenant:stadt-muenster:element:mobility.parking:ParkingSensor:p4q8r2s6tu:1.0.0
urn:core:standard:xoev:element:xmeld:Meldeanschrift:z1x2c3v4b5:1.7

The standard scope marks external standard models imported unmodified (e.g. XÖV standards from XRepository).

The disambiguator segment

Model Forge is the source of every artifact's identity, and two artifacts with the same display name must not collide onto the same logical URN. The disambiguator segment guarantees that: a short token (10 base36 chars) in its own segment, so the name segment stays clean and human-readable.

It comes in two flavours:

• Minted — a fresh random token, generated once when Model Forge derives a URN from a display name (a schema title, a $defs key, a host-supplied name). This is the normal case: createArtifact and a $id-less import both mint. The token then belongs to the artifact's stable identity — follow-up versions and renames keep it.
• Derived — a deterministic token from a stable external identity, used when importing a standard from XRepository so that re-importing the same standard resolves to the same URN instead of a duplicate.

Who assigns the identity: createArtifact always mints — a caller-supplied id in the content is ignored. The only way to bring your own URN is to import a document (importSchema) whose $id is already a real CORE URN; that identity is kept. Everything else is minted by Model Forge.

Versions are normally SemVer x.y.z. Externally imported standards (XSD/XRepository, scope standard) may carry two-segment versions such as 1.7 or 6.0 — the XSD import explicitly accepts one to three numeric segments (plus an optional pre-release/build suffix).

An Element's exchange format (JSON Schema or XSD) is not encoded in the URN. Both use the element artifact type; the format is a per-version representation, not an identity (see XML/XSD Integration). A caller-supplied urn:core:…:xsd:… (an XSD artifact-type URN) is rejected with a validation error (IllegalArgumentException).

Logical vs. versioned identity

Model Forge distinguishes two forms of the same identity:

Form	Example	Represents
Logical URN (no version)	urn:core:platform:civitas:element:common:GeoPoint:k3f9a2b7qx	The domain concept
Versioned URN	urn:core:platform:civitas:element:common:GeoPoint:k3f9a2b7qx:1.0.0	A concrete version

The logical URN is the artifact's stored identity and the key of the in-memory caches; the version segment maps to a stored artifact_version. The dependency graph is version-precise: its nodes are versioned URNs and the dependency endpoints report concrete versions (a logical or :latest query resolves to the current version).

The latest reference token

A reference between artifacts may pin a concrete version (…:Foo:1.0.0) or use the latest token (…:Foo:latest) to always track the target's current (highest-SemVer) version. latest is valid as a reference target and as a read id (an artifact id passed to the ModelForge facade, e.g. …:Foo:latest), resolving to the current version at read time; the contract records returned by the facade always carry the concrete version, so latest stays a caller-side input. It is not a writable identity — an artifact is always authored at a concrete version, and a caller-supplied :latest (like a legacy :xsd:) identity is rejected with an IllegalArgumentException.

Usage in JSON Schema

Every JSON Schema carries the CORE URN as its $id — the document is fully self-describing:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id":     "urn:core:platform:civitas:element:common:GeoPoint:3ak90vqrog:1.0.0",
  "title":   "GeoPoint"
}

The backend respects an existing CORE URN as $id. If none is present, Model Forge generates one from the title field using the configured namespace segments (see Configuration).

Schemas reference other schemas directly through their CORE URN:

{
  "properties": {
    "location": {
      "$ref": "urn:core:platform:civitas:element:common:GeoPoint:3ak90vqrog:1.0.0"
    }
  }
}

From these references Model Forge automatically registers the dependency-graph edges and stores the full reference graph (including cycles) as artifact references (ADR 056).

Usage in Mappings and Pipelines

Mappings reference the participating Elements by URN:

{
  "$schema": "https://civitasconnect.digital/core/mapping/v1",
  "id":     "urn:core:platform:civitas:mapping:common:sensor-to-observation:0qyaberslc:1.0.0",
  "source": "urn:core:platform:civitas:element:common:SensorReading:d28s38wfmi:1.0.0",
  "target": "urn:core:platform:civitas:element:common:Observation:ulhry9fjx6:1.0.0"
}

Pipeline nodes reference DataSources, Mappings and DataSinks by URN:

{
  "id": "n-source",
  "kind": "source",
  "sourceRef": "urn:core:platform:civitas:datasource:common:mqtt-temperature:ofnq6u2trm:1.0.0"
}

Mapping to the registry

The artifact registry addresses artifacts by their stored identity, all derived mechanically from the URN:

Registry column	Derived from
artifact_type	artifact type segment (element, datastructure, mapping, …)
logical_urn	logical URN (without version)
artifact_version.version	version segment

The URN remains the domain source of truth; PostgreSQL is the technical persistence.