JSON Schema Reference

Model Forge ships eight JSON Schemas (JSON Schema 2020-12). They define the CORE-IR artifact formats, the x-* extension vocabulary and the exchange envelope. The authoritative copies live in model-forge-runtime/src/main/resources/; the files linked here are CI-guarded copies of exactly those schemas.

The schemas are the normative definition of the CORE-IR artifact formats. They are also the source the TypeScript and Zod types in portal-frontend/src/generated/core/ are generated from. Element schemas are validated against the JSON Schema 2020-12 meta-schema on import (ModelForge.importSchema / validateSchema); the typed artifact documents (Mapping, Pipeline, …) are stored as authored — Model Forge does not validate them against these schemas on write.

Schema	$id	Download
CORE DataSet	https://civitasconnect.digital/core-dataset/v1	dataset.schema.json
CORE DataStructure	https://civitasconnect.digital/core-datastructure/v1	datastructure.schema.json
CORE Mapping	https://civitasconnect.digital/core/mapping/v1	mapping.schema.json
CORE Pipeline	https://civitasconnect.digital/core/pipeline/v1	pipeline.schema.json
CORE DataSource	https://civitasconnect.digital/core/datasource/v1	datasource.schema.json
CORE DataSink	https://civitasconnect.digital/core/datasink/v1	datasink.schema.json
CORE JSON Schema Extensions	https://civitasconnect.digital/core/extensions/v1	core-schema-extensions.schema.json
CORE Artifact Envelope	https://civitasconnect.digital/core/artifact-envelope/v1	artifact-envelope.schema.json

Elements carry no CORE-specific schema: an Element is a JSON Schema 2020-12 document and validates against the official meta-schema (https://json-schema.org/draft/2020-12/schema).

Artifact content schemas

CORE DataSet

The bracketing manifest of a coherent integration. It references its members by URN (datastructureRefs, mappingRefs, pipelineRefs, dataSourceRefs, dataSinkRefs) and stores no content inline.

Field	Type	Meaning
$schema	string (required)	https://civitasconnect.digital/core-dataset/v1
id	string (required)	Versioned CORE URN of the DataSet
title, description, version	string	Display metadata
datastructureRefs … dataSinkRefs	string[]	URNs of the referenced artifacts

See CORE-IR Reference — DataSet for the full semantics and an example manifest.

CORE DataStructure

A named, versioned grouping of Elements — records which Elements belong together (for example all entities of one imported JSON Schema document).

It is itself a JSON Schema: a $defs library with one entry per member, whose value is a $ref to that member Element's CORE URN. The Elements are stored separately; a bundled or inlined read embeds them again. An optional top-level $ref designates one member as the root shape, so a root-shaped schema can be derived for a client that needs one.

CORE Mapping

A declarative field-to-field mapping between two Elements. source and target are versioned Element URNs; fields maps target field paths to field operations (direct copy, constant, expression).

CORE Pipeline

An integration pipeline as a directed acyclic graph: nodes (typed pipeline steps) and edges (connections). debug toggles verbose engine logging.

CORE DataSource

Connector configuration feeding data into a pipeline. The schema is a oneOf over the source types that exist: MqttDataSource and SqlDataSource. Each variant carries its own fields, and element references the Element describing the payload format.

CORE DataSink

Connector configuration receiving transformed data from a pipeline. The schema is a oneOf over the sink types that exist: FrostDataSink and PostgisDataSink. element references the Element describing the output row format.

Extension vocabulary

CORE JSON Schema Extensions

Defines the x-* keywords CORE documents may carry inside JSON Schemas:

Keyword	Meaning
x-core-ref	Foreign-key annotation: the string field holds the CORE URN of another artifact. Registry-aware existence checks run on import — see CORE-IR Reference.
x-xsd-source	Points a JSON Schema projection back at the Element version that carries the source XSD representation.
x-ui-position	Editor canvas position of a modelled entity.
x-ui-styles	The editor diagram a stored model carries — nodes, edges, positions, labels. Host-owned and opaque to the registry: the import carries it verbatim and a read splits it off again. Its shape is deliberately permissive.

All x-* keywords are non-validating annotations: schema fidelity guarantees they survive storage and views verbatim.

Exchange format

CORE Artifact Envelope

Wraps one artifact content version together with its identity and metadata (artifactId, artifactType, title, labels, firstVersion) for import and exchange. Used when an artifact is transported as a self-contained file rather than through the Java facade.