XML/XSD Integration

A user can create, view and link XSD and JSON Schema Elements 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: Elements are format-agnostic (artifact-type=element; the format is a per-version representation), the xsd package provides parsing/conversion, and the following operations are available to a host application:

Operation	Function
ModelForge.searchXRepository(…) / importFromXRepository(…)	Search, convert and import XÖV standards
ModelForge.importFromXRepository(…) with importAsXsd=true	Store raw XSD as an Element (no JSON conversion) — XXE-hardened parsing and well-formedness checks; failures surface as import diagnostics
ModelForge.getArtifact(…)	Read the stored JSON Schema of an Element
ModelForge.getBundledView(…) / getInlinedView(…)	Normalized JSON-Schema views for any Element (XSD versions converted on read)

Schemas can also be imported from a remote URL (e.g. Smart Data Models or a raw GitHub URL). These URL imports are SSRF-guarded: private, link-local and cloud-metadata IP ranges are blocked, and DNS resolution is pinned so the host cannot be rebound to a private address between check and connect. Redirects are disabled, and the fetch is bounded by a 1 MB response cap plus connect/read timeouts.

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

The format-agnostic Element model

An Element 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	Element 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 Element
description	xs:documentation	Tooltip / description text
enum: [...]	xs:enumeration	Enumeration
oneOf: [...]	xs:choice	Alternative types

Cross-format links

In an XSD Element, a property can reference a JSON Schema Element — exactly the way two JSON Schema Elements are linked. The format of the target does not matter.

In JSON Schema:

{
  "$id": "urn:core:standard:xoev:element:xinneres.xmeld:Meldeanschrift:rbo8uzyisb",
  "x-xsd-source": "urn:core:standard:xoev:element:xinneres.xmeld:Meldeanschrift:rbo8uzyisb:1.7",
  "properties": {
    "ort": {
      "$ref": "urn:core:platform:civitas:element:common:Gemeinde:iz3eulz7nv: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 Element (of any format) and records the dependency edge:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:g="urn:core:platform:civitas:element:common:Gemeinde:iz3eulz7nv:1.0.0"
           targetNamespace="urn:example:meldeanschrift">
  <xs:import namespace="urn:core:platform:civitas:element:common:Gemeinde:iz3eulz7nv: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 for the dependency graph; impact analysis, versioning and search work as before. The JSON-Schema converter, however, maps only namespaces that are already CORE URNs: for a type from a classic XÖV namespace the converted $ref falls back to a URN minted in the importing schema's own prefix and version — an unresolved placeholder, not the imported target. This is a known limitation; the xsd_namespace index feeds the dependency edges, not the converter. Only CORE-URN imports produce a $ref that points at the target Element URN and 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 Element and a JSON Schema Element share the same identity shape — the artifact-type slot is always element:

urn:core:standard:xoev:element:xinneres.xmeld:Meldeanschrift:rbo8uzyisb: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 the normalized JSON-Schema view works for both; the converted schema carries x-xsd-source pointing back at the Element URN it was derived from. Because the format is per-version, the same Element may be XSD in v1 and JSON-Schema-only in v2.

A caller-supplied urn:core:…:xsd:… (an XSD artifact-type URN) is rejected with a validation error (IllegalArgumentException).

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).

• The authored (primary) format is recorded per version; the readable formats are the stored representations plus the derivable jsonschema.
• ModelForge.getArtifact(…) returns the stored JSON Schema; the schema views (getBundledView/getInlinedView) work for every version regardless of authored format (XSD versions converted on read). A new version may change the authored format (e.g. an XSD v1 followed by a JSON-Schema-only v2); the normalized JSON-Schema views keep working across the format change.

Runtime: format-transparent processing

So that XSD Elements can be used in pipelines without caring about the format, the platform handles the conversion transparently: a pipeline detects the XSD Element by its format="xsd" tag and automatically selects the XML deserializer. The conversion rules follow the XSD → JSON Schema mappings worked out in XRepository Integration. 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/.