Convert industry-standard ontologies to DTDL for Azure Digital Twins

Most ontologies are based on semantic web standards such as OWL, RDF, and RDFS.

To use a model with Azure Digital Twins, it must be in DTDL format. This article describes general design guidance in the form of a conversion pattern for converting RDF-based models to DTDL so that they can be used with Azure Digital Twins.

The article also contains sample converter code for RDF and OWL converters, which can be extended for other schemas in the building industry.

Although the examples in this article are building-focused, you can apply similar processes to standard ontologies across different industries to convert them to DTDL as well.

Conversion pattern

There are several third-party libraries that can be used when converting RDF-based models to DTDL. Some of these libraries allow you to load your model file into a graph. You can loop through the graph looking for specific RDFS and OWL constructs, and convert them to DTDL.

The following table is an example of how RDFS and OWL constructs can be mapped to DTDL.

RDFS/OWL concept	RDFS/OWL construct	DTDL concept	DTDL construct
Classes	owl:Class IRI suffix rdfs:label rdfs:comment	Interface	@type:Interface @id displayName comment
Subclasses	owl:Class IRI suffix rdfs:label rdfs:comment rdfs:subClassOf	Interface	@type:Interface @id displayName comment extends
Datatype Properties	owl:DatatypeProperty rdfs:label or INode rdfs:label rdfs:range	Interface Properties	@type:Property name displayName schema
Object Properties	owl:ObjectProperty rdfs:label or INode rdfs:range rdfs:comment rdfs:label	Relationship	type:Relationship name target (or omitted if no rdfs:range) comment displayName

The following C# code snippet shows how an RDF model file is loaded into a graph and converted to DTDL, using the dotNetRDF library.

using VDS.RDF.Ontology;
using VDS.RDF.Parsing;
using System;
using System.Collections.Generic;
using Newtonsoft.Json;

namespace DigitalTwins_Samples
{
    public class DigitalTwinsConvertRDFSample
    {

        public void Run()
        {

            Console.WriteLine("Reading file...");

            FileLoader.Load(_ontologyGraph, rdfFile.FullName);

            // Start looping through for each owl:Class
            foreach (OntologyClass owlClass in _ontologyGraph.OwlClasses)
            {

                // Generate a DTMI for the owl:Class
                string Id = GenerateDTMI(owlClass);

                if (!String.IsNullOrEmpty(Id))
                {

                    Console.WriteLine($"{owlClass.ToString()} -> {Id}");

                    // Create Interface
                    var dtdlInterface = new DtdlInterface
                    {
                        Id = Id,
                        Type = "Interface",
                        DisplayName = GetInterfaceDisplayName(owlClass),
                        Comment = GetInterfaceComment(owlClass),
                        Contents = new List<DtdlContents>(),
                    };

                    // An OWL graph can have parent/child classes.
                    // So to understand if an OWL class is a base class or a child class,
                    // look for a superclass on any given OWL class.
                    // If found, convert these to parent + child Interfaces using DTDL extends.
                    IEnumerable<OntologyClass> foundSuperClasses = owlClass.DirectSuperClasses;

                    //...
                }

                // Add interface to the list of interfaces
                _interfaceList.Add(dtdlInterface);
            }

            // Serialize to JSON
            var json = JsonConvert.SerializeObject(_interfaceList);

        }
    }
}

Converter samples

This section contains sample converter code for RDF and OWL converters, which can be extended for other schemas in the building industry.

RDF converter application

There's a sample application available that converts an RDF-based model file to DTDL Version 2 (v2). DTDL v2 is supported by Azure Digital Twins, but you can also follow these instructions to convert DTDL v2 models to the newer DTDL v3.

The sample application has been validated for the Brick schema, and can be extended for other schemas in the building industry (such as Building Topology Ontology (BOT), Semantic Sensor Network, or buildingSmart Industry Foundation Classes (IFC)).

The sample is a .NET Core command-line application called RdfToDtdlConverter.

To download the code to your machine, select the Browse code button underneath the title on the sample page, which will take you to the GitHub repo for the sample. Select the Code button and Download ZIP to download the sample as a .zip file called RdfToDtdlConverter-main.zip. You can then unzip the file and explore the code.

You can use this sample to see the conversion patterns in context, and to have as a building block for your own applications doing model conversions according to your own specific needs.

OWL2DTDL converter

The OWL2DTDL Converter is a sample code base that translates an OWL ontology into a set of DTDL interface declarations, which can be used with the Azure Digital Twins service. It also works for ontology networks, made of one root ontology reusing other ontologies through owl:imports declarations. This converter was used to translate the Real Estate Core Ontology to DTDL and can be used for any OWL-based ontology.

This sample code isn't a comprehensive solution that supports the entirety of the OWL spec, but it can give you ideas and starting code that you can use in developing your own ontology ingestion pipelines.

Next steps

Continue on the path for developing models based on ontologies: Full model development path.