ontouml-json2graph 1.3.2

OntoUML JSON2Graph Decoder

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

• The OntoUML JSON2Graph Transformation
  • Contents
  • Installation
  • Usage
    • Executing as a Script
      • Arguments
    • Importing as a Library
      • decode_json_project
      • decode_json_model
      • save_graph_file
    • Input and Output
    • OntoUML Vocabulary and gUFO
  • Basic Syntactical and Sematic Validation
  • Permanent URLs and Identifiers
  • Related Projects
  • Development Contribution
  • Author

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')

Related Projects

• OntoUML Metamodel: Implementation-independent OntoUML Metamodel. Unlike the UML profile, this version is independent of UML and presents only the concepts officially supported in the language. This metamodel covers the abstract and concrete syntaxes of the language and serves as the reference for all projects in the OntoUML as a Service (OaaS) ecosystem, including its different model serializations.

• OntoUML Vocabulary: An OntoUML Metamodel's serialization in Turtle (ttl) format. This vocabulary supports the serialization, exchange, and publishing of OntoUML models as graphs that can be used for Semantic Web and Linked Data applications.

• OntoUML Schema: An OntoUML Metamodel's serialization in JSON format. The JSON is a format better suited for manipulation within software code. It supports the exchange of models between modeling tools and the OntoUML server, providing model intelligent services.

• ontouml-vp-plugin: The OntoUML Plugin for Visual Paradigm adds features designed for OntoUML modelers to any version of the Visual Paradigm - a modeling editor that provides a free for non-commercial version. These features range from enabling OntoUML stereotypes in class diagrams to model verification and transformation.

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.

Author

This project is maintained by the Semantics, Cybersecurity & Services (SCS) Group of the University of Twente, The Netherlands. Its developer is:

• Pedro Paulo Favato Barcelos [GitHub] [LinkedIn]

Feel free to get in touch using the provided links. For questions, contributions, or to report any problem, you can open an issue at this repository.