XML/XSD Integration

A user can create, view and link 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 XSD as a DataStructure
POST /api/v1/datastructures/validate (XML body)	Dry run: well-formedness/security check of an 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 (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 URN (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 XSD:

JSON Schema	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 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 XSD — an xs:import whose namespace is the target's CORE URN. 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 URN) is instead resolved through the xsd_namespace index to the 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 (XSD targets are converted on the fly).

Format is a representation, not an identity

The URN never encodes the format. An 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 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 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 XSD in v1 and JSON-Schema-only in v2.

A client-supplied urn:core:…:xsd:… (an 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 XSD version therefore advertises both xsd and jsonschema; a JSON-authored version advertises jsonschema only (there is no JSON→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 (XSD versions converted); &format=xsd returns the raw XSD, or 404 when the version stores no 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 XSD-authored DataStructures are included, since JSON Schema is derivable) and xsd as stored (only versions with an actual XSD representation).

A new version may change the authored format (e.g. an 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 XSD DataStructures can be used in pipelines without caring about the format, the platform handles the conversion transparently: a pipeline detects the XSD DataStructure by its format="xsd" tag and automatically selects the XML deserializer. The conversion rules follow the 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 XSD → JSON Schema	Manage 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 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/.