XRepository Integration

Model Forge uses JSON Schema 2020-12 with stable CORE URNs as its canonical modelling format. XRepository 3.0 (KoSIT/IT-Planungsrat) is the authoritative directory for XÖV standards — primarily XML/XSD-based, but with an API-first approach and an extended artifact model in version 3.0.

There are two complementary integration directions:

Direction A (consuming XÖV) is implemented:

Facade operation	Function
ModelForge.searchXRepository(query)	Search XÖV standards in XRepository 3.0 (paginated)
ModelForge.importFromXRepository(command)	Download, XSD → JSON Schema 2020-12 conversion (or raw-XSD storage via importAsXsd) and storage as CORE Elements

Direction B (publishing CORE models to XRepository) is still a concept. See the ModelForge facade in model-forge-contract for the operation signatures.

Direction A — consuming XÖV models

XÖV standards (XMeld, XKfz, XPlanung, XBau, …) define data structures that municipalities process daily. Instead of remodelling them manually, Model Forge imports them directly from XRepository and manages them as CORE Elements.

XSD → JSON Schema mapping

The core of the work lies in the semantically correct mapping. The main cases:

XSD construct	JSON Schema 2020-12 equivalent	Note
xs:complexType	object + properties	1:1
xs:simpleType + xs:restriction	Base type + constraints	Partial (xs:totalDigits, exact xs:length and xs:whiteSpace facets are dropped — see the limitations below)
xs:sequence	properties + required	Ordering is lost (JSON Schema defines none)
xs:choice	oneOf	Semantically correct
xs:extension (inheritance)	allOf: [$ref: base, {properties: ...}]	Matches the CORE pattern
xs:import / xs:include	$ref to CORE URN	Namespace → URN mapping required
xs:annotation/xs:documentation	description	Direct
Codelist via xs:enumeration	enum: [...] or $ref to codelist schema	Handled separately (see below)
xs:attribute	properties (convention: @name)	Lossless without XML serialization
xs:mixed (mixed content)	No equivalent	Genuine gap — practically never occurs in XÖV standards
xs:fractionDigits	multipleOf (approximated)	Minor gap

Import safeguards

Downloaded XSDs often arrive as a ZIP archive. Extraction is bounded to defend against zip bombs and runaway memory use:

• at most 50 .xsd entries per archive,
• at most 2 MB decompressed per entry,
• at most 20 MB decompressed in total — enforced mid-stream, so an over-sized archive is rejected before it is fully buffered.

When an archive contains several schemas, the longest file is selected as the root schema (it is the one that includes the others). Archives that breach a limit are rejected with a validation error (IllegalArgumentException).

Namespace → CORE URN mapping

Each XÖV namespace gets a CORE owner and a domain. The scope standard (alongside platform and tenant) signals: external standard model, not locally modified.

urn:xoev-de:xmeld     →  urn:core:standard:xoev:element:xmeld::bwgu80skaz…
urn:xoev-de:xkfz      →  urn:core:standard:xoev:element:xkfz::bwgu80skaz…
urn:xoev-de:xplanung  →  urn:core:standard:xoev:element:xplanung::bwgu80skaz…

Codelist handling

XÖV codelists (nationality keys, vehicle registration codes, …) are imported as standalone JSON Schema Elements with enum values:

{
  "$id": "urn:core:standard:xoev:element:xmeld.codelists:Staatsangeh:b46hg5tywdörigkeit:2024.01",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Staatsangehörigkeit",
  "type": "string",
  "enum": ["DEU", "FRA", "AUT"],
  "x-xoev-codelist": "urn:de.xoev.xmeld.xmeld.2024.staatsangehoerigkeitsschluessel"
}

Other XÖV schemas reference this codelist Element via $ref — the dependency graph handles versioning and impact analysis automatically.

Direction B — publishing JSON models (concept)

Compared to 2.x, XRepository 3.0 has a significantly extended artifact model with a REST API and JSON Schema support. Municipal Elements (urn:core:tenant:stadt-muenster:…) could thus be registered as standards and shared with other municipalities.

Metadata mapping: CORE URN → XRepository

XRepository field	CORE source
identifier	CORE URN (logical, without version)
version	URN version segment (1.0.0)
name	title from JSON Schema
description	description from JSON Schema
artifactType	JSON_SCHEMA
dependencies	stored artifact references → XRepository references
owner	owner segment of the CORE URN
domain	domain segment

Publish flow

1. Select the CORE URN to publish
2. Generate the bundled view — all transitive dependencies embedded as $defs
3. Map the URN segments to XRepository metadata fields
4. POST to the XRepository artifact API
5. Annotate the stored artifact with the resulting XRepository URL (x-xrepo-url)

The bundled format is ideal for export: it is a fully valid, standalone JSON Schema 2020-12 without external registry dependencies — exactly what an external consumer without registry access needs.

Publishing is only sensible for schemas with scope=tenant or scope=platform — not for re-exported scope=standard schemas (XÖV originals).

Feature parity assessment

JSON Schema 2020-12 covers about 90 % of XÖV constructs directly.

• Genuine gap (rare in administrative data): xs:mixed — mixed content; practically never occurs in XÖV standards.
• Approximated: field ordering (xs:sequence enforces order, JSON Schema does not — irrelevant for data exchange); xs:fractionDigits approximated via multipleOf. xs:totalDigits, exact xs:length and xs:whiteSpace facets are currently dropped.
• Not implemented: xs:appinfo → x-* extraction — appinfo content is currently dropped (only xs:documentation is extracted).
• No gap, but convention required: XML attributes (@attribName prefix convention — note that xs:attributeGroup references are currently dropped; only direct xs:attribute declarations are mapped); namespaces (CORE URN scheme, already solved).

There is no fundamental gap that calls the JSON Schema approach into question.

Outlook: XRepository as a second storage backend

In the long term, XRepository 3.0 could serve as an additional storage backend alongside the PostgreSQL registry — scope=standard schemas would be read directly from XRepository without a local copy. This requires a sufficiently performant schema API on XRepository's side; currently a local copy in the registry is more robust.