semantic_jsonsubschema

semantic_jsonsubschema checks whether one JSON Schema is a subschema of another, while extending structural checks with semantic reasoning on x-concept annotations.

This library is a fork and semantic extension of the jsonsubschema work by Habib et al. It supports the demo work submitted to the ISWC Demo Track.

Links

• Homepage: https://gitlab.emse.fr/territoire-public/semantic_jsonsubschema
• Playground demo: https://ci.mines-stetienne.fr/semantic-jsonsubschema/playground

Main features

• JSON subschema checking (s1 <: s2)
• Semantic policy control when x-concept is missing on one side
• Semantic reasoners for concept hierarchies:
  • equality
  • rdfs
  • skos
  • owl_rl
  • hermit
• Schema algebra operations:
  • meet
  • join
  • semantic equivalence (s1 <: s2 and s2 <: s1)

Installation

From PyPI:

pip install semantic_jsonsubschema

From source:

git clone https://gitlab.emse.fr/territoire-public/semantic_jsonsubschema.git
cd semantic_jsonsubschema
pip install .

For contributors:

uv sync --extra dev --extra docs

Python API quick start

from semantic_jsonsubschema import isSubschema

s1 = {"type": "integer"}
s2 = {"type": ["integer", "number"]}

print("LHS <: RHS", isSubschema(s1, s2))

Semantic context with reasoner and policy:

from rdflib import Graph

from semantic_jsonsubschema import (
    EvaluationContext,
    SemanticInclusionPolicy,
    PolicyDecision,
    SKOSReasoner,
    isSubschema,
)

graph = Graph()
graph.parse(data='''
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix ex: <https://example.org/> .

ex:MeasuredAirTemperature skos:broader ex:FluidTemperature .
''', format="turtle")

policy = SemanticInclusionPolicy(
    x_defined_y_not_defined=PolicyDecision.TRUE,
    x_not_defined_y_defined=PolicyDecision.TRUE,
    x_not_defined_y_not_defined=PolicyDecision.TRUE,
)

ctx = EvaluationContext(
    reasoner=SKOSReasoner(graph),
    semantic_inclusion_policy=policy,
)

s1 = {"type": "number", "x-concept": "https://example.org/MeasuredAirTemperature"}
s2 = {"type": "number", "x-concept": "https://example.org/FluidTemperature"}

print(isSubschema(s1, s2, ctx=ctx))

CLI quick start

Basic comparison:

semantic_jsonsubschema compare schema1.json schema2.json

Show command-level help:

semantic_jsonsubschema --help
semantic_jsonsubschema compare --help

With semantic options:

semantic_jsonsubschema compare schema1.json schema2.json \
  --reasoner skos \
  --ontology https://ci.mines-stetienne.fr/semantic-jsonsubschema/example \
  --policy-json '{"x_not_defined_y_defined": true, "x_defined_y_not_defined": true, "x_not_defined_y_not_defined": true}'

Use a policy file instead of inline JSON:

semantic_jsonsubschema compare schema1.json schema2.json \
  --reasoner owl_rl \
  --policy-file policy.json \
  --rdf-graph graph.ttl

Other operations:

semantic_jsonsubschema canonicalize schema.json
semantic_jsonsubschema simplify schema.json
semantic_jsonsubschema meet lhs.json rhs.json
semantic_jsonsubschema join lhs.json rhs.json
semantic_jsonsubschema neg schema.json

Note: simplify first canonicalizes, then simplifies. You do not need to run canonicalize manually before simplify.

Run semantic_jsonsubschema --help for all options.

Development

Run tests:

python -m unittest discover -s test -p 'test_*.py'

Run a focused test suite:

python -m unittest test.test_api test.semantic.test_api

Publication checklist

Publish on PyPI

uv build
uv publish --check-url https://upload.pypi.org/legacy/ dist/*

Publish documentation on Read the Docs

• Read the Docs config is in .readthedocs.yaml
• Sphinx docs root is docs/
• Activate the repository on Read the Docs and choose the default branch

Local docs build:

uv sync --extra docs
sphinx-build -b html docs docs/_build/html

Authorship

Main authors of this fork:

• Maxime Lefrancois
• Nicolas Berne
• Irfan Ullah
• William Charles

Upstream attribution is preserved in NOTICE.txt.

License

This project is distributed under Apache License 2.0. See LICENSE.txt.