Creating company specific DTDLv3 extensions

[svenna]

My company have adopted DTDLv2 as modeling language for a iot platform hosted on Azure and one thing that we found problematic with v2 was the locked nature of sematic units (and possibility to extend the core language of a model)

I was glad when i saw that v3 added them to an extension and believed that it would solve our issue as we then could create our own company-extension that exposes the specific units we need for our customers while retaining DTDL compatibility with the released tooling.

But now i am wondering if i was mistaken as much of the information released seems be around microsoft controlled extensions and i have not really found documentation on how to develop and use custom extensions.

Is it supposed to be possible to add your own extensions or will it be a Microsoft controlled package of extensions that are supported?

[thern743]

@svenna I have similar questions. That being said, the extensions are just a metamodel. You can see the annotations extension example here:

https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v3/metamodel/DTDL.FeatureExtension.annotation.v1.RDF-SHACL.json

In theory we can define our own but I'm assuming Microsoft wants us to use the annotations extension if possible. I can't imagine too many scenarios where they wouldn't be sufficient (though they could potentially get prohibitively verbose). Another thing to keep in mind is (I'm assuming) that, if we create our own extensions, they would not work with Microsoft's products such as the DTDL parser/validator. This means our solutions would have to implement the extensions natively.

[rido-min]

@svenna @thern743

In DTDL v3 the feature extensions are intended to be defined and approved in this repo, and then implemented by the parser. Both repos are open and willing to accept contributions.

I don't think annotations will serve these purposes (despite the name, the use case is to annotate payloads/instances, not models).

If any of you have any request to add any specific extension, we are more than happy to collaborate on those.

nit, wrt to this comment:

they would not work with Microsoft's products such as the DTDL parser/validator.

I'd like to clarify that the DTDLParser has been donated to the DigitalTwin consortium, so this statement is not 100% accurate.

BTW, we are also looking to an API to allow the parser to load any arbitrary extension, but we have not decided if this will enabled in v3 or future releases.

/c @briancr-ms @jrdouceur

[svenna]

@rido-min Thanks for the update! My thought was around adding a custom QuantitativeTypes extenstion for types that currently not are defined. And doing this without needing to do a PR. It is of course interesting to add them to dtdl proper here but i know as a general rule that you normally don't have time when it comes to delivering customer projects :)

But it might be as possible to actually use the ValueAnnotation just need to do a propertery ValueAnnotation and give it a name that the code parsing the model understands :)

we parse the models clientside to extract metadata already and this can be done as a ad hoc busniess rule and still be compliant with DTDLv3

Do you have any idea when DTDLv3 will be released GA?

[rido-min]

@svenna

ValueAnnotation is intended to annotate instance messages (aka the payload), not the model iteself.

You can always use adjunct types and initialize the ParsingOptions with AllowUndefinedExtensions = true

The goal of DTDL is to establish a common vocabulary to allow different services to interoperate. If you need any additional units, please let us know, so we can update the quantiativeTypes extension with those.

We are in the last steps to make DTDL v3 GA, hopefully in the upcoming weeks (not months).

[svenna]

@rido-min yeah i understand that the valueannotation is for the data and not for the model, but all systems can be abused :)

Will look into this with AlloowUndefinedExtensions to see if we can use that. And I will definitely propose new units when needed.

Thanks for the update regarding the release schedule.