The OntoUML JSON2Graph Transformation
The OntoUML JSON2Graph (ontouml-json2graph) decodes a JSON file that complies with the ontouml-schema (e.g., the ones exported by the ontouml-vp-plugin) to a graph file that complies with the ontouml-vocabulary.
When transforming a model, you can choose to represent only the core concepts of the model or include all of its information, including diagrammatic elements, as part of the knowledge graph. Additionally, users have the choice to enable basic semantic and syntactical verifications, ensuring enhanced and accurate transformation results.
This application was developed using the RDFLib and Python 3.11. The generated graph file can be serialized in the diverse formats supported by the RDFLib, which are Turtle, RDF/XML, JSON-LD, N-Triples, Notation-3, Trig, Trix, and N-Quads.
📦 PyPI Package: The transformation is conveniently available as a PyPI package, which allows users to use it as an executable script or import it as a library into other Python projects.
📚 Code Documentation: For inquiries and further information, please refer to the comprehensive docstring-generated documentation available for this project.
Contents
Installation
Before using the OntoUML JSON2Graph Decoder, you need to download and install Python. To install the application you simply need to perform the following command:
pip install ontouml-json2graph
All dependencies will be installed automatically, and you will be ready to use the ontouml-json2graph package.
Usage
After being installed, the OntoUML JSON2Graph Decoder can be used as an executable script or imported as a library into another Python project.
The output of the transformation, i.e., the graph file, will be saved into a directory named results in the same path in which the software was executed.
Executing as a Script
For executing the software, run the following command on the terminal inside the project’s folder:
python -m json2graph.decode -i [path_to_json] [OPTIONAL ARGUMENTS]
For example, to decode the JSON file my_ontology.json and save the output graph in the Turtle format, you would run the following command:
python -m json2graph.decode -i turtle my_ontology.json
You can also use the script to decode multiple JSON files. To do this, you would use the decode_all option (‘-a’ argument).
For example, to decode all the JSON files in ‘my_data’ directory you have to run the following command:
python -m json2graph.decode -a -i my_data
Arguments
The only mandatory argument is path_to_json, which must be substituted for the input file’s location on your computer.
Optional arguments provide additional features. All available ontouml-json2graph arguments can be observed below.
usage: ontouml-json2graph [-h] -i INPUT_PATH [-o OUTPUT_PATH] [-a] [-f {turtle,ttl,turtle2,xml,pretty-xml,json-ld,ntriples,nt,nt11,n3,trig,trix,nquads}]
[-l LANGUAGE] [-c] [-s] [-u BASE_URI] [-m] [-v]
OntoUML JSON2Graph Decoder. Version: 1.3.1
options:
-h, --help show this help message and exit
-i INPUT_PATH, --input_path INPUT_PATH
The path of the JSON file or directory with JSON files to be decoded.
-o OUTPUT_PATH, --output_path OUTPUT_PATH
The path of the directory in which the resulting decoded file(s) will be saved. Default is the working directory.
-a, --decode_all Converts all JSON files in the informed path.
-f {turtle,ttl,turtle2,xml,pretty-xml,json-ld,ntriples,nt,nt11,n3,trig,trix,nquads}, --format {turtle,ttl,turtle2,xml,pretty-xml,json-ld,ntriples,nt,nt11,n3,trig,trix,nquads}
Format to save the decoded file. Default is 'ttl'.
-l LANGUAGE, --language LANGUAGE
Language tag for the ontology's concepts. Default is 'None'.
-c, --correct Enables syntactical and semantic validations and corrections.
-s, --silent Silent mode. Does not present validation warnings and errors.
-u BASE_URI, --base_uri BASE_URI
Base URI of the resulting graph. Default is 'https://example.org#'.
-m, --model_only Keep only model elements, eliminating all diagrammatic data from output.
-v, --version Print the software version and exit.
More information at: https://w3id.org/ontouml/json2graph
Importing as a Library
The library.py module (full documentation) is a user-friendly component of the ontouml-json2graph package. By encapsulating complex functionalities, this library empowers users to seamlessly integrate OntoUML JSON conversion capabilities into their projects. In addition to conversion functions, the library provides a utility function for safely saving OntoUML graphs to files in the desired syntax.
The library provides the following functions for decoding OntoUML JSON data and saving OntoUML graphs to files:
decode_json_project
The decode_json_project function allows you to decode the complete OntoUML JSON data (including elements from OntoUML’s abstract and concrete syntax) into a knowledge graph that conforms to the OntoUML Vocabulary. This function provides customization options, such as specifying the base URI for ontology concepts, adding language tags, and enabling error correction. With this function domain-level and diagrammatic data are converted to Knowledge Graph.
from json2graph.library import decode_json_project
decoded_graph_project = decode_json_project(json_file_path="path/to/input.json", base_uri="https://myuri.org#",
language="en", correct=True)
decode_json_model
The decode_json_model function decodes OntoUML JSON data representing a model-level view into a knowledge graph that adheres to the OntoUML Vocabulary.
Differently from the decode_json_model, this function decodes only elements from the OntoUML’s abstract syntax. I.e., only domain-level (and not diagrammatic) data is converted to knowledge graph. It offers options for base URI, language tags, and error correction.
from json2graph.library import decode_json_model
decoded_graph_model = decode_json_model(json_file_path="path/to/input.json", base_uri="https://myuri.org#",
language="en",
correct=True)
save_graph_file
The save_graph_file utility function provides a convenient way to save an OntoUML graph as an RDF file in the desired syntax.
from json2graph.library import save_graph_file
output_file_path = "./output_graph.ttl"
syntax = "ttl" # Choose the desired syntax: "xml", "n3", "nt", etc.
save_graph_file(ontouml_graph, output_file_path, syntax)
The valid syntax options are the ones that can be parsed by the RDFLib: turtle, ttl, turtle2, xml, pretty-xml, json-ld, ntriples, nt, nt11, n3, trig, trix, and nquads.
Input and Output
This software’s **input ** is a JSON file that complies with the OntoUML Schema. This JSON file can be obtained from the ontouml-vp-plugin’s export feature. The JSON2Graph Decoder was tested to guarantee its compatibility with the JSON generated by the plugin’s version 0.5.3.
The transformation’s **output ** corresponds to the OntoUML Model serialized as a graph. The saved file information is described by the OntoUML Vocabulary and can be saved in the different formats that are supported by the RDFLib. This output graph may contain the model’s diagrammatic information or not, depending on the user’s provided arguments. The OntoUML Vocabulary documentation contains a usage overview, presenting information about all available elements, and about how to use them, including examples of SPARQL queries.
Both the input and output of the software are built upon the same metamodel, the OntoUML Metamodel, which facilitates the conversion between different representations.
OntoUML Vocabulary and gUFO
The ontouml-vp-plugin has a feature that enables an ontology to be transformed from OntoUML to a graph format. This feature is called the Model Transformation to OWL with gUFO. gUFO is a lightweight implementation of the OntoUML’s underlying foundational ontology, the Unified Foundational Ontology (UFO).
Even though an ontology represented in gUFO and in the OntoUML Vocabulary are both suitable for Semantic Web OWL 2 DL applications, these two representations are different and were created with different purposes.
gUFO is intended for reuse in the definition of UFO-based lightweight ontologies. Reuse of gUFO consists in instantiating and/or specializing the various entities defined in the ontology, inheriting from it the domain-independent distinctions of UFO. A key feature of UFO (and hence, gUFO) is that it includes two taxonomies: one with classes whose instances are individuals (classes in this taxonomy include gufo:Object, gufo:Event) and another with classes whose instances are types (classes in this taxonomy include gufo:Kind, gufo:Phase, gufo:Category).
Differently, the OntoUML Vocabulary was created to support the serialization, exchange, publishing of OntoUML as linked data, and to be used in Semantic Web applications. Models in this format are machine-readable resources intended to support the needs of tool developers and researchers, enabling the performance of complex analysis using the SPARQL querying language with no need for additional software. In addition, as it contains the concrete elements (i.e., diagrammatic data such as diagrams and diagram elements) of OntoUML projects, it can also be used to fully reconstruct the original models.
Basic Syntactical and Sematic Validation
Class validations:
Reports Class with incompatible attributes isExtensional (not ‘null’) and isPowertype (set as ‘True’).
Sets Class stereotype as ‘collective’ when the Class’s stereotype is ‘null’ and its isExtensional attribute is ‘True’.
Sets Class stereotype as ‘type’ when the Class’s stereotype is ‘null’ and its isPowertype attribute is ‘True’.
Removes the Class’s isExtensional attribute if the Class’s stereotype is not ‘collective’.
Sets the Class’s isPowertype attribute as ‘False’ if the Class’s stereotype is not ‘type’.
Sets the Class’s order attribute to ‘1’ if the Class’s stereotype is not ‘type’ and its order different from ‘1’.
Sets the Class’s order attribute to ‘2’ if the Class’s stereotype is ‘type’ and its order is ‘1’.
Reports mandatory Class stereotype missing.
Stereotype validations:
Reports invalid Class stereotype assigned (i.e., assigned stereotype is not in enumeration class ClassStereotype).
Reports invalid Relation stereotype assigned (i.e., assigned stereotype is not in enumeration class RelationStereotype).
Reports invalid Property stereotype assigned (i.e., assigned stereotype is not in enumeration class PropertyStereotype).
Property validations:
Reports invalid assertion when a Property stereotype is related to a Class that is known not to be of stereotype ‘event’.
Sets Class stereotype as ‘event’ when it is originally ‘null’ and the class is related to a Property with stereotype.
Permanent URLs and Identifiers
Repository: https://w3id.org/ontouml/json2graph
Documentation: https://w3id.org/ontouml/json2graph/docs
Releases:
All releases: https://w3id.org/ontouml/json2graph/releases
Latest release: https://w3id.org/ontouml/json2graph/latest
Specific release: https://w3id.org/ontouml/json2graph/v
, where <n> represents the version number (e.g., ‘1.0.0’)
Development Contribution
We encourage you to contribute to the development of this software.
The dependencies to develop this software are not the same as the ones to execute it. Hence, it is necessary run the following command on the terminal inside the project’s folder to install all necessary dependencies:
pip install -r requirements.txt
You also need run pre-commit install to set up the git hook scripts.
The ontouml-json2graph package was developed using test-driven-based development. Multiple tests are available inside the following folder: ontouml-json2graph/json2graph/tests. To execute the tests, run the following command from inside the project’s root folder:
pytest .\json2graph\tests\test_main.py
The tests’ code documentation is also available.