Migration path for `customProperties` and `customTags`

[kbrnsr]

Context

We are the Smart-Campus project at NMBU (Norwegian University of Life Sciences),
building a smart campus solution on top of REC using Azure Digital Twins (ADT) as the digital twin platform.
We are currently evaluating the migration from REC 4 to REC 5.

Background

Per section 2. Excluded Properties and Relationships in the
rec5-breaking-changes.pdf bfab7a3:

customProperties and customTags have been excluded from all core classes:
Agent, Asset, BuildingElement, Collection, Event, Information, Space

We rely on both properties on Space and BuildingElement for campus-specific metadata —
customProperties for arbitrary key-value metadata, and customTags specifically for storing
boolean flags (not for traditional free-form tagging).

The same document's Migration Recommendations state:

2. Custom Properties: Implement custom properties through separate extension ontologies

Question

We would like to understand what this recommendation means in practice:

• What does a minimal extension ontology for customProperties and customTags look like?
• Is there a reference example or template for extending REC 5 core classes with custom properties?
• Should customTags (used here as boolean flags) be modeled the same way, or is there a more idiomatic REC 5 pattern for boolean attributes?
• Are there any tooling or validation guidelines for extension ontologies to ensure compatibility with REC 5 SHACL shapes?

Why this matters

Our ADT deployment uses customProperties for metadata and customTags for boolean flags
on Space and BuildingElement twins extensively.
A clear migration path would significantly reduce upgrade risk and effort for our campus deployment.

Any pointers to migration tooling, worked examples, or documentation would be appreciated.

[PeteHart]

Thank you for the detailed writeup. We basically decided to remove the customProps/Tags to allow extensions to be semantically captured rather than only exist in the implementations (hence opening for community sharing).

There's as I see it two ways to do this; either you extend in DTDL or in OWL/SHACL. Obviously the DTDL path is only relevant if you stay in Azure Digital Twins (ADT) (I'm unsure what your REC 4 to REC 5 evaluation entails).

DTDL

Since you're already on ADT, the most straightforward migration is to extend directly in DTDL using your own DTMI namespace:

Custom properties — create DTDL models that extends the REC/Brick base models and add your properties there:

{
  "@id": "dtmi:nmbu:smartcampus:Room;1",
  "@type": "Interface",
  "extends": "dtmi:org:w3id:rec:Room;1",
  "contents": [
    {
      "@type": "Property",
      "name": "costCenter",
      "schema": "string"
    },
    {
      "@type": "Property",
      "name": "bookingSystemId",
      "schema": "string"
    }
  ]
}

Tags — same pattern, just boolean properties on your extended models:

{
  "@type": "Property",
  "name": "isFireExit",
  "schema": "boolean"
},
{
  "@type": "Property",
  "name": "isAccessible",
  "schema": "boolean"
}

This is essentially what you were doing with customProperties and customTags in REC 4, except now the properties are explicitly typed and scoped to your namespace rather than buried in opaque maps. A cleaner model with the same deployment target.

OWL/SHACL

Alternatively, you can author extensions in OWL/SHACL using your own namespace and layer them onto REC classes via sh:targetClass:

@prefix nmbu: <https://nmbu.no/smartcampus#> .
@prefix rec:  <http://w3id.org/rec#> .
@prefix owl:  <http://www.w3.org/2002/07/owl#> .
@prefix sh:   <http://www.w3.org/ns/shacl#> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

# Custom property
nmbu:costCenter a owl:DatatypeProperty ;
    rdfs:label "cost center"@en ;
    rdfs:range xsd:string .

nmbu:costCenterShape a sh:PropertyShape ;
    sh:path nmbu:costCenter ;
    sh:datatype xsd:string ;
    sh:maxCount 1 .

# Boolean tag
nmbu:isFireExit a owl:DatatypeProperty ;
    rdfs:label "is fire exit"@en ;
    rdfs:range xsd:boolean .

nmbu:isFireExitShape a sh:PropertyShape ;
    sh:path nmbu:isFireExit ;
    sh:datatype xsd:boolean ;
    sh:maxCount 1 .

# Attach both to rec:Room
nmbu:RoomExtension a sh:NodeShape ;
    sh:targetClass rec:Room ;
    sh:property nmbu:costCenterShape, nmbu:isFireExitShape .

The advantage here is that you get SHACL validation, and your extensions compose cleanly with the REC core ontology for any non-ADT use cases (triple stores, SPARQL, linked data).

DTDL for REC 5

We're actively developing translation tooling that generates DTDL models from OWL/SHACL — the reverse of the pipeline that produced REC 5 with some simplifications. Once that's available, extensions authored in OWL/SHACL like the above would automatically translate to DTDL models deployable to ADT.

Summary

If you stay in ADT rely on automatically converted models from REC 5. Either extend those in your own namespace. Or specify new semantics in OWL/SHACL according to the REC 5 pattern and use the tooling to convert these as well.

A final note. Should you decide on specifying in OWL/SHACL it's much easier to formalize your extensions into REC going forward.

Hope this answers? Happy to engage in further dialogue around these topics.