Version: 2.0-rc2

URN Format

Model Management 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.

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>:<version>

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	`datastructure`, `mapping`, `pipeline`, `datasource`, `datasink`, `dataset`
`domain`	Domain hierarchy (dot-separated)	`common`, `mobility.parking`, `environment.air`
`name`	Technical name	`GeoPoint`, `ParkingSensor`, `WeatherObservation`
`version`	Semantic version	`1.0.0`, `1.1.0`, `2.0.0`

Examples

urn:core:platform:civitas:datastructure:common:GeoPoint:1.0.0
urn:core:tenant:stadt-muenster:datastructure:mobility.parking:ParkingSensor:1.0.0
urn:core:tenant:stadt-muenster:mapping:mobility.parking:ParkingSensorToNgsi:1.0.0
urn:core:tenant:stadt-muenster:pipeline:mobility.parking:ParkingImport:1.0.0
urn:core:standard:xoev:datastructure:xmeld:Meldeanschrift:1.7

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

A DataStructure's exchange format (JSON Schema or XSD) is not encoded in the URN. Both use the datastructure artifact type; the format is a per-version representation, not an identity (see XML/XSD Integration). A client-supplied urn:core:…:xsd:… (an XSD artifact-type URN) is rejected with HTTP 400.

Logical vs. versioned identity

Model Management distinguishes two forms of the same identity:

Form	Example	Represents
Logical URN (no version)	`urn:core:platform:civitas:datastructure:common:GeoPoint`	The domain concept
Versioned URN	`urn:core:platform:civitas:datastructure:common:GeoPoint: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 (GET …?id=…:Foo:latest), resolving to the current version at read time; self/HAL links and Location headers always return the concrete version, so latest stays a client→server input. It is not a writable identity — an artifact is always authored at a concrete version, and a client-supplied :latest (like a legacy :xsd:) identity is rejected with 400.

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:datastructure:common:GeoPoint: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:datastructure:common:GeoPoint:1.0.0"
    }
  }
}

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

Usage in Mappings and Pipelines

Mappings reference the participating DataStructures by URN:

{
  "$schema": "https://civitasconnect.digital/core/mapping/v1",
  "id":     "urn:core:platform:civitas:mapping:common:sensor-to-observation:1.0.0",
  "source": "urn:core:platform:civitas:datastructure:common:SensorReading:1.0.0",
  "target": "urn:core:platform:civitas:datastructure:common:Observation: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: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 (`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.

Structure​

Examples​

Logical vs. versioned identity​

The latest reference token​

Usage in JSON Schema​

Usage in Mappings and Pipelines​

Mapping to the registry​