Thing Description Playground

This is an example of the most basic form of a td.

In some cases binary data is embedded in text-based values, e.g., a JSON string-based value embeds a base64 encoded image. The terms contentMediaType and contentEncoding can be used to clarify the context and encoding format of such name-value pairs.

The contentType member is used to assign a media type [RFC2046] including media type parameters as attribute-value pairs separated by a ; character.

A basic TD with all default values.

This is an example for proper form serialization.

A member with the name @context and a value of type string is generally used to identify the TD representation format version defined by this specification.

All name-value pairs of a map of PropertyAffordance instances MUST be serialized as members of the JSON object that results from serializing the Map.

readOnly can be used to signal which data items are exchanged in read interactions (i.e., when reading a Property).

writeOnly can be used to signal which data items are exchanged in write interactions (i.e., when writing a Property).

All name-value pairs of a Map of ActionAffordance instances MUST be serialized as members of the JSON object that results from serializing the Map.

In some use cases, the form metadata of the Interaction Affordance not only describes the request, but also provides metadata for the expected response. The response must be a JSON object and contain a contentType.

All name-value pairs of a Map of EventAffordance instances MUST be serialized as members of the JSON object that results from serializing the Map.

CoAP supports block-wise transfers to allow large resource representations to be transferred between clients and servers. This feature enables clients and servers to request or provide resource representations in smaller blocks, which can be useful when constrained network conditions make it undesirable to transfer large amounts of data at once.

A cov:blockwise or cov:quickblockwise member may indicate relevant parameters, such as the largest block size that may be used in a Block2 Option.

Content negotiation in CoAP is used to negotiate the representation of CoAP resources that may have different representations available. This is accomplished through the use of CoAP Accept and Content-Format options. The CoAP Accept option is used by clients to request a particular content format, while the Content-Format option is used by clients and servers to indicate the content format of the representation in requests and responses, respectively.

The CoAP Hop-Limit option [RFC8768] limits the number of hops a CoAP message can take before it is considered undeliverable. This prevents infinite message loops in CoAP networks. The cov:hopLimit member can be used to set the desired hop limit for a particular CoAP request.

CoAP provides a mechanism for clients to *observe* resources [RFC7641], i.e., to request notifications from the server whenever the resource changes. This is especially useful in the Web of Things where many Things are expected to have resources that change over time, such as sensor readings.

A simple Thing Description using CoAP. The target resource is specified in the Thing Description by the href member of a form and the request method (e.g., GET, PUT, POST, or DELETE) is specified using the cov:method member of a form.

A simple Thing Description using CoAP. The target resource is specified in the Thing Description by the href member of a form and the request method (e.g., GET, PUT, POST, or DELETE) is specified using the cov:method member of a form.

This example shows the binding of the readproperty operation for the HTTP.

This example shows the default values for Procol Binding based on HTTP.

This is an example of an extended version when using multiple operations with Modbus.

To describe forms with multiple operations types, the Entity keyword can be used to create a short description of the modbus endpoint. This example shows how to use the read and write property in a single coil.

This example shows the minimal set of terms to configure a single coil reading using Modbus. Notice that the unitID is contained in the href as the first element of the path.

In the case of a forms entry that has multiple op values the usage of the htv:methodName is not permitted. A TD Processor will extend the multiple op values to separate forms entries and associates a single operation with the default assumption.

protocols may have defined Subprotocols that can be used for some interaction types. For example, to receive asynchronous notifications using HTTP, some servers may support long polling.

OAuth 2.0 makes use of scopes. These are identifiers that may appear in tokens and must match with corresponding identifiers in a resource to allow access to that resource.

It is possbile to simplify how security parameters are included in the payload by using the feature that the location referenced by a JSON pointer in a body location will be automatically inserted if it does not exist.

This in an example on how to include security parameters along with the payload.

API key can be included in the request to the Thing in different ways. One way it can be used, is as a URI template where the API key should be replaced in the URI when sending an HTTPS request.

A simple security configuration specifying basic username/password authentication in the header.

Multiple intances of API security schemes are also possible. These must then be used in the href in in a Form where the security scheme is active.

TDs can specify a combination of security schemes. A ComboSecurityScheme with allOf can be used to specify that all need to be satisfied to allow activation of the Interaction Affordance.

TDs can specify a combination of security schemes. To avoid redundancy in this case, e.g. repeating the details of the form elements, a ComboSecurityScheme with oneOf can be used instead.

A TD can also have multiple security definitions.

Security configurations can also be specified for different forms within the same Interaction Affordance.

Security configuration in the TD is mandatory, therefore the nosec security scheme is provided for the case that no security is needed.

Data schema serialization applies to PropertyAffordance instances, the values assigned to input and output in ActionAffordance instances, the values assigned to subscription, data, and cancellation in EventAffordance instances, and the value assigned to uriVariables in instances of Subclasses of InteractionAffordance.

Data schema serialization applies to PropertyAffordance instances, the values assigned to input and output in ActionAffordance instances, the values assigned to subscription, data, and cancellation in EventAffordance instances, and the value assigned to uriVariables in instances of Subclasses of InteractionAffordance.

When forms are present at the top level, it can be used to describe meta interactions offered by a Thing. readallproperties is a type of meta interaction which allows the consumer to read all properties at once.

Thing-level uriVariables can be used here to supply further variables to the operation or to specify a list of Property Affordance names for a readmultipleproperties operation.

When forms is present at the top level, it can be used to describe meta interactions offered by a Thing. writeallproperties is a type of meta interaction which allows the consumer to write all properties at once.

The version member is intended as container for additional application- and/or device-specific version information based on TD Context Extensions.

The message received from the Thing as part of an Interaction Affordance can differ due to different reasons. Such reasons could be error cases or alternative responses for a valid response. In these cases, additionalResponses terms can be used to describe this behavior.

The Interaction Affordance not only describes the request, but also provides metadata for the expected response. In such cases, the response member is used to indicate the representation format of the response payload. therefore no output schema is required, as the content type fully specifies the representation format.

TD instances may also combine the use of title and description with titles and descriptions. title and description are seeing as the default text.

A TD can contain multiple languages, where the name is a valid language tag as defined by [BCP47] and the value is a human-readable string in the language indicated by the tag.

Metadata can be used to determine the base direction of string values, utilizing @direction and the values rtl, ltr and null for default direcction.

Combined dynamic uriVariables and uriVariables in href structure.

href may also carry a URI that contains dynamic variables.

As defined in [RFC6570], uriVariables can be used for replacing the href structure.

Thing Description with TD Context Extension for semantic annotations.

TD Context Extensions may be used to annotate pieces of a data schema, to be able to semantically process the state information of the physical world object, which is represented by the data exchanged during an interaction.

This example provides additional metadata terms from different external context files as provided in @context.

In some use cases location based metadata have to be provided at the interaction level, e.g., as provided as a Property that returns the latest longitude, latitude, and elevation values based on schema.org.

A Thing can also refer to a group in which it is collected with the collection value.

A reference can be provided that points to a Thing (e.g., a controller) that controls the underlying unit (e.g., a lamp) utilizing controlledBy.

A superordinate Thing can collect a group of Things and refer to them by using the item value.

To point to a developer documentation of a Thing the value service-doc can be used.

This is an example of a basic Thing, which is use as a sort of template for creating a Thing Description instance of a Lamp TD.

If it is desired to provide information that a Thing Model consists of one or more (sub-)TMs, the links entries must use the 'rel': 'tm:submodel' that targets to the (sub-)TM. Optionally an instanceName may be provided to associate an individual name to the composed (sub-)TM. This is useful when multiple similar Thing Model definitions are composed and needs to be distinguished.

The tm:extends and the import mechanism based on tm:ref can also be used at the same time in a TM definition. This example extends the a basic TM with an On/Off property and imports the status and dim definitions from pther TMs respectively.

A Thing Model can extend an existing Thing Model by using the tm:extends mechanism. When a Thing Model extends another Thing Model, at least one links entry with 'rel: tm:extends' that targets a Thing Model that is be extended must be used.

For importing pieces of definitions of one or more existing Thiing Models, the 'tm:ref' term is utilized which provides the location of an existing (sub-)definition that should be reused. This example shows a TM definition that imports the existing definition of the property onOff from another TM into the new property definition switch.

In some cases it is desirable to not enforce which interaction affordances are mandatory and do not necessarily need to be implemented in a Thing Description instance. If interaction models are not mandatory to be implemented in a Thing Description instance, Thing Model definitions MUST use the JSON member name tm:optional.

At the place the 'tm:ref' is defined, additional name-value pairs can be added. It is also permitted to override name-value pairs from the referenced definition. If the intention is to override an existing JSON name-value pair definition from tm:ref, the same JSON name MUST be used at the same level of the tm:ref declaration that provides a new value. This example shows a new TM definition that overwrites (maximum), enhances (unit), and removes (title) existing definitions.

An optional definition in a Thing Model definition can be overwritten in the case it is extended by another Thing Model through the use of tm:ref. This examples overwrites the 'tm:optional' of another TM with an optional 'overheating' event.

In a case where TD instance terms, but not their values, are known in advance, the placeholder labeling may be used in a Thing Model. The string-based pattern of the placeholder must follow a valid pattern based on the regular expression {{2}[ -~]+}{2} (e.g., {{PLACEHOLDER_IDENTIFIER}}). The characters between {{ and }} are used as identifier name of the placeholder.

This Thing example re-uses and augments a 'genericTemperature' property in two more specific properties, which describe an inner and an outer temperature value, respectively.

This is an example of a simple Thing Model which is utilized as a submodel of another Thing Model.

This is an example of a simple Thing Model which is utilized as a submodel of another Thing Model.

When the Thing definitions change over time, this should be reflected in the version container. The term model is used with the version container in order to provide such versioning information.