ThingDescribes a physical and/or virtual Thing (may represent one or more physical and/or virtual Things) in the Web of Things context.
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
lastModified | Provides information when the TD instance was last modified. | no | . | string |
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
actions | All Action-based interaction patterns of the Thing. | no | . | Action |
base | Define the base URI that is valid for all defined local interaction resources. All other URIs in the TD must then be resolved using the algorithm defined in [[!RFC3986]]. | no | . | anyURI |
links | Provides Web links to arbitrary resources that relate to the specified Thing Description. | no | . | array of Link |
description | Provides additional (human-readable) information. | no | . | string |
actions | All Action-based interaction patterns of the Thing. | no | . | Action |
security | Set of security definition names, chosen from those defined in securityDefinitions. These must all be satisfied for access to resources at or below the current level, if not overridden at a lower level. | yes | . | array of string |
events | All Event-based interaction patterns of the Thing. | no | . | Event |
support | Provides information about the TD maintainer (e.g., author, link or telephone number to get support, etc). | no | . | anyURI |
created | Provides information when the TD instance was created. | no | . | string |
properties | All Property-based interaction patterns of the Thing. | no | . | Property |
version | Provides version information. | no | . | Versioning |
lastModified | Provides information when the TD instance was last modified. | no | . | string |
name | Name of the Thing. | yes | . | string |
support | Provides information about the TD maintainer (e.g., author, link or telephone number to get support, etc). | no | . | anyURI |
securityDefinitions | Set of named security configurations (definitions only). Not actually applied unless names are used in a security section. | no | . | SecurityScheme |
InteractionPatternThree interaction patterns are defined as subclasses: Property, Action and Event. When a concrete Property, Action or Event is defined in a Thing Description, it is called an "interaction resource". Interactions between Things can be as simple as one Thing accessing another Thing's data to get or (in the case the data is also writable) change the representation of data such as metadata, status or mode. A Thing may also be interested in getting asynchronously notified of future changes in another Thing, or may want to initiate a process served in another Thing that may take some time to complete and monitor the progress. Interactions between Things may involve exchanges of data between them. This data can be either given as input by the client Thing, returned as output by the server Thing or both.
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
security | Set of security definition names, chosen from those defined in securityDefinitions. These must all be satisfied for access to resources at or below the current level, if not overridden at a lower level. | no | . | array of string |
title | Provides a human-readable title (e.g., display a text for UI representation) of the interaction pattern. | no | . | string |
forms | Indicates one or more endpoints from which an interaction pattern is accessible. | yes | . | array of Form |
version | Provides version information. | no | . | Versioning |
events | All Event-based interaction patterns of the Thing. | no | . | Event |
description | Provides additional (human-readable) information. | no | . | string |
security | Set of security definition names, chosen from those defined in securityDefinitions. These must all be satisfied for access to resources at or below the current level, if not overridden at a lower level. | yes | . | array of string |
properties | All Property-based interaction patterns of the Thing. | no | . | Property |
securityDefinitions | Set of named security configurations (definitions only). Not actually applied unless names are used in a security section. | no | . | SecurityScheme |
links | Provides Web links to arbitrary resources that relate to the specified Thing Description. | no | . | array of Link |
InteractionPatternThree interaction patterns are defined as subclasses: Property, Action and Event. When a concrete Property, Action or Event is defined in a Thing Description, it is called an "interaction resource". Interactions between Things can be as simple as one Thing accessing another Thing's data to get or (in the case the data is also writable) change the representation of data such as metadata, status or mode. A Thing may also be interested in getting asynchronously notified of future changes in another Thing, or may want to initiate a process served in another Thing that may take some time to complete and monitor the progress. Interactions between Things may involve exchanges of data between them. This data can be either given as input by the client Thing, returned as output by the server Thing or both.
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
description | Provides additional (human-readable) information. | no | . | string |
scopes | Set of authorization scope identifiers, provided as an array. These are provided in tokens returned by an authorization server and associated with forms in order to identify what resources a client may access and how. | no | . | array of string |
uriVariables | Define URI template variables as collection based on DataSchema declarations. | no | . | DataSchema |
The class InteractionPattern has the following subclasses:
EventtitlestringuriVariablesDataSchemasecuritystringformsFormThe class InteractionPattern has the following subclasses:
@@ -600,28 +600,28 @@
ActionActions offer functions of the Thing. These functions may manipulate the internal state of a Thing in a way that is not possible through setting Properties. Examples are changing internal state that is not exposed as a Property, changing multiple Properties, changing Properties over time or with a process that should not be disclosed. Actions may also be pure functions, that is, they may not use any internal state at all, and may simply process input data and return a result that directly depends only on the input given.
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
safe | Signals if the action is safe (=true) or not. Used to signal if there is no internal state (cf. resource state) is changed when invoking an Action. In that case responses can be cached as example. | yes | false | boolean |
idempotent | Signals if the action is idempotent (=true) or not. Informs if the action can be called repeatedly with the same outcome. . | yes | false | boolean |
input | Used to define the input data schema of the action. | no | . | DataSchema |
idempotent | Signals if the action is idempotent (=true) or not. Informs if the action can be called repeatedly with the same outcome. . | yes | false | boolean |
output | Used to define the output data schema of the action. | no | . | DataSchema |
EventThe Event Interaction Pattern describes event sources that asynchronously push messages. Here not state, but state transitions (events) are communicated (e.g., "clicked"). Events may be triggered by internal state changes that are not exposed as Properties. Events usually follow strong consistency, where messages need to be queued to ensure eventual delivery of all events that have occurred.
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
subscription | Defines data that needs to be passed upon subscription, e.g., filters or message format for setting up Webhooks. | no | . | DataSchema |
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
data | Defines the data schema of the Event instance messages pushed by the Thing. | no | . | DataSchema |
cancellation | Defines any data that needs to be passed to cancel a subscription, e.g., a specific message to remove a Webhook. | no | . | DataSchema |
data | Defines the data schema of the Event instance messages pushed by the Thing. | no | . | DataSchema |
subscriptionDataSchemaFormCommunication metadata indicating where a service can be accessed by a client application. An interaction might have more than one form.
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
href | URI of the endpoint where an interaction pattern is provided. | yes | . | anyURI |
contentType | Assign a content type based on a media type [[!MEDIATYPES]] (e.g., 'application/json) and (optional) parameters (e.g., 'charset=utf-8'). | yes | application/json | string |
security | Set of security definition names, chosen from those defined in securityDefinitions. These must all be satisfied for access to resources at or below the current level, if not overridden at a lower level. | no | . | array of string |
response | This optional term can be used if, e.g., the output communication metadata differ from input metdata (e.g., output contentType differ from the + input contentType). The response name contains metadata that is only valid for the reponse messages. | no | . | Response |
op | Indicates the expected result of performing the operation described by the form. For example, the Property interaction allows get and set operations. The protocol binding may contain a form for the get operation and a different form for the set operation. The op attribute indicates which form is which and allows the client to select the correct form for the operation required. | no | . | string (one of readproperty, writeproperty, observeproperty, invokeaction, subscribeevent, or unsubscribeevent) |
contentType | Assign a content type based on a media type [[!MEDIATYPES]] (e.g., 'application/json) and (optional) parameters (e.g., 'charset=utf-8'). | yes | application/json | string |
subprotocol | Indicates the exact mechanism by which an interaction will be accomplished for a given protocol when there are multiple options. For example, for HTTP and Events, it indicates which of several available mechanisms should be used for asynchronous notifications. | no | . | string (one of longpoll) |
scopes | Set of authorization scope identifiers, provided as an array. These are provided in tokens returned by an authorization server and associated with forms in order to identify what resources a client may access and how. | no | . | array of string |
response | This optional term can be used if, e.g., the output communication metadata differ from input metdata (e.g., output contentType differ from the - input contentType). The response name contains metadata that is only valid for the reponse messages. | no | . | Response |
LinkA Web link, as specified by IETF RFC 8288 (https://tools.ietf.org/html/rfc8288).
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
anchor | By default, the context of a link is the URL of the representation it is associated with, and is serialised as a URI. When present, the anchor parameter overrides this with another URI, such as a fragment of this resource, or a third resource (i.e., when the anchor value is an absolute URI). | no | . | anyURI |
type | Provides a hint indicating what the media type [[!MEDIATYPES]] of the result of dereferencing the link should be. | no | . | string |
security | Set of security definition names, chosen from those defined in securityDefinitions. These must all be satisfied for access to resources at or below the current level, if not overridden at a lower level. | no | . | array of string |
LinkA Web link, as specified by IETF RFC 8288 (https://tools.ietf.org/html/rfc8288).
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
type | Provides a hint indicating what the media type [[!MEDIATYPES]] of the result of dereferencing the link should be. | no | . | string |
anchor | By default, the context of a link is the URL of the representation it is associated with, and is serialised as a URI. When present, the anchor parameter overrides this with another URI, such as a fragment of this resource, or a third resource (i.e., when the anchor value is an absolute URI). | no | . | anyURI |
rel | Indicates the relation to an other Thing. | no | . | string |
href | URI of the endpoint where an interaction pattern is provided. | yes | . | anyURI |
VersioningCarries version information about the TD instance. If required, additional version information such as firmware and hardware version (term definitions outside of the TD namespace) can be extended here.
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
instance | Provides a version identicator of this TD instance. | yes | . | string |
DataSchema| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
const | Provides a constant value. | no | . | any type |
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
title | Provides a human-readable title (e.g., display a text for UI representation) of the interaction pattern. | no | . | string |
const | Provides a constant value. | no | . | any type |
unit | Provides unit information that is used, e.g., in international science, engineering, and business. | no | . | DataSchema |
enum | Restricted set of values provided as an array. | no | . | array of any type |
oneOf | Used to ensure that the data is valid against one of the specified schemas in the array. | no | . | array of DataSchema |
description | Provides additional (human-readable) information. | no | . | string |
writeOnly | Boolean value that indicates whether a property interaction / value is write only (=true) or not (=false). | yes | false | boolean |
type | Assignment of JSON-based data types compatible with JSON Schema (one of boolean, integer, number, string, object, array, or null). | no | . | string (one of object, array, string, number, integer, boolean, or null) |
readOnly | Boolean value that indicates whether a property interaction / value is read only (=true) or not (=false). | yes | false | boolean |
oneOf | Used to ensure that the data is valid against one of the specified schemas in the array. | no | . | array of DataSchema |
unit | Provides unit information that is used, e.g., in international science, engineering, and business. | no | . | DataSchema |
title | Provides a human-readable title (e.g., display a text for UI representation) of the interaction pattern. | no | . | string |
type | Assignment of JSON-based data types compatible with JSON Schema (one of boolean, integer, number, string, object, array, or null). | no | . | string (one of object, array, string, number, integer, boolean, or null) |
The class DataSchema has the following subclasses:
IntegerSchemawriteOnlyfalsebooleanThe class DataSchema has the following subclasses:
IntegerSchemaArraySchemaBooleanSchemaNullSchemaNumberSchemaStringSchemaArraySchemaA JSON array specification ("type": "array").
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
maxItems | Defines the maximum number of items that have to be in the array. | no | . | unsignedInt |
items | Used to define the characteristics of an array. | no | . | DataSchema |
minItems | Defines the minimum number of items that have to be in the array. | no | . | unsignedInt |
minItemsunsignedIntitemsDataSchemaBooleanSchemaA JSON boolean value specification ("type": "boolean").
NumberSchemaA JSON number value specification ("type": "number").
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
minimum | Specifies a minimum numeric value. Only applicable for associated number or integer types. | no | . | double |
maximum | Specifies a maximum numeric value. Only applicable for associated number or integer types. | no | . | double |
NumberSchemaA JSON number value specification ("type": "number").
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
maximum | Specifies a maximum numeric value. Only applicable for associated number or integer types. | no | . | double |
minimum | Specifies a minimum numeric value. Only applicable for associated number or integer types. | no | . | double |
IntegerSchemaA JSON integer value specification, that is, numbers without a fractional part ("type": "integer").
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
maximum | Specifies a maximum numeric value. Only applicable for associated number or integer types. | no | . | integer |
minimum | Specifies a minimum numeric value. Only applicable for associated number or integer types. | no | . | integer |
ObjectSchemaA JSON object specification ("type": "object").
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
properties | Data schema nested definitions. | no | . | DataSchema |
required | Defines which members of the object type are mandatory. | no | . | array of string |
ObjectSchemaA JSON object specification ("type": "object").
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
required | Defines which members of the object type are mandatory. | no | . | array of string |
properties | Data schema nested definitions. | no | . | DataSchema |
StringSchemaA JSON string value specification ("type": "string").
NullSchemaA JSON null value specification ("type": "null"). Is the type of null then it has only one acceptable value, namely null.
SecurityScheme| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
scheme | Identification of security mechanism being configured. | yes | . | string (one of nosec, basic, cert, digest, bearer, pop, psk, public, oauth2, or apikey) |
description | Provides additional (human-readable) information. | no | . | string |
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
description | Provides additional (human-readable) information. | no | . | string |
scheme | Identification of security mechanism being configured. | yes | . | string (one of nosec, basic, cert, digest, bearer, pop, psk, public, oauth2, or apikey) |
proxy | URI of the proxy server this security configuration provides access to. If not given, the corresponding security configuration is for the endpoint. | no | . | anyURI |
The class SecurityScheme has the following subclasses:
PSKSecuritySchemeAPIKeySecuritySchemeNoSecuritySchemeNoSecuritySchemeA security configuration corresponding to ("scheme": "nosec"), indicating there is no authentication or other mechanism required to access the resource.
BasicSecuritySchemeBasic authentication security configuration ("scheme": "basic"), using an unencrypted username and password. This scheme should be used with some other security mechanism providing confidentiality, for example, TLS.
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
name | Name for query, header, or cookie parameters. | no | . | string |
in | Specifies the location of security authentication information (one of header, query, body, or cookie). | no | header | string |
DigestSecuritySchemeDigest authentication security configuration ("scheme": "digest"). This scheme is similar to basic authentication but with added features to avoid man-in-the-middle attacks.
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
in | Specifies the location of security authentication information (one of header, query, body, or cookie). | no | header | string |
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
qop | Quality of protection (one of auth or auth-int). | no | auth | string |
name | Name for query, header, or cookie parameters. | no | . | string |
qop | Quality of protection (one of auth or auth-int). | no | auth | string |
inheaderstringAPIKeySecuritySchemeAPI key authentication security configuration ("scheme": "apikey"). This is for the case where the access token is opaque and is not using a standard token format.
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
in | Specifies the location of security authentication information (one of header, query, body, or cookie). | no | query | string |
name | Name for query, header, or cookie parameters. | no | . | string |
BearerSecuritySchemeBearer token authentication security configuration ("scheme": "bearer"). This scheme is intended for situations where bearer tokens are used independently of OAuth2. If the oauth2 scheme is specified it is not generally necessary to specify this scheme as well as it is implied.
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
authorization | URI of the authorization server. | no | . | anyURI |
format | Specifies format of security authentication information (one of jwt, jwe, or jws). | no | jwt | string |
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
format | Specifies format of security authentication information (one of jwt, jwe, or jws). | no | jwt | string |
authorization | URI of the authorization server. | no | . | anyURI |
name | Name for query, header, or cookie parameters. | no | . | string |
alg | Encoding, encryption, or digest algorithm (one of MD5, ES256, or ES512-256). | no | ES256 | string |
in | Specifies the location of security authentication information (one of header, query, body, or cookie). | no | header | string |
CertSecuritySchemeCertificate-base asymmetric key security configuration ("scheme": "cert").
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
identity | Pre-shared key identity. | no | . | string |
PSKSecuritySchemePre-shared key authentication security configuration ("scheme": "psk").
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
identity | Pre-shared key identity. | no | . | string |
PublicSecuritySchemeRaw public key asymmetric key security configuration ("scheme": "public").
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
identity | Pre-shared key identity. | no | . | string |
PoPSecuritySchemeProof-of-possession token authentication security configuration ("scheme": "pop").
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
alg | Encoding, encryption, or digest algorithm (one of MD5, ES256, or ES512-256). | no | ES256 | string |
authorization | URI of the authorization server. | no | . | anyURI |
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
authorization | URI of the authorization server. | no | . | anyURI |
alg | Encoding, encryption, or digest algorithm (one of MD5, ES256, or ES512-256). | no | ES256 | string |
in | Specifies the location of security authentication information (one of header, query, body, or cookie). | no | header | string |
name | Name for query, header, or cookie parameters. | no | . | string |
format | Specifies format of security authentication information (one of jwt, jwe, or jws). | no | jwt | string |
OAuth2SecuritySchemeOAuth2 authentication security configuration ("scheme": "oauth2"). For the implicit flow the authorization and scopes are required. For the password and client flows both token and scopes are required. For the code flow authorization, token, and scopes are required.
| Vocabulary term | Description | Mandatory | Default value | Type |
|---|---|---|---|---|
refresh | URI of the refresh server. | no | . | anyURI |
token | URI of the token server. | no | . | anyURI |
flow | Authorization flow (one of implicit, password, client, or code). | no | implicit | string |
scopes | Set of authorization scope identifiers, provided as an array. These are provided in tokens returned by an authorization server and associated with forms in order to identify what resources a client may access and how. | no | . | array of string |
authorization | URI of the authorization server. | no | . | anyURI |
flow | Authorization flow (one of implicit, password, client, or code). | no | implicit | string |
tokenanyURIsupport member in Thing class was changed to "anyURI".response member that can be used to describe metadata for response messages.securityDefinitions, update examples using security to use defined names, not SecurityScheme objects.scopes.scopes.security declaration is mandatory.unit member to provide unit information.support member in Thing class was changed to "anyURI".response member that can be used to describe metadata for response messages.securityDefinitions, update examples using security to use defined names, not SecurityScheme objects.scopes.scopes.security declaration is mandatory.unit member to provide unit information.