Skip to content

Commit

Permalink
Merge pull request #188 from Azure/dtdl-v4-release
Browse files Browse the repository at this point in the history 
Release DTDL v4
  • Loading branch information
@jrdouceur
jrdouceur authored Dec 12, 2024
2 parents fac8c2f + 7033bec commit f8ab999
Show file tree
Hide file tree
Showing 2,663 changed files with 232,878 additions and 46,632 deletions.
16 changes: 10 additions & 6 deletions DTDL/v2/DTDL.Specification.v2.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ It is based on [JSON-LD](https://json-ld.org/spec/FCGS/json-ld/20180607/), which
DTDL can be understood and validated without knowing RDF or JSON-LD, and the present document specifies DTDL without reference to either of these other standards.
DTDL cannot be readily understood without a basic knowledge of JSON; however, JSON syntax is fortunately straightforward, in marked contrast to the size, complexity, and subtlety of JSON-LD.

Within this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in IETF [RFC 2119](https://tools.ietf.org/search/rfc2119) as updated by [RFC 8174](https://tools.ietf.org/search/rfc8174), per [BCP 14](https://tools.ietf.org/search/bcp14).
Within this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in IETF [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) as updated by [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174), per [BCP 14](https://www.rfc-editor.org/info/bcp14).
Although these IETF documents make no distinction between the meaning of "MUST" and "SHALL", in the present document a violation of a "MUST" requirement indicates an **invalid** model, whereas a violation of a "SHALL" requirement indicates an **incomplete** model.
See [Model completeness](#model-completeness) for a description of this distinction.

Expand All @@ -51,7 +51,7 @@ Following is a complete set of JSON terms with concise definitions:
* value — an object OR array OR string OR number OR boolean OR null

For brevity and simplicity, the definitions above — particularly for number and string — are succinct to the point of imprecision.
See IETF [RFC 8259](https://tools.ietf.org/search/rfc8259) for more details on JSON syntax.
See IETF [RFC 8259](https://www.rfc-editor.org/rfc/rfc8259) for more details on JSON syntax.
Note that the term "boolean" is never used in the JSON spec; the paired terms "true" and "false" are always used instead.
Another term not used in the JSON spec is "integer", which herein will mean an integral number expressible in 4 bytes.

Expand Down Expand Up @@ -169,8 +169,8 @@ If the definition of this extension is not known, the model is contextually inco
```json
{
"@context": [
"dtmi:dtdl:context;2",
"dtmi:example:someExtensionContext;1"
"dtmi:dtdl:context;2",
"dtmi:example:someExtensionContext;1"
],
"@id": "dtmi:example:someInterface;1",
"@type": "Interface",
Expand Down Expand Up @@ -1628,10 +1628,14 @@ In addition to the direct requirements on members of various [DTDL elements](#dt
Specifically:

* There [MUST NOT](spec/Requirement-ClassArrayPropertiesElementSchemaSchemaMaxDepthV2.json) be more than 5 "elementSchema" or "schema" members in any path from a DTDL [Array](#array) element to another DTDL element.
* There [MUST NOT](spec/Requirement-ClassArrayPropertiesElementSchemaSchemaSelfReferenceV2.json) be a path from a DTDL [Array](#array) element wherein some "elementSchema" or "schema" member referentially includes the DTDL Array element where the path begins.
* There [MUST NOT](spec/Requirement-ClassComponentPropertiesSchemaContentsExcludeComponentV2.json) be a path of "schema" or "contents" members from any DTDL [Component](#component) element to any DTDL [Component](#component) element.
* There [MUST NOT](spec/Requirement-ClassInterfacePropertiesExtendsMaxDepthV2.json) be more than 10 members in any path of "extends" members from a DTDL [Interface](#interface) element to another DTDL element.
* There [MUST NOT](spec/Requirement-ClassInterfacePropertiesExtendsSelfReferenceV2.json) be a path of "extends" members from a DTDL [Interface](#interface) element to the DTDL Interface element where the path begins.
* There [MUST NOT](spec/Requirement-ClassMapPropertiesElementSchemaSchemaMaxDepthV2.json) be more than 5 "elementSchema" or "schema" members in any path from a DTDL [Map](#map) element to another DTDL element.
* There [MUST NOT](spec/Requirement-ClassMapPropertiesElementSchemaSchemaSelfReferenceV2.json) be a path from a DTDL [Map](#map) element wherein some "elementSchema" or "schema" member referentially includes the DTDL Map element where the path begins.
* There [MUST NOT](spec/Requirement-ClassObjectPropertiesElementSchemaSchemaMaxDepthV2.json) be more than 5 "elementSchema" or "schema" members in any path from a DTDL [Object](#object) element to another DTDL element.
* There [MUST NOT](spec/Requirement-ClassObjectPropertiesElementSchemaSchemaSelfReferenceV2.json) be a path from a DTDL [Object](#object) element wherein some "elementSchema" or "schema" member referentially includes the DTDL Object element where the path begins.
* A DTDL [Property](#property) element [MUST NOT](spec/Requirement-ClassPropertyPropertiesSchemaExcludeArrayV2.json) be an ancestor of any DTDL element with a "schema" member that includes or referentially includes a DTDL [Array](#array) element.
* A DTDL [Property](#property) element [MUST NOT](spec/Requirement-ClassPropertyPropertiesSchemaExcludeArrayImplicantV2.json) be an ancestor of any DTDL element with a "schema" member that includes any string from the [Geospatial schemas](#geospatial-schemas) table.

Expand Down Expand Up @@ -2495,8 +2499,8 @@ The active context of the DTDL Relationship element is the set { "dtmi:dtdl:cont
```json
{
"@context": [
"dtmi:dtdl:context;2",
"dtmi:ex:foo;2"
"dtmi:dtdl:context;2",
"dtmi:ex:foo;2"
],
"@id": "dtmi:ex:anInterface;1",
"@type": "Interface",
Expand Down
26 changes: 13 additions & 13 deletions DTDL/v2/DTDL.iotcentral.v2.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,15 @@ The chart below lists constraints on properties of a Property or a Telemetry tha

| Property | Limits |
| --- | --- |
| `schema` | must have type [Enum](#enum) |
| `schema` | must have type Enum |

### State examples

```json
{
"@context": [
"dtmi:dtdl:context;2",
"dtmi:iotcentral:context;2"
"dtmi:dtdl:context;2",
"dtmi:iotcentral:context;2"
],
"@id": "dtmi:com:example:Monitor;1",
"@type": "Interface",
Expand Down Expand Up @@ -70,8 +70,8 @@ The chart below lists constraints on properties of an element that is co-typed E
```json
{
"@context": [
"dtmi:dtdl:context;2",
"dtmi:iotcentral:context;2"
"dtmi:dtdl:context;2",
"dtmi:iotcentral:context;2"
],
"@id": "dtmi:com:example:Alarm;1",
"@type": "Interface",
Expand Down Expand Up @@ -100,8 +100,8 @@ The chart below lists constraints on properties of an element that is co-typed L
```json
{
"@context": [
"dtmi:dtdl:context;2",
"dtmi:iotcentral:context;2"
"dtmi:dtdl:context;2",
"dtmi:iotcentral:context;2"
],
"@id": "dtmi:com:example:Tracker;1",
"@type": "Interface",
Expand Down Expand Up @@ -136,8 +136,8 @@ The chart below lists constraints on properties of an element that is co-typed V
```json
{
"@context": [
"dtmi:dtdl:context;2",
"dtmi:iotcentral:context;2"
"dtmi:dtdl:context;2",
"dtmi:iotcentral:context;2"
],
"@id": "dtmi:com:example:Speedometer;1",
"@type": "Interface",
Expand Down Expand Up @@ -173,8 +173,8 @@ The chart below lists constraints on properties of an element that is co-typed A
```json
{
"@context": [
"dtmi:dtdl:context;2",
"dtmi:iotcentral:context;2"
"dtmi:dtdl:context;2",
"dtmi:iotcentral:context;2"
],
"@id": "dtmi:com:example:Accelerometer;1",
"@type": "Interface",
Expand Down Expand Up @@ -204,8 +204,8 @@ The version restrictions described above apply only to co-types of adjunct types
```json
{
"@context": [
"dtmi:dtdl:context;2",
"dtmi:iotcentral:context;2"
"dtmi:dtdl:context;2",
"dtmi:iotcentral:context;2"
],
"@id": "dtmi:com:example:Locator;1",
"@type": "Interface",
Expand Down
18 changes: 10 additions & 8 deletions DTDL/v2/DTDL.v2.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

**Version 2**

This version of DTDL is used for [Azure Digital Twins](https://azure.microsoft.com/services/digital-twins/) and [IoT Plug and Play](https://aka.ms/iotpnp).
This version of DTDL is used for [Azure Digital Twins](https://azure.microsoft.com/services/digital-twins/) and [IoT Plug and Play](https://aka.ms/iotpnp).

> Note: Since April 2023, DTDL v3 is the latest supported version in Azure products and services (except IoT Central)
Expand Down Expand Up @@ -55,6 +55,7 @@ For example, properties that are semantically annotated as "temperature" can be
When writing a digital twin definition, it's necessary to specify the version of DTDL being used.
Because DTDL is based on JSON-LD, we use the JSON-LD context (the `@context` statement) to specify the version of DTDL being used.
For DTDL version 2, the appropriate context specifier is "dtmi:dtdl:context;2".
See the [Context](#context) section for more details.

## Interface

Expand Down Expand Up @@ -462,9 +463,9 @@ A full set of primitive data types are provided and can be specified directly as
| `boolean` | a boolean value |
| `date` | a date in ISO 8601 format, per [RFC 3339](https://tools.ietf.org/html/rfc3339) |
| `dateTime` | a date and time in ISO 8601 format, per [RFC 3339](https://tools.ietf.org/html/rfc3339) |
| `double` | a finite numeric value that is expressible in IEEE 754 double-precision floating point format, conformant with xsd:double |
| `double` | a finite numeric value that is expressible in IEEE 754 double-precision floating point format, conformant with the numeric range of xsd:double |
| `duration` | a duration in ISO 8601 format |
| `float` | a finite numeric value that is expressible in IEEE 754 single-precision floating point format, conformant with xsd:float |
| `float` | a finite numeric value that is expressible in IEEE 754 single-precision floating point format, conformant with the numeric range of xsd:float |
| `integer` | a signed integral numeric value that is expressible in 4 bytes |
| `long` | a signed integral numeric value that is expressible in 8 bytes |
| `string` | a UTF8 string |
Expand All @@ -476,8 +477,9 @@ Complex schemas are designed for supporting complex data types made up of primit
In DTDL v2, the complex schemas are [Array](#array), [Enum](#enum), [Map](#map), and [Object](#object).
A complex schema can be specified directly as the value of a schema property or described in the Interface schemas set and referenced in a schema property.

Complex schema definitions are recursive.
Complex schema definitions are recursive but not self-referential.
An Array's elementSchema may be Array, Enum, Map, Object, or any of the [primitive schema](#primitive-schema) types.
However, the elementSchema must not refer to the Array itself or to another complex schema that refers to the Array.
The same is true for a Map's mapValue's schema and an Object's field's schema.
For DTDL v2, the maximum depth of nested complex schemas is 5 levels.

Expand Down Expand Up @@ -644,7 +646,7 @@ The chart below lists the properties that a MapKey may have.
| `description` | optional | localizable *string* | max 512 characters | A localizable description for display. |
| `displayName` | optional | localizable *string* | max 64 characters | A localizable name for display. |
| `name` | required | *string* | max 64 characters; contains only alphanumerics and underscore, starting with a letter, ending with alphanumeric | The programming name of the element. |
| `schema` | required | [String](#string) | must be *string* | The data type of the Map's key, which must be string. |
| `schema` | required | [primitive schema](#primitive-schema) | must be *string* | The data type of the Map's key, which must be string. |

### MapValue

Expand Down Expand Up @@ -1007,7 +1009,7 @@ IRIs in DTDL are [JSON-LD IRIs](https://w3c.github.io/json-ld-syntax/#iris) and
Some string properties in models are meant for display and, therefore, support localization.
Digital twin models use JSON-LD's string internationalization support for localization.
Each localizable property (e.g. `displayName` and `description`) is defined to be a JSON-LD language map (`"@container": "@language"`).
The keys of the language map must be language tag strings (see [BCP 47](https://tools.ietf.org/html/bcp47)).
The keys of the language map must be language tag strings (see [BCP 47](https://www.rfc-editor.org/info/bcp47)).
[ISO 639](https://www.loc.gov/standards/iso639-2/php/code_list.php) provides a list of language tags.
The default language for DTDL documents is English.

Expand Down Expand Up @@ -1078,7 +1080,7 @@ By contrast, if the undefined co-type "Commercial" were not present in the above

## Language extensions

DTDL also supports a selection of [language extensions](../v3/DTDL.Extensions.md), which offer additional functionality beyond what is provided by the core DTDL language.
DTDL also supports a selection of [language extensions](../v4/DTDL.Extensions.md), which offer additional functionality beyond what is provided by the core DTDL language.
The chart below lists the language extensions that are currently available for use with DTDL version 2.

| Extension | Category | Description |
Expand All @@ -1103,7 +1105,7 @@ The chart below lists the language extensions that are currently available for u
## References

* JSON-LD: JSON-LD 1.1 - https://json-ld.org/spec/latest/json-ld/
* Language codes: BCP47 - https://tools.ietf.org/html/bcp47
* Language codes: BCP47 - https://www.rfc-editor.org/info/bcp47
* RDF (Resource Description Framework): RDF Concepts and Abstract Syntax - http://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/
* RDF Schema: RDF Schema 1.1 - http://www.w3.org/TR/rdf-schema/

4 changes: 2 additions & 2 deletions DTDL/v2/metamodel/DTDL.v2.ModelElements.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
"@type": "Double",
"displayName": "double",
"description": {
"en-US": "a finite numeric value that is expressible in IEEE 754 double-precision floating point format, conformant with xsd:double"
"en-US": "a finite numeric value that is expressible in IEEE 754 double-precision floating point format, conformant with the numeric range of xsd:double"
}
},
{
Expand All @@ -23,7 +23,7 @@
"@type": "Float",
"displayName": "float",
"description": {
"en-US": "a finite numeric value that is expressible in IEEE 754 single-precision floating point format, conformant with xsd:float"
"en-US": "a finite numeric value that is expressible in IEEE 754 single-precision floating point format, conformant with the numeric range of xsd:float"
}
},
{
Expand Down
20 changes: 10 additions & 10 deletions DTDL/v2/spec/Allowance-ClassArrayOptionalPropertiesV2.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@
"input": [
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:example:kappa_um;1",
"@id": "dtmi:example:mu_psi;1",
"@type": "Interface",
"contents": {
"@type": "Telemetry",
"name": "kappa_wum",
"name": "mu_chi",
"schema": {
"@context": [],
"@type": "Array",
Expand All @@ -29,11 +29,11 @@
"input": [
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:example:kappa_fuddle;1",
"@id": "dtmi:example:mu_yuzz;1",
"@type": "Interface",
"contents": {
"@type": "Telemetry",
"name": "kappa_humpf",
"name": "mu_omega",
"schema": {
"@type": "Array",
"elementSchema": "time"
Expand All @@ -50,10 +50,10 @@
"input": [
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:example:kappa_nuh;1",
"@id": "dtmi:example:mu_um;1",
"@type": "Interface",
"schemas": {
"@id": "dtmi:example:kappa_glikk;1",
"@id": "dtmi:example:mu_wum;1",
"@type": "Array",
"elementSchema": "boolean"
}
Expand All @@ -68,10 +68,10 @@
"input": [
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:example:kappa_quan;1",
"@id": "dtmi:example:mu_fuddle;1",
"@type": "Interface",
"schemas": {
"@id": "dtmi:example:kappa_snee;1",
"@id": "dtmi:example:mu_humpf;1",
"@type": "Array",
"elementSchema": "date"
}
Expand All @@ -86,10 +86,10 @@
"input": [
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:example:kappa_spazz;1",
"@id": "dtmi:example:mu_nuh;1",
"@type": "Interface",
"schemas": {
"@id": "dtmi:example:kappa_thnad;1",
"@id": "dtmi:example:mu_glikk;1",
"@type": "Array",
"elementSchema": "dateTime"
}
Expand Down
8 changes: 4 additions & 4 deletions DTDL/v2/spec/Allowance-ClassArrayPropertyCommentDtmiV2.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,13 @@
"input": [
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:example:xi_sigma;1",
"@id": "dtmi:example:pi_sigma;1",
"@type": "Interface",
"schemas": {
"@id": "dtmi:example:xi_pi;1",
"@id": "dtmi:example:pi_pi;1",
"@type": "Array",
"dtmi:dtdl:property:comment;2": "xi_rho",
"elementSchema": "double"
"dtmi:dtdl:property:comment;2": "pi_rho",
"elementSchema": "float"
}
}
]
Expand Down
8 changes: 4 additions & 4 deletions DTDL/v2/spec/Allowance-ClassArrayPropertyDescriptionDtmiV2.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,15 @@
"input": [
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:example:pi_gamma;1",
"@id": "dtmi:example:sigma_gamma;1",
"@type": "Interface",
"schemas": {
"@id": "dtmi:example:pi_alpha;1",
"@id": "dtmi:example:sigma_alpha;1",
"@type": "Array",
"dtmi:dtdl:property:description;2": [
"pi_beta"
"sigma_beta"
],
"elementSchema": "float"
"elementSchema": "long"
}
}
]
Expand Down
8 changes: 4 additions & 4 deletions DTDL/v2/spec/Allowance-ClassArrayPropertyDisplayNameDtmiV2.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,15 @@
"input": [
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:example:rho_nuh;1",
"@id": "dtmi:example:tau_nuh;1",
"@type": "Interface",
"schemas": {
"@id": "dtmi:example:rho_fuddle;1",
"@id": "dtmi:example:tau_fuddle;1",
"@type": "Array",
"dtmi:dtdl:property:displayName;2": [
"rho_glikk"
"tau_glikk"
],
"elementSchema": "long"
"elementSchema": "time"
}
}
]
Expand Down
4 changes: 2 additions & 2 deletions DTDL/v2/spec/Allowance-ClassArrayPropertyElementSchemaDtmiV2.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,10 @@
"input": [
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:example:kappa_rho;1",
"@id": "dtmi:example:mu_nu;1",
"@type": "Interface",
"schemas": {
"@id": "dtmi:example:kappa_pi;1",
"@id": "dtmi:example:mu_mu;1",
"@type": "Array",
"dtmi:dtdl:property:elementSchema;2": "date"
}
Expand Down
6 changes: 3 additions & 3 deletions DTDL/v2/spec/Allowance-ClassArrayPropertyInvalidDtmiV2.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,15 @@
"input": [
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:example:sigma_wum;1",
"@id": "dtmi:example:upsilon_wum;1",
"@type": "Interface",
"schemas": {
"@id": "dtmi:example:sigma_yuzz;1",
"@id": "dtmi:example:upsilon_yuzz;1",
"@type": [
"Array",
"Foobar"
],
"elementSchema": "double",
"elementSchema": "float",
"dtmi:foo//bar": 626
}
}
Expand Down
Loading

0 comments on commit f8ab999

Please sign in to comment.