Home

Awesome

Digital Twins Definition Language-based RealEstateCore ontology for smart buildings

Motivation and purpose

Azure Digital Twins (ADT), and its underlying Digital Twins Definition Language (DTDL), are at the heart of Smart Building solutions built on Azure.

DTDL is the language by which developers can define the language of the entities they expect to use in their topologies. Since DTDL is a blank canvas which can model any entity, it is important to accelerate developers' time to results by providing a common domain-specific ontology to bootstrap solution building, as well as seamless integration between DTDL-based solutions from different vendors.

Our partnership with the RealEstateCore Consortium has delivered this DTDL-based ontology (or set of models) for the real estate industry, which provides common ground for modeling smart buildings while leveraging industry standards to prevent reinvention. As part of the delivery, we also provide best practices for how to consume and properly extend the ontology.

This is an open-source ontology definition which learns from, builds on, and uses industry standards, and meets the needs of solution builders in the built world. We hope it will be widely adopted and/or extended by developers, and strongly encourage active participation and contribution.

DTDL-based RealEstateCore ontology overview

This DTDL ontology is implemented based on the domain ontology RealEstateCore. RealEstateCore is a common language used to model and control buildings, simplifying the development of new services. The ontology is rich and complete, while providing simplicity and real-world applicability with proven industry solutions and partnerships. It has seen practical deployments across sizeable real estate portfolios over the past several years, and has gone through several revisions based on real-world feedback and learning. RealEstateCore specifically does not aim to be a new standard, but rather provides a common denominator and bridge with other building industry standards such as Brick Schema, Project Haystack, W3C Building Topology Ontology (W3C BOT), and more. Read more about our ontology alignment with standards.

The original RealEstateCore ontology is represented using the W3C Web Ontology Language (OWL) and it can be visualized here. It has been converted into the DTDL syntax used in this repository using our universal OWL2DTDL tool.

RealEstateCore structure

Building Ontology

RealEstateCore ontology consists of a main set of interfaces:

RealEstateCore also contains additional base interfaces:

RealEstateCore contains a number of relationship types, here we list the main ones:

Using RealEstateCore ontology

Here is a real example of a subgraph of an Azure Digital Twins instance based on this ontology:

Using the models

We have instantiated the following twins:

Below is the Azure Digital Twins query to find out all rooms' temperatures in Building 121, Level 1 which values are below 73.

SELECT Room, Sensor, Level 
    FROM DIGITALTWINS Room  
    JOIN Level RELATED Room.isPartOf
    JOIN Sensor RELATED Room.hasCapability
    JOIN Building RELATED Level.isPartOf
    WHERE IS_OF_MODEL(Room, 'dtmi:digitaltwins:rec_3_3:core:Room;1') 
    AND IS_OF_MODEL(Level, 'dtmi:digitaltwins:rec_3_3:core:Level;1')
    AND IS_OF_MODEL(Building, 'dtmi:digitaltwins:rec_3_3:core:Building;1')
    AND IS_OF_MODEL(Sensor, 'dtmi:digitaltwins:rec_3_3:core:TemperatureSensor;1')
    AND Level.levelNumber = 1 
    AND IS_DEFINED(Sensor.hasValue)
    AND Building.$dtId = 'Building121'
    AND Sensor.hasValue < 73

Another query example on above subgraph is to find the rooms which are affected by VAVs with serialNumber 2561A5510 (because it's going to be replaced).

SELECT VAV, Room 
    FROM DIGITALTWINS VAV
    JOIN Room RELATED VAV.locatedIn  
    JOIN Level RELATED Room.isPartOf
    JOIN Building RELATED Level.isPartOf
    WHERE IS_OF_MODEL(Room, 'dtmi:digitaltwins:rec_3_3:core:Room;1') 
    AND IS_OF_MODEL(Level, 'dtmi:digitaltwins:rec_3_3:core:Level;1')
    AND IS_OF_MODEL(Building, 'dtmi:digitaltwins:rec_3_3:core:Building;1')
    AND Building.$dtId = 'Building121'
    AND VAV.serialNumber ='2561A5510'

To learn more on Azure Digital Twins queries, please refer to Query the Azure Digital Twins twin graph article.

Tools to use this (and other REC based) Ontology

The tools for this Ontology have been moved to this Github repository Tools for Digital Twins Definition Language (DTDL) based Ontologies.

Extending the ontology

This is the decision tree workflow we recommend for extending and contributing to this DTDL-based RealEstateCore ontology.

Extending ontology

We encourage users to extend existing models via inheritance by using the DTDL extends property. Interface inheritance can be used to create specialized interfaces from more general interfaces. If you need to add a new interface or add additional properties, try to find the interfaces to extend from. For example, if you need to add a specialized type of room, like FocusRoom, add a new interface FocusRoom which inherits from Room interface. Through inheritance, the FocusRoom has two properties Room: the personCapacity property (from Room) and the occupied property (from FocusRoom).

[
  {
    "@id": "dtmi:digitaltwins:rec_3_3:core:Room;1",
    "@type": "Interface",
    "dtmi:dtdl:property:contents;2": {
      "@type": "Property",
      // ...
      "name": "personCapacity",
      "schema": "integer"
    },
    // ...
    "extends": "dtmi:digitaltwins:rec_3_3:core:Space;1",
    "@context": "dtmi:dtdl:context;2"
  },
  {
    "@id": "dtmi:digitaltwins:rec_3_3:core:FocusRoom;1",
    "@type": "Interface",
    "dtmi:dtdl:property:contents;2": {
      "@type": "Property",
      // ...
      "name": "occupied",
      "schema": "bool"
    },
    // ...
    "extends": "dtmi:digitaltwins:rec_3_3:core:Room;1",
    "@context": "dtmi:dtdl:context;2"
  }
]

Now that you have extended your specialized interface(s), ask yourself if your extensions are generic and could benefit other users. If the answer is yes, our recommendation is to fork the existing repository, make your changes and send a pull request (see the section below).

Contributing to ontology

We are working on improving the main interfaces, adding more interfaces in areas that we don't yet support, as well as making better tools to integrate and use the models in smart building platforms and its applications.

We encourage you to contribute to continue improving the DTDL-based RealEstateCore ontology. Please point out bugs or peculiarities, add or extend interfaces and vocabularies, and suggest improvements to evolve this ontology.

Pull requests will be evaluated based on the quality of the proposed interface models, adherence to the modeling conventions used in the repo (see below), and conceptual and roadmap compliance with the RealEstateCore OWL model project that DTDL RealEstateCore is generated from.

Modeling conventions

Alignment with standards

The DTDL-based RealEstateCore ontology accelerates developers from the “blank page” and facilitates business-to-business integrations between vendors in a smart building. Since the DTDL-based ontology is open sourced, developers can easily annotate existing models while contributing their own domain expertise. Read more about:

More about Azure Digital Twins

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Microsoft collects performance and usage information which may be used to provide and improve Microsoft products and services and enhance your experience. To learn more, review the privacy statement.

Contributors

<sub> Jönköping University: Karl Hammar <br /> Microsoft: Alina Stanciu, Brian Crawford, Bert Van Hoof, Akshay Johar, Matthew Vogel, Kevin Hilscher, Miriam Berhane Russom, OP Ravi <br /> RealEstateCore Consortium: Karl Hammar, Erik Wallin, Per Karlberg, Peter Hartlev, Joakim Eriksson <br /> Idun Real Estate Solutions: Erik Wallin, Per Karlberg <br /> Willow: Rick Szcodronski </sub>