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_uri and append_content_hash for resource identity;

  • language for language-tagging source name literals;

  • correct for the legacy class and property correction pass;

  • policies for invalid stereotypes, invalid cardinalities, unresolved diagrammatic modelElement references, path-point order, and propertyAssignments; and

  • transformation_metadata for 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.