This repository is used to maintain the custom Ontologies and associated SHACL Shapes that are used within a specific Scope. It's also used to ensure a unified process for handling the Ontologies & Shapes.
Ontologies are required, when there is a need to introduce a custom type for a Self Description which should be expressed as an OWL class. For each class a SHACL Shape must be defined, which defines the properties for the class and optional constraints.
The repository contains a folder for each domain in the project which stores Turtle files for the domain-specific Ontologies and associated SHACL Shapes.
Example files can be found in the folder example in the this repository.
This section describes the general process to apply changes to the Ontologies & SHACL Shapes.
main
branch and adds the changes (SHACL file and/or Ontology file) to the Federated Catalogue via its API (supported by Github Action)In the case you want to create a new Class which is not suitable for the existing Ontologies, you should create a new Ontology that contains this class. An Ontology describes a set of classes in a specific subject area and how they are related. A domain may contain multiple Ontologies.
NodeShape
in the SHACL file that refers to the class created in step 3 and describes its properties and their
constraintsIn the case you want to create a new Class which fits to any of the existing Ontologies in the Domain, you should add this class to the existing Ontology.
NodeShape
in the SHACL file that refers to the class created in step 1 and describes its properties and their
constraintsThis section describes guidelines that must be followed when applying changes to this repository.
-
(except the _
as separator for the suffix, see below)._ontology
.
Example: sensor_ontology.ttl
_shacl
. Example:
sensor_shacl.ttl
_instance
. Example: sensor_instance.json
. The content stored in the json file is also called claims.
Sensor
sensorType
SensorShape
sensorType
Shape
. Example: SensorShape
sh:targetClass
sh:nodeKind sh:IRI
general
Shape. Example:
@prefix general:https://github.com/GAIA-X4PLC-AAD/ontology-management-base/tree/main/general/ .
GeneralShape
as a node. Replace <your_prefix>
with the prefix of the ontology
sh:property [ sh:maxCount 1 ;
sh:minCount 1 ;
sh:node general:GeneralShape ;
# some other attributes
sh:path <your_prefix>:general ],
The CI/CD pipeline is defined in the .github/workflows
directory. The pipeline is triggered on every push to the repository as defined in the workflow. The result can be seen in the Actions
tab in the github repository.
The file VARIABLES.md will be generated automatically when a push to a non-main branch is executed. This file is existent in every subdirectory once there is a SHACL file containing properties. This should help to get a fast overview of the properties used in the SHACL files.
NOTE: the VARIABLES.md file should not be changed since it will be overwritten automatically.
The pipeline checks the syntax of the Turtle files (*.ttl
) by loading a RDF graph. If the Turtle file is not correct the pipeline fails with a detailed error message.
_instance.json
file is conform to the SHACL Shape(s)The pipeline checks if the _instance.json
file is conform to the SHACL Shape(s) defined in the corresponding SHACL file. For this all *_shacl.ttl
files in this repository are collected to be able to check against a schema not defined in the current SHACL Shape. If the instance is not conform the pipeline fails with a detailed error message.
# prepare venv (optional)
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python3 -m pip install --upgrade pip
(.venv) $ python3 -m pip install -r src/requirements_ci.txt
# execute check from CI
python3 src/check_ttl_syntax.py <path_to_ttl_file>
python3 src/check_jsonld_against_shacl_schema.py <directory name>
Example:
python3 src/check_ttl_syntax.py scenario/scenario_ontology.ttl
python3 src/check_jsonld_against_shacl_schema.py scenario
You might use
py
orpython
instead ofpython3
depending on your system.
To handle and display rdf-files, especially .ttl files, you can use an IDE with plugins. Following plugins have been experienced as being very helpful:
GeneralShape
in SensorShape
. To do this you have to temporarily copy the GeneralShape
into the SensorShape
file. This applies to all external Shapes which are not defined in the file which is loaded into the wizard._instance
file when having optional structures which have mandatory attributes.
Example: relatedData
in GeneralShape
:
[ sh:node general:LinkShape ;
sh:description "Reference to optional related assets" ;
skos:example "at hd map, link to optional surface map" ;
sh:name "relatedData" ;
sh:order 2 ;
sh:path general:relatedData ];
If relatedData
is not filled in the wizard, following block will be generated:
"general:relatedData": {
"@type": "general:Link"
}
This is obviously not conform since the mandatory files url
and type
of LinkShape
are missing. This bug will be fixed in the future.