Aspect templates

Aspect templates are an abstraction over aspects sharing common features among multiple Twins. Instances of aspect templates are called virtual aspects, and rendered at runtime as if they were concrete aspects.

Purpose

There are two main advantages in using aspect templates.

  1. Scalability: field observations show that many Twins will have near-identical aspects in common. Reducing those aspects to their common features implies smaller network and persistence loads for the Digital Twin Registry.

  2. Maintainability: individuals in charge of creating and maintaining aspects can leverage the aspect templates feature to drastically reduce the number of aspects in their care.

Aspect template lifecycle

An aspect template is an abstraction over a number of traits common to multiple aspects. The variable part of an aspect template is defined in its HTTP endpoints, in the form of one or multiple placeholders in the endpoint’s URL.

  • Aspect templates are created in association with a Digital Twin Group

  • Any Twin in that group can leverage all its associated aspect templates, thus reducing the required number of concrete aspects for all Twins

  • When Twin data is requested from the Digital Twin Registry, all aspect templates within the given Twin’s group(s) are instantiated and featured with the Twin, just as if they were concrete aspects: those instances are called virtual aspects

  • Virtual aspects are runtime-only data: they display as concrete aspects but are never persisted

  • The HTTP endpoints of virtual aspects may have placeholders that are resolved at runtime, when fetching the associated Twin

  • Virtual aspects can be suppressed if they collide with any concrete aspect the given Twin features. A concrete aspect will always be favored over a colliding virtual aspect

  • A collision between a concrete aspect and a virtual aspect exists if both have an endpoint in common, sharing the same type and URL (once all applicable placeholders are resolved in the virtual aspect)

  • Aspect templates can be modified or removed from their Digital Twin Group, with immediate impact on the associated Twins' virtual aspects

  • Similarly, removing a Twin from a group implies the Twin will immediately stop featuring virtual aspects instantiated from the group’s aspect templates

URL Placeholders and syntax

The variable data in an aspect template is defined in the URLs of its HTTP endpoints, in the form of placeholders. Endpoint placeholders can leverage runtime data coming from the Twin. The table below illustrates the capabilities available for URL placeholders.

Syntax Description Path variable support Query parameter support Multiple instances support May fail to resolve at runtime Example

{twinId}

Resolves to the Twin’s ID

Yes

Yes

Yes

No

https://mydomain.com/{twinId}/?id={twinId}

{tenantId}

Resolves to the Twin’s owning tenant ID

Yes

Yes

Yes

No

https://mydomain.com/{tenantId}/?id={tenantId}

{localIdentifier=(<key1>,<key2>,<keyN>)}

Resolves to a 1+ sequence of key-value pairs matched by the Twin’s Local Identifier having the exact set of keys referenced in the sequence

No

Yes

Yes

Yes

https://mydomain.com/?{localIdentifier=(<key1>,<key2>,<keyN>)}

{twinCategory}

Resolves to the Twin’s category

Yes

Yes

Yes

Yes

https://mydomain.com/{twinCategory}/?twinCategory={twinCategory}

{twinType}

Resolves to the Twin’s type

Yes

Yes

Yes

Yes

https://mydomain.com/{twinType}/?twinType={twinType}

Local Identifier sequences

The placeholder Local Identifier key sequence deserves a few extra words on its own.

Firstly, given that Local Identifier sequences are made to resolve into key-value assignments, they are only available as query parameters (i.e., not also as path variables, like the other sequences).

Secondly, in order for the sequence to resolve, the set of keys referenced in it must match one of the Twin’s Local Identifiers' featured keys exactly.

The table below illustrates a few usage cases, assuming a Twin with one Local Identifier featuring the following key/values:

  • key1 → value1

  • key2 → value2

Sequence in endpoint Resolution Explanation

{localIdentifier=(<key1>,<key2>)}

key1=value1&key2=value2

Exact match, resolves with given values

{localIdentifier=(<key1>)}

{localIdentifier=(<key1>)}

Local Identifier features a super-set of the referenced keys → does not resolve

{localIdentifier=(<key1>, <key2>,<key3>)}

{localIdentifier=(<key1>, <key2>,<key3>)}

Local Identifier features a sub-set of the referenced keys → does not resolve

Validation

  • The endpoint placeholders are validated syntactically upon creating or modifying an aspect template

  • The URI syntax of the endpoint is also validated for convenience

  • The validation of the URI syntax temporarily ignores the curly brackets surrounding path variable placeholders

  • This static validation does not attempt to resolve any data, therefore referencing a Local Identifier key that is not present in a Twin featuring the given aspect template will not result in an invalid aspect template

Resolution

  • Both {twinId} and {tenantId} placeholders will always resolve to their respective values from the Twin

  • The {localIdentifier=(<key1>,<key2>,<keyN>)} may not successfully resolve if the Twin does not have a Local Identifier whose set of keys matches the set of keys used in the placeholder reference

  • {twinCategory} and {twinType} may not successfully resolve if the Twin does not have these fields

  • In those cases, the placeholder will not be substituted, thus resulting in an invalid URL at runtime for the endpoint of the given virtual aspect, which will be displayed as-is instead of producing an error response

Suppression

Virtual aspects (i.e., aspect templates instantiated and resolved at runtime) behave just like concrete aspects.

In other words, when retrieving a Twin, the section of the response body listing its aspects will display both the concrete aspects the Twin features, and the instantiated virtual aspects coming from the Twin’s Group membership(s), seemingly as they were all the Twin’s own aspects.

A simple way to tell a concrete aspect from a virtual aspect lies in the fact that virtual aspects always feature a "nil" ID (i.e., a UUID made entirely of 0s).

In some cases, the Twin may not feature the number of aspects one would expect.

This can happen when a collision is detected between a concrete aspect and a virtual aspect, or between two virtual aspects.

The rules governing those collisions and determining whether any virtual aspect will be suppressed can be summarized as follows:

  • Two aspects collide with one another if they feature at least one colliding endpoint, while also having the same Aspect Model reference

  • In turn, two endpoints collide with one another when they feature the same endpoint type and URL (for virtual aspects, after placeholders have been resolved)

  • Concrete aspects are always favored over virtual aspects when a collision occurs

As the resolution of endpoint placeholders in aspect templates occurs at runtime, it is impossible to validate in advance whether a given aspect template will collide with other aspect templates or with a Twin’s concrete aspects.

Examples

This section illustrates a series of examples on how an aspect template’s HTTP endpoint will either:

  • Fail to validate (preventing the end user from creating or modifying the aspect template), or

  • Successfully resolve at runtime, or

  • Leniently fail to fully resolve at runtime (only applicable to Local Identifier sequences)

In this example, the Twin against which the virtual aspects are resolved has the following properties:

Property

Value

Twin ID

01234567-8901-2345-6789-012345678901

Owning tenant ID

12345678-9012-3456-7890-123456789012

Local Identifier key key1

value1

Local Identifier key key2

value2

Twin category

category1

Twin type

type1

The table below displays a non-exhaustive list of examples:

Example

Validation

Resolution

Explanation

http://mydomain.com/{tenantId}/{twinId}?{localIdentifier=(<key1>,<key2>)}

Pass

http://mydomain.com/12345678-9012-3456-7890-123456789012/01234567-8901-2345-6789-012345678901?key1=value1&key2=value2

Tenant and Twin IDs are resolved as path variables. Both key1 and key2 are present in the Twin’s Local Identifiers, therefore they can be resolved

http://mydomain.com/{twinCategory}/{twinType}

Pass

http://mydomain.com/category1/type1

Twin category and type are resolved as path variables

http://mydomain.com/{tenantId}/?twinId={twinId}&twinType={twinType}&twinCategory={twinCategory}

Pass

http://mydomain.com/12345678-9012-3456-7890-123456789012/?twinId=01234567-8901-2345-6789-012345678901&twinType=type1&twinCategory=category1

Tenant ID is resolved as a path variable. Twin ID, type and category are resolved as query parameters with the given keys

http://mydomain.com/{tenantId}/?{localIdentifier=(<key1>)}&{localIdentifier=(<key2>)}

Pass

http://mydomain.com/12345678-9012-3456-7890-123456789012/?key1=value1&key2=value2

Multiple Local Identifier sequences are supported. However, they require query parameter separators between one another

http://mydomain.com/{tenantId}/?{localIdentifier=(<key1>)}{localIdentifier=(<key2>)}

Pass

http://mydomain.com/12345678-9012-3456-7890-123456789012/?key1=value1key2=value2

The only difference with the previous example is that the Local Identifier sequences have not been separated with &. As a result, the endpoint is valid but it will resolve into an invalid URL at runtime

http://mydomain.com/{localIdentifier=(<key1>,<key2>)}/?twinId={twinId}

Fail

n/a

Local Identifier placeholder sequences can only be used as query parameters

http://mydomain.com/{tenant Id}/

Fail

n/a

Malformed tenant ID placeholder

http://mydomain.com/{twinId/

Fail

n/a

Malformed Twin ID placeholder

http://mydomain.com/{tenantId}/?{localIdentifier=(<key1>,<key3>)}

Pass

http://mydomain.com/12345678-9012-3456-7890-123456789012/?{localIdentifier=(<key1>,<key3>)}

The endpoint is valid, but the runtime cannot resolve key3 for the given Twin, so the whole sequence is not resolved

http://mydomain.com/{localIdentifier=key; key2}

Fail

n/a

Incorrect Local Identifier sequence placeholder syntax

Troubleshooting

  • In case of any doubt about failed validation of an aspect template due to the syntax of one of its URL endpoint templates, please refer to the "URL Placeholders and syntax" section above.

  • If one or multiple Local Identifier sequences are not resolved at runtime, introspect the Twin’s Local Identifiers and ensure the referenced keys are present