XML/XSD Integration

A user can create, view and link 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. and JSON Schema DataStructures with the same tooling. The format is an implementation detail — visible only as a small tag. Everything else (search, linking, dependency graph, mapping) works uniformly.

Status

The backend side is implemented: DataStructures are format-agnostic (artifact-type=datastructure; the format is a per-version representation), the xsd package provides parsing/conversion, and the following endpoints are in operation:

Endpoint	Function
GET /api/v1/xrepository/search / preview, POST .../import	Search, convert and import XÖV standards
POST /api/v1/datastructures (XML body)	Import raw 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. as a DataStructure
POST /api/v1/datastructures/validate (XML body)	Dry run: well-formedness/security check of 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.
GET /api/v1/datastructures/schema?id=…&format=json-schema|xsd	Read a representation (default = authored format)
GET /api/v1/datastructures/views/json-schema?id=…	Normalized JSON Schema for any DataStructure (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. converted)

The UI parts (format tag, cross-format ref picker) are frontend concepts that build on these endpoints.

The format-agnostic DataStructure model

A DataStructure is format-agnostic. The format is a property, not a category:

Field	Content
id	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. (unchanged across formats)
title, description	Display metadata
format	jsonschema or xsd
properties	Unified property representation (see below)
refs	DataStructure URNs — cross-format references are possible

Unified property representation

The editor always renders properties the same way — whether extracted from a JSON Schema or 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.:

JSON Schema	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.	Representation in the editor
properties.strasse	xs:element name="strasse"	Property strasse
type: string	xs:string	Type string
required: [strasse]	minOccurs="1"	Required-field marker
$ref: urn:…	xs:element type="…"	Link to another DataStructure
description	xs:documentation	Tooltip / description text
enum: [...]	xs:enumeration	Enumeration
oneOf: [...]	xs:choice	Alternative types

Cross-format links

In 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. DataStructure, a property can reference a JSON Schema DataStructure — exactly the way two JSON Schema DataStructures are linked. The format of the target does not matter.

In JSON Schema:

{
  "$id": "urn:core:standard:xoev:datastructure:xinneres.xmeld:Meldeanschrift:1.7",
  "x-xsd-source": "urn:core:standard:xoev:datastructure:xinneres.xmeld:Meldeanschrift:1.7",
  "properties": {
    "ort": {
      "$ref": "urn:core:platform:civitas:datastructure:common:Gemeinde:1.0.0"
    }
  }
}

In 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. — an xs:import whose namespace is the target's 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.. Model Forge resolves a CORE-URN import namespace directly to that DataStructure (of any format) and records the dependency edge:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:g="urn:core:platform:civitas:datastructure:common:Gemeinde:1.0.0"
           targetNamespace="urn:example:meldeanschrift">
  <xs:import namespace="urn:core:platform:civitas:datastructure:common:Gemeinde:1.0.0"/>
  <xs:complexType name="Meldeanschrift">
    <xs:sequence>
      <xs:element name="ort" type="g:Gemeinde"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

A classic XML namespace (not a 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.) is instead resolved through the xsd_namespace index to the 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. artifact that declares it — so existing XÖV-style imports keep working. Either way the dependency graph records the link; impact analysis, versioning and search work as before. In JSON-Schema views the converted $ref points at the target DataStructure URN, which resolves on read (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. targets are converted on the fly).

Format is a representation, not an identity

The URN never encodes the 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.-authored DataStructure and a JSON Schema DataStructure share the same identity shape — the artifact-type slot is always datastructure:

urn:core:standard:xoev:datastructure:xinneres.xmeld:Meldeanschrift:1.7

Whether a given version is 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. or as JSON Schema is recorded as a stored representation of that version (format = xsd | jsonschema), never in the URN. A version 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. additionally exposes a derived JSON Schema representation, so GET …/views/json-schema works for both; the converted schema carries x-xsd-source pointing back at the DataStructure URN it was derived from. Because the format is per-version, the same DataStructure may be 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 and JSON-Schema-only in v2.

A client-supplied urn:core:…:xsd:… (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. artifact-type URN) is rejected with 400 Bad Request.

Representations and read formats

Each version exposes the formats it can be served in — its stored representations plus the derivable ones. 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. version therefore advertises both xsd and jsonschema; a JSON-authored version advertises jsonschema only (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).

• DataStructureDto.format is the authored (primary) format of the version.
• DataStructureDto.availableFormats lists every format the version can be served in (stored ∪ derivable).
• GET /api/v1/datastructures/schema?id=… returns the authored representation by default. &format=json-schema returns JSON Schema (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 converted); &format=xsd returns the raw 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., or 404 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..
• GET /api/v1/datastructures/views/json-schema?id=… is the normalized JSON-Schema read path and works for every version regardless of authored format.
• The list/search ?format= filter treats json-schema as available (so 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 DataStructures are included, since JSON Schema is derivable) and xsd as stored (only versions with an actual 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. representation).

A new version may change the authored format (e.g. 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. v1 followed by a JSON-Schema-only v2); for that v2, format=xsd then returns 404 while views/json-schema keeps working.

Runtime: format-transparent processing

So that 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. DataStructures can be used in pipelines without caring about the format, the platform handles the conversion transparently: a pipeline detects the 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. DataStructure by its format="xsd" tag and automatically selects the XML deserializer. The conversion rules follow the 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. → JSON Schema mappings described in Cross-format links. The user configures none of this explicitly.

Relationship to the XRepository import

	XRepository import	This concept
What	Translate 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. → JSON Schema	Manage 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. and JSON Schema as equals
Result	Only JSON Schema in the platform	Both formats side by side
Linking	One-way (import)	Bidirectional, cross-format
UI	Import wizard	Same editor, format tag

The two approaches complement each other. The import path remains sensible for standards where one only wants to work with JSON. Keeping the original 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. as an artifact matters especially for XÖV standards that must be processed losslessly.

A curated example of a standard data model managed this way is the OGC SensorThings model in schemas/sta/.