Python library guide
The supported library interface exposes two decoders and one graph-writing
utility from json2graph.library.
Decode and write a complete project
The repository’s canonical example reads minimal-project.json, returns an
RDFLib graph, and writes it as Turtle. Run it from docs/examples:
"""Run the canonical ontouml-json2graph library example."""
from json2graph.library import decode_json_project, save_graph_file
graph = decode_json_project("minimal-project.json")
save_graph_file(graph, "minimal-project.ttl", "ttl")
decode_json_project returns model, project, and supported diagrammatic
resources in an RDFLib Graph. Library decoding does not write a model file;
the example calls save_graph_file explicitly.
Decode model information only
from json2graph.library import decode_json_model
graph = decode_json_model("my_ontology.json")
decode_json_model removes project and diagrammatic resources while retaining
domain-level model resources, including enumeration literals.
The accepted syntax names are listed in the Python API reference and match the CLI’s supported serializations.
Configure decoding
Both decoding functions accept the same optional controls:
base_uriandappend_content_hashfor resource identity;languagefor language-tagging sourcenameliterals;correctfor the legacy class and property correction pass;policies for invalid stereotypes, invalid cardinalities, unresolved diagrammatic
modelElementreferences, path-point order, andpropertyAssignments; andtransformation_metadatafor absent or embedded provenance.
When base_uri is omitted, a deterministic urn:uuid: namespace is derived
from the parsed JSON. When append_content_hash=True, a supplied base_uri is
treated as a parent and the content UUID is appended.
Library decoding accepts transformation_metadata="none" or "embedded".
Embedded mode returns a new graph containing model and provenance triples and
adds a generation timestamp. Sidecar mode is rejected because it requires a
file-writing operation and is available only through the CLI.
Path-order comments have no effect on model-only output because it contains no paths. Property-assignment handling applies only to elements that remain in the returned graph.
Handle warnings and errors
Library calls suppress the transformation’s informational and legacy correction
logs. They still emit Python warnings for encoding fallback, normalization,
policy decisions, and representational loss. Callers can filter or capture these
warnings with Python’s warnings module.
Invalid option values and error policies raise ValueError or a specialized
ValueError subclass. File and JSON decoding failures propagate to the caller.
See the Python API reference for signatures and parameter documentation, and Policies and configuration for exact policy consequences.