Skip to content

Latest commit

 

History

History
70 lines (42 loc) · 3.49 KB

README.md

File metadata and controls

70 lines (42 loc) · 3.49 KB
Raw

SHACL2DTDL -- The RDF Shapes to DTDL translator

Author: Karl Hammar

The SHACL2DTDL converter is a tool that translates a SHACL ontology into a set of DTDL Interface declarations for use, e.g., with the Azure Digital Twins service.

It maps SHACL NodeShapes to DTDL Interfaces and PropertyShapes to DTDL Properties or Relationships.

Example usage

dotnet run -f C:\path-to-SHACL-file -i C:\ignore-file.csv -o C:\output-path

Options

  -f, --file-path         Required. The path to the on-disk root ontology file to translate

  -o, --outputPath        Required. The directory in which to create DTDL models.

  -m, --merged-output     Sets program to output one merged JSON-LD file for batch import into ADT.

  -i, --ignorefile        Path to a CSV file, the first column of which lists (whole or partial) IRI:s that should be ignored by this tool and not translated into DTDL output.

  -s, --ontologySource    An identifier for the ontology source; will be used to generate DTMI:s per the following design, where interfaceName is the local name of a translated NodeShape, and ontologyName is the last segment of the translated shape's namespace: <dtmi:{ontologySource}:{ontologyName}:{interfaceName};1>.

  --help                  Display this help screen.

  --version               Display version information.

Supported SHACL features

sh:NodeShape

  • Named node shapes are translated into DTDL Interfaces.
  • Anonymous node shapes are ignored.

sh:PropertyShape

  • Property shapes that have sh:Datatype set, or that have sh:NodeKind set as Literal are translated into DTDL Properties.
    • Schemas are translated from XSD -> DTDL primitives, see source for exact mapping.
  • Other property shapes are translated into DTDL Relationships.
    • As DTDL only allows a single Target definition per Relationship, we only map such properties that target singletons. More complex properties are ignored (for now).

rdfs:domain and rdfs:range

  • Data properties with a NodeShape in their rdfs:domain are translated into DTDL Properties
  • Object properties with a NodeShape in their rdfs:domain are translated into DTDL Relationships.

owl:AnnotationProperty on owl:ObjectProperty

OWL annotation properties that have an object property defined as their rdfs:domains are translated into DTDL Properties on the corresponding DTDL Relationships (see above). Per this approach, the property-graph behaviour of DTDL can be loosely emulated in OWL.

Documentation and Deprecation

  • rdfs:labels become DTDL displayNames; language tags are maintained.
  • rdfs:comments become DTDL comments; language tags are maintained.
  • Entities that are marked as deprecated (i.e., are annotated with the property owl:deprecated and the boolean value true) are ignored in translation.

DTMI Minting

DTMI:s for named shapes are minted based on the shapes' URIs by concatenating five components:

  • The "dtmi:" prefix
  • The ontology source, either given by a CLI option (-s), or generated by reverting the hostname and concatenating with the path segments excluding those that go into the ontology name or local name, see below
  • The ontology name: the last fragment of the URI before the local name
  • The local name of the shape
  • The DTMI version identifier; for now hardcoded as ";1"

E.g., https://w3id.org/rec#Building becomes dtmi:org:w3id:rec:Building;1. If the CLI option -s rec4 is given it becomes dtmi:rec4:rec:Building;1