OntoUML JSON2Graph

ontouml-json2graph transforms OntoUML JSON projects into RDF graphs that use the OntoUML Vocabulary. It can retain project and diagrammatic information or produce a model-only graph.

Use the command-line interface to convert files directly, or the supported Python API to obtain an RDFLib Graph. The package supports Python 3.10 or newer.

Installation

pip install ontouml-json2graph

Command-line quick start

Convert one JSON file to Turtle in the current directory:

python -m json2graph.decode -i my_ontology.json

Choose an output directory and serialization explicitly:

python -m json2graph.decode -i my_ontology.json -o results -f json-ld

Convert every .json file directly inside a directory:

python -m json2graph.decode -a -i models -o results

Display all supported options and their defaults with:

python -m json2graph.decode --help

Python quick start

from json2graph.library import decode_json_project, save_graph_file

graph = decode_json_project("my_ontology.json")
save_graph_file(graph, "my_ontology.ttl", "ttl")

The supported public API consists of:

• decode_json_project for model and diagrammatic information;
• decode_json_model for model-only output; and
• save_graph_file for explicit RDF serialization.

Important behavior

• Without an explicit base URI, the package derives a deterministic urn:uuid: namespace from the parsed JSON content.
• The default policies preserve invalid stereotypes and cardinality source values where possible, omit unresolved diagrammatic modelElement references, and warn about information that the vocabulary cannot represent.
• The correct option enables a legacy set of class and property corrections. It is independent of the explicit policy options.
• Input is decoded as UTF-8, with a warned CP1252 fallback. The package expects the OntoUML JSON structure but does not perform JSON Schema validation.
• Complete-project output is not a guarantee of lossless reconstruction. Path point order, non-empty propertyAssignments, and legacy diagrammatic Text.value content have no direct normative representation in OntoUML Vocabulary 1.1.1.

See the documentation for the complete CLI and Python guides, policy consequences, diagnostics, limitations, and 1.x-to-2.0 migration guidance.

Development

Install the project and development dependencies with Poetry:

poetry install

Run the primary validation commands from the repository root:

poetry check --strict --lock
poetry run python update_documentation.py
poetry run pytest
poetry run pre-commit run --all-files

Generated Sphinx HTML is written to docs/_build/html and is not committed.

Project links

• Documentation
• PyPI
• Releases
• Issue tracker
• OntoUML Schema
• OntoUML Vocabulary
• OntoUML Metamodel

Author and organization

The author of ontouml-json2graph is Pedro Paulo Favato Barcelos.

The project is maintained in the OntoUML organization, linked to the Semantics, Cybersecurity & Services Group at the University of Twente, The Netherlands.

The software is distributed under the Apache License 2.0.