jsonschema2rdf

Converts JSON Schema into SHACL shapes, an OWL ontology and SKOS concept schemes, with the mapping model of xsd2rdf.

jsonschema2rdf reads a JSON Schema and fills the SHACL shape model of xsd2rdf (xsd2rdf.shapes) as xsd2rdf fills it for an XSD: the same shape IRIs, labels, constraints and SKOS schemes. Everything after that is xsd2rdf's own code: the OWL ontology is read from the shapes (xsd2rdf.model), the -k naming policy qualifies the property IRIs, the SKOS writer makes one file per concept scheme, the shapes are checked against SHACL-SHACL and the result has the file names of xsd2rdf. So a JSON Schema and an XSD that describe the same thing give the same kind of output, and the options mean the same.

openapi2rdf builds on this package for the schemas of an OpenAPI document.

Installation

Python 3.12 or later.

pip install jsonschema2rdf

From source:

python -m pip install poetry
poetry install

jsonschema2rdf depends on xsd2rdf>=2.1.0,<3 and PyYAML.

Usage

jsonschema2rdf convert path/to/schema.json -o out

writes, as xsd2rdf does:

• schema.json.shape.ttl: the SHACL shapes
• schema.json.owl.ttl: the OWL ontology
• schema.json.skos.<Name>.ttl: one SKOS concept scheme per enum
• schema.json.provenance.ttl: with --source-provenance only

A folder converts each of its *.json files on its own. A schema may also be written in YAML (.yaml, .yml).

jsonschema2rdf validate path/to/schema.json data.ttl -o out

validates RDF data against the converted shapes, with the concept schemes added to the data (this is xsd2rdf validate; exit code 0 conforms, 1 does not, 2 a file is missing).

From Python:

from jsonschema2rdf import convert

result = convert("schema.json", use_namespace="http://data.europa.eu/949/", property_kind_qualified_iris=True)
result.shacl, result.owl, result.skos   # the graphs (xsd2rdf.Result), nothing is written yet
result.write("out")

The settings are the fields of jsonschema2rdf.Options. Progress and warnings go to the jsonschema2rdf and xsd2rdf loggers.

Options

The flags are those of xsd2rdf where the setting is the same.

xsd2rdf's --simple-type-subproperties, --source-namespaces and --namespace-map have no JSON Schema counterpart. --license has no xsd2rdf counterpart: xsd2rdf always writes the EUPL.

Mapping rules

Each rule has a fixture in tests/fixtures with its golden output and instance data that must (not) conform. <ns> is the namespace, <shapes> is <ns>shapes/. Names become IRIs as in xsd2rdf: a class name starts with a capital, a property name with a lower-case letter (-p puts has in front), characters that do not belong in an IRI become _. Labels (sh:name, rdfs:label) are made from the names by xsd2rdf's label function (CarDescriptionType → "Type of car description"), or are the schema's title.

Documents and names

Object schemas

Two node shapes that would target the same class (an inline object named like another class) are scoped as in xsd2rdf: a node shape that a property shape reaches with sh:node loses its sh:targetClass.

Arrays

Scalars

Enums

The scheme files are <schema>.skos.<Name>.ttl. Two different enums that would get the same scheme name: the second gets _2.

oneOf and anyOf

Not mapped

The shape model of xsd2rdf has no term for these, so they are reported (one warning per keyword, with the number of schemas and the first place) and left out: additionalProperties (false would be sh:closed), patternProperties, propertyNames, dependencies / dependentSchemas / dependentRequired, minProperties / maxProperties, unevaluatedProperties, not, if / then / else, oneOf / anyOf next to properties, multipleOf, items as a list (tuples). examples, readOnly, writeOnly and $comment are ignored, and so is deprecated on an enum or a scalar definition (it has no class).

The ontology

<ns> is an owl:Ontology with rdfs:label Ontology generated from <title or file name> JSON Schema, dct:title and dct:description (the schema's title and description, else that label) and dct:created, dct:issued, dct:modified.

Provenance

With --source-provenance, <schema>.provenance.ttl links each node and property shape, class, property and concept scheme to the schema it was made from with dct:source: the file (relative to the main schema) and a JSON Pointer, as a URI reference typed xsd:anyURI, for example types.json#/definitions/Ticket/properties/route. A class or property gets one value per schema it was made from. Each property shape also gets the JSON name of its property, jsonschema2rdf:jsonName (the property IRI is lower-camel and may carry has, DP or OP, so it cannot be turned back into the name). The term is defined in vocabulary/jsonschema2rdf.ttl, in the namespace https://w3id.org/jsonschema2rdf#.

Building on jsonschema2rdf

jsonschema2rdf.JsonSchemaToRDF is a subclass of xsd2rdf.XSDtoRDF. The parts that differ between JSON Schema dialects are methods that a subclass can override: named_type_name and entry_points (where the named schemas are), is_nullable, enum_values and enum_entries, discriminator_property, ontology_metadata and read. jsonschema2rdf.cli is the command line, parameterised by a Program. openapi2rdf is built this way.

Tests

poetry install
poetry run pytest

• tests/test_fixtures.py: the fixture suite, one folder per mapping rule (golden output, SHACL-SHACL, instance data, the same bytes in two runs). After an intended output change: poetry run pytest tests/test_fixtures.py --update-golden, then review the diff. Regenerate the catalogue with python tests/fixture_support.py.
• tests/test_golden.py: the real B14 schema (UIC IRS 90918-4) of the ERA telematics ontology, see tests/golden.

ruff check src tests and mypy are configured in pyproject.toml.

The fixtures are also published as a documentation site on GitLab Pages, built by the pages job on main: one page per case with the JSON Schema source, the golden output, the instance data and UML-like class diagrams of the source, the SHACL shapes and the OWL ontology, plus the mapping rules above and a summary of the B14 golden test. The site is at https://era-europa-eu.gitlab.io/private/OPDU/SOT/era-ontology/telematics/jsonschema2rdf/ (Deploy → Pages in GitLab shows the address if the project uses a unique Pages domain; the site is visible to whoever can see the project). To build it locally (Mermaid then loads from a CDN):

poetry run python docs/build_site.py public

Releasing

Releases are published to PyPI from GitLab CI.

1. Update CHANGELOG.md: move the changes to a new [X.Y.Z] - YYYY-MM-DD section and merge it to main.
2. In GitLab, create a release (Deploy → Releases → New release) with a new tag vX.Y.Z created from main. The release notes can go in its description.
3. The tag pipeline runs lint and the tests, sets the package version from the tag (v1.2.3 gives 1.2.3), builds the wheel and the sdist, and uploads them to PyPI with trusted publishing: no PyPI password or token is stored in GitLab. Only tags of the form vX.Y.Z (or X.Y.Z) build and publish.

The PyPI project has a GitLab trusted publisher with these settings (before the first release, when the project does not exist on PyPI yet, add it as a pending publisher under Your account → Publishing):

License

EUPL 1.2