Microsoft.SmartPlaces.Facilities.OntologyMapper 0.6.6-preview

Ontology Mapper

Motivation and purpose

The OntologyMapper allows developers to define conversion processes from one DTDL-based Ontology to a different DTDL-based Ontology.

This may be needed in cases where cloning a topology which uses a propriety ontology, and converting to an open standard ontology such as RealEstateCore.

These conversion rules are defined in a series of Mappings files here in the repo which are embedded in the assembly to make versioning easier.

The key is that these files describe exceptions only. If the source DTMI and Target DTMI are identical, nothing needs to appear for the mapping between the two. Thus, if an source and target use the same ontology and version, the mapping file will have very little content.

This library provides helpers useful for mapping one Digital Twins Definition Language (DTDL) model to a different DTDL model. It defines a set of classes which allow the following types to be mapped:

1. Interfaces
2. Relationships
3. Property Projections
4. Backfilling of Properties

A json file can be created with collections of these types of mappings, and then that can be used in a process which uses one DTDL ontology as an input and outputs a different DTDL ontology.

File Sections

Header

The header section is for informational purposes designating the source and destination DTDLs. This is to provide an at-a-glance summary of what DTDLs this file maps.

Input Ontologies

A collection of what ontologies make up the input source for the conversion

Output Ontologies

A collection of what ontologies make up the output source for the conversion

NamespaceRemaps

A collection of mappings from one namespace name to another namespace name. This is used after the explicit InterfaceRemaps to execute a simple search and replace of a string in an input model to convert it to an output model. That is, in those cases where the input model interface name is exactly the same as the output model interface name, but the namespace is different, then the input model''s namespace will be replaced by the NamespaceRemap's output namespace.

InterfaceRemaps

A collection of mappings from one interface name to another interface name. It is suggested that you only need to list mappings where the input DTMI is not the same as the output DTMI. Systems should assume that if a DTMI is not listed in the mappings, that the output DTMI will be the same as the input DTMI.

RelationshipRemaps

A collection of mappings from one relationship name to another relationship name. It is suggested that you only need to list mappings where the input relationship is not the same as the output relationship. Systems should assume that if a relationship is not listed in the mappings, that the output relationship will be the same as the input relationship.

PropertyProjections

A collection of mappings from one property name to another property name. It is suggested that you only need to list mappings where the input property is not the same as the output property. Systems should assume that if a property is not listed in the mappings, that the output property will be the same as the input property.

FillProperties

A collection of mappings from one or more property names to another property name so that if the output property is a required value and the input fields might be empty, that alternative fields can be used to populate the output field. It is suggested that you only need to list mappings where the input property is not the same as the output property. Systems should assume that if a property is not listed in the mappings, that the output property will be the same as the input property. Implementations should respect the order in which the input properties are specified so that the first non-empty valued input property is assigned to the output property

Sample File

  "Header": {
    "InputOntologies": [
      {
        "Name": "input-ontology-name",
        "Version": "1.0",
        "DtdlVersion": "v2"
      }
    ],
    "OutputOntologies": [
      {
        "Name": "output-ontology-name",
        "Version": "2.0",
        "DtdlVersion": "v3"
      }
    ]
  },
  "NamespaceRemaps": [
    {
      "InputDtmi": "dtmi:source-namespace:",
      "OutputDtmi": "dtmi:target-namespace:"
    },
  ],
  "InterfaceRemaps": [
    {
      "InputDtmi": "dtmi:source-namespace:source-interface-name;1",
      "OutputDtmi": "dtmi:target-namespace:target-interface;1"
    },
  ],
  "RelationshipRemaps": [
    {
      "InputRelationship": "source-relationship-name",
      "OutputRelationship": "target-relationship-name"
      "ReverseRelationshipDirection": true | false
    }
  ],
  "PropertyProjections": [
    {
      "OutputDtmiFilter": ".*",
      "OutputPropertyName": "output-property-name",
      "InputPropertyNames": [ "input-property-name1", "input-property-name2" ],
      "IsOutputPropertyCollection": true
    },
    {
      "OutputDtmiFilter": "\w*Space\w*",
      "OutputPropertyName": "output-property-name",
      "InputPropertyNames": [ "input-property-name2" ],
      "IsOutputPropertyCollection": true
    }

  ],
  "FillProperties": [
    {
      "OutputDtmiFilter": ".*",
      "OutputPropertyName": "output-property-name",
      "InputPropertyNames": [ "input-property-name1, input-property-name2" ]
    },
    {
      "OutputDtmiFilter": "\w*Space\w*",
      "OutputPropertyName": "output-property-name",
      "InputPropertyNames": [ "input-property-name2, input-property-name1" ]
    }
  ]
}

Interfaces and Classes

Interface: IOntologyMappingManager

Method: ValidateTargetOntologyMapping

Description

Validates that all Output DTMIs listed in the Interface Remaps exist in the target object model

Parameters

Returns

true if all targets are valid, otherwise false

Method: TryGetInterfaceRemapDtmi

Description

For a given DTMI from the source ontology, get the DTMI for the target ontology

Parameters

Returns

true if a remap exists, or if a namespaceremap exists for the namespace of the input dtmi, otherwise false

Method: TryGetRelationshipRemap

Description

For a given relationship from the source ontology, get the relationship for the target ontology

Parameters

Returns

true if a remap exists, otherwise false

Method: TryGetFillProperty

Description

In some cases, the contents of one input property may need to be copied to multiple other fields in the target ontology. For instance, if the target ontology requires that the name field always be populated, but the source name field may be null and the description field be more reliable, a chain of fields can be set here so that there is a priority list of fields that will backfill the name field if the input name field is null.

Parameters

Returns

true if a fillProperty exists, otherwise false

Method: TryGetPropertyProjection

Description

In some cases, a property of the input model needs to be put into a different field or collection in the target model. A declaration can be made to map the input field to the appropriate output field

Parameters

Returns

true if a propertyProjection exists, otherwise false

Interface: IOntologyMappingLoader

Method: LoadOntologyMapping

Description

Loads an OntologyMapping into memory

Parameters

None

Returns

An ontology mapping

Class: FileOntologyMappingLoader

Implements

OntologyMapper.IOntologyMappingLoader

Method: LoadOntologyMapping

Description

Loads an OntologyMapping into memory from an input file (specified in the constructor)

Parameters

None

Returns

An ontology mapping