ThingAn abstraction of a physical or a virtual entity whose - metadata and interfaces are described by a WoT Thing - Description, whereas a virtual entity is the composition - of one or more Things.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
@context | JSON-LD keyword to define short-hand names called terms that are used throughout a TD document. | mandatory | anyURI or Array |
@type | JSON-LD keyword to label the object with semantic tags (or types). | optional | string or Array of string |
id | Identifier of the Thing in form of a URI [[RFC3986]] (e.g., stable URI, temporary and mutable URI, URI with local IP address, URN, etc.). | optional | anyURI |
title | Provides a human-readable title (e.g., display - a text for UI representation) based on a default - language. | mandatory | any type |
titles | Provides multi-language human-readable titles - (e.g., display a text for UI representation in - different languages). Also see MultiLanguage. | optional | Map of MultiLanguage |
description | Provides additional (human-readable) - information based on a default language. | optional | string |
descriptions | Can be used to support (human-readable) - information in different languages. Also see MultiLanguage. | optional | Map of MultiLanguage |
version | Provides version information. | optional | VersionInfo |
created | Provides information when the TD instance was - created. | optional | dateTime |
modified | Provides information when the TD instance was - last modified. | optional | dateTime |
support | Provides information about the TD maintainer as
- URI scheme (e.g., mailto [[RFC6068]],
- tel [[RFC3966]],
- https [[RFC9112]]). | optional | anyURI |
base | Define the base URI that is used for all
- relative URI references throughout a TD document.
- In TD instances, all relative URIs are resolved
- relative to the base URI using the algorithm
- defined in [RFC3986]. - - base does not affect the URIs used in
- @context and the IRIs used within
- Linked Data [LINKED-DATA]
- graphs that are relevant when semantic processing
- is applied to TD instances. | optional | anyURI |
properties | All Property-based Interaction Affordances - of the Thing. | optional | Map of PropertyAffordance |
actions | All Action-based Interaction Affordances - of the Thing. | optional | Map of ActionAffordance |
events | All Event-based Interaction Affordances - of the Thing. | optional | Map of EventAffordance |
links | Provides Web links to arbitrary resources that - relate to the specified Thing Description. | optional | Array of Link |
forms | Set of form hypermedia controls that describe how - an operation can be performed. Forms are - serializations of Protocol Bindings. Thing level forms are used to describe endpoints for a group of interaction affordances. | optional | Array of Form |
security | Set of security definition names, chosen from
- those defined in securityDefinitions.
- These must all be satisfied for access to resources. | mandatory | string or Array of string |
securityDefinitions | Set of named security configurations
- (definitions only). Not actually applied unless
- names are used in a security
- name-value pair. | mandatory | Map of SecurityScheme |
profile | Indicates the WoT Profile mechanisms followed by this Thing Description and the corresponding Thing implementation. | optional | anyURI or Array of anyURI |
schemaDefinitions | Set of named data schemas.
- To be used in a schema
- name-value pair inside an
- AdditionalExpectedResponse object. | optional | Map of DataSchema |
uriVariables | Define URI template variables according to [[RFC6570]] as collection
- based on DataSchema declarations. The Thing level uriVariables can be used in Thing level
- forms or in Interaction Affordances.
- The individual variables DataSchema cannot be an ObjectSchema or an ArraySchema since each variable needs
- to be serialized to a string inside the href upon the execution of the operation.
- If the same variable is both declared in Thing level uriVariables and in Interaction Affordance level,
- the Interaction Affordance level variable takes precedence. | optional | Map of DataSchema |
- For @context the following rules are defined for Thing Description instances:
-
Thing+ An abstraction of a physical or a virtual entity whose metadata and interfaces are described by a WoT + Thing Description, whereas a virtual entity is the composition of one or more Things. +
+| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
@context |
+ + JSON-LD keyword to define short-hand names called terms that are used throughout a TD document. + | +mandatory | +
+ anyURI or
+ Array
+ |
+
@type |
+ JSON-LD keyword to label the object with semantic tags (or types). | +optional | +
+ string or
+ Array of
+ string
+ |
+
id |
+ + Identifier of the Thing in form of a URI [[RFC3986]] (e.g., stable URI, temporary and mutable URI, + URI with local IP address, URN, etc.). + | +optional | +
+ anyURI
+ |
+
title |
+ + Provides a human-readable title (e.g., display a text for UI representation) based on a default + language. + | +mandatory | +any type | +
titles |
+ + Provides multi-language human-readable titles (e.g., display a text for UI representation in + different languages). Also see MultiLanguage. + | +optional | +
+ Map of MultiLanguage
+ |
+
description |
+ Provides additional (human-readable) information based on a default language. | +optional | +
+ string
+ |
+
descriptions |
+ + Can be used to support (human-readable) information in different languages. Also see + MultiLanguage. + | +optional | +
+ Map of MultiLanguage
+ |
+
version |
+ Provides version information. | +optional | +
+ VersionInfo
+ |
+
created |
+ Provides information when the TD instance was created. | +optional | +
+ dateTime
+ |
+
modified |
+ Provides information when the TD instance was last modified. | +optional | +
+ dateTime
+ |
+
support |
+
+ Provides information about the TD maintainer as URI scheme (e.g., mailto [[RFC6068]],
+ tel [[RFC3966]], https [[RFC9112]]).
+ |
+ optional | +
+ anyURI
+ |
+
base |
+
+ Define the base URI that is used for all relative URI references throughout a TD document. In TD
+ instances, all relative URIs are resolved relative to the base URI using the algorithm defined in
+ [RFC3986]. + + base does not affect the URIs used in @context and the IRIs used within
+ Linked Data [LINKED-DATA] graphs that are relevant when semantic processing is applied to TD instances.
+ |
+ optional | +
+ anyURI
+ |
+
properties |
+ + All Property-based + Interaction Affordances + of the Thing. + | +optional | +
+ Map of PropertyAffordance
+ |
+
actions |
+ + All Action-based + Interaction Affordances + of the Thing. + | +optional | +
+ Map of ActionAffordance
+ |
+
events |
+ + All Event-based + Interaction Affordances + of the Thing. + | +optional | +
+ Map of EventAffordance
+ |
+
links |
+ Provides Web links to arbitrary resources that relate to the specified Thing Description. | +optional | +
+ Array of Link
+ |
+
forms |
+ + Set of form hypermedia controls that describe how an operation can be performed. Forms are + serializations of Protocol Bindings. Thing level forms are used to describe endpoints for a + group of interaction affordances. + | +optional | +
+ Array of Form
+ |
+
security |
+
+ Set of security definition names, chosen from those defined in securityDefinitions.
+ These must all be satisfied for access to resources.
+ |
+ mandatory | +
+ string or
+ Array of
+ string
+ |
+
securityDefinitions |
+
+ Set of named security configurations (definitions only). Not actually applied unless names are used
+ in a security name-value pair.
+ |
+ mandatory | +
+ Map of SecurityScheme
+ |
+
profile |
+ + Indicates the WoT Profile mechanisms followed by this Thing Description and the corresponding Thing + implementation. + | +optional | +
+ anyURI or
+ Array of
+ anyURI
+ |
+
schemaDefinitions |
+
+ Set of named data schemas. To be used in a schema
+ name-value pair inside an
+ AdditionalExpectedResponse object.
+ |
+ optional | +
+ Map of DataSchema
+ |
+
uriVariables |
+
+ Define URI template variables according to [[RFC6570]] as collection based on DataSchema
+ declarations. The Thing level uriVariables can be used in Thing level
+ forms or in Interaction Affordances. The individual variables DataSchema cannot be an
+ ObjectSchema or an ArraySchema since each variable needs to be serialized to a string inside the
+ href upon the execution of the operation. If the same variable is both declared in
+ Thing level uriVariables and in Interaction Affordance level, the Interaction
+ Affordance level variable takes precedence.
+ |
+ optional | +
+ Map of DataSchema
+ |
+
For @context the following rules are defined for Thing Description instances:
@context
+ name-value pair MUST contain the anyURI
+ https://www.w3.org/2022/wot/td/v1.1
+ in order to identify the document as a TD 1.1 which would allow Consumers to use the newly
+ introduced terms.
+
+ https://www.w3.org/2019/wot/td/v1
+ MUST be the first entry and the https://www.w3.org/2022/wot/td/v1.1 MUST be the second
+ entry.
+ @context is an
+ Array, the anyURI
+ https://www.w3.org/2022/wot/td/v1.1 MAY be followed
+ by elements of type anyURI or type
+ Map in any order, while it is
+ RECOMMENDED to include only one
+ Map with all the name-value pairs in
+ the @context
+ Array.
+ @context Array MAY
+ contain name-value pairs, where the value is a namespace identifier of type anyURI and
+ the name a Term or prefix denoting
+ that namespace.
+ @context Array SHOULD
+ contain a name-value pair that defines the default language for the Thing Description, where the name
+ is the Term
+ @language and the value is a well-formed language tag as defined by [BCP47] (e.g., en, de-AT, gsw-CH, zh-Hans,
+ zh-Hant-HK, sl-nedis).
+ @context
- name-value pair MUST contain the anyURI
- https://www.w3.org/2022/wot/td/v1.1
- in order to identify the document as a TD 1.1 which would allow Consumers to use the newly introduced terms.
- https://www.w3.org/2019/wot/td/v1
- MUST be the first entry and the https://www.w3.org/2022/wot/td/v1.1 MUST be the second entry.
- @context
- is an Array, the anyURI
- https://www.w3.org/2022/wot/td/v1.1 MAY be followed by elements of
- type anyURI or type Map in any
- order, while it is RECOMMENDED to include only one
- Map with all the name-value pairs in the
- @context Array.
- @context
- Array MAY
- contain name-value pairs, where the value is a namespace
- identifier of type anyURI and the name a
- Term or prefix denoting that namespace.
- @context Array SHOULD contain a name-value pair that
- defines the default language for the Thing Description,
- where the name is the Term
- @language and the value is a well-formed
- language tag as defined by [BCP47] (e.g.,
- en, de-AT, gsw-CH,
- zh-Hans, zh-Hant-HK,
- sl-nedis).
- + To determine the base direction of all human-readable text in Thing Description and + Thing Model instances this specification recommends to follow the [[STRING-META]] guideline about + string-specific directional information + when no built-in mechanism for associating base direction metadata is available. +
- -To determine the base direction of all - human-readable text in Thing Description - and Thing Model instances this specification - recommends to follow the [[STRING-META]] guideline about - string-specific directional information - when no built-in mechanism for associating base direction metadata - is available. -
- -TD Processors should be aware of - certain special cases when processing bidirectional text. - - TD Processors SHOULD take care to use bidi isolation when - presenting strings to users, particularly when embedding - in surrounding text (e.g., for Web user interface). - Mixed direction text can occur in any language, even when the - language is properly identified.
-- TD producers SHOULD attempt to provide mixed direction - strings in a way that can be displayed successfully by a - naive user agent. - For example, if an RTL string begins - with an LTR run (such as a number or a brand or trade - name in Latin script), including an RLM character at the - start of the string or wrapping opposite direction runs - in bidi controls can assist in proper display.
-Strings on the Web: Language and Direction - Metadata [string-meta] - provides some guidance and illustrates a number of - pitfalls when using bidirectional text.
-In addition to the
- explicitly provided Interaction
- Affordances in the properties,
- actions, and events Maps, a Thing can also
- provide meta-interactions, which are indicated by
- Form instances in its optional
- forms Array.
- When
- the forms Array of a
- Thing instance contains Form
- instances, it MUST contain op member with the string values assigned
- to the name op, either directly or within an Array, MUST be one of the following operation
- types: readallproperties,
- writeallproperties,
- readmultipleproperties,
- writemultipleproperties, observeallproperties,
- unobserveallproperties, queryallactions,
- subscribeallevents, or
- unsubscribeallevents. (See
- an example for an
- usage of form in a Thing instance.)
The data schema for each of the property meta-interactions is
- constructed by combining the data schemas of each
- PropertyAffordance instance in a single
- ObjectSchema instance, where the
- properties Map of the
- ObjectSchema instance contains each data
- schema of the PropertyAffordances identified
- by the name of the corresponding
- PropertyAffordances instance.
If not specified otherwise (e.g., through a TD Context Extension), the request data of the
- readmultipleproperties operation is an
- Array that contains the intended
- PropertyAffordances instance names, which is
- serialized to the content type specified by the
- Form instance.
InteractionAffordanceMetadata of a Thing that shows the possible choices to - Consumers, thereby suggesting - how Consumers may interact with the - Thing. There are many types of potential affordances, but - W3C WoT - defines three types of Interaction Affordances: - Properties, Actions, and Events.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
@type | JSON-LD keyword to label the object with semantic tags (or types). | optional | string or Array of string |
title | Provides a human-readable title (e.g., display - a text for UI representation) based on a default - language. | optional | string |
titles | Provides multi-language human-readable titles - (e.g., display a text for UI representation in - different languages). Also see MultiLanguage. | optional | Map of MultiLanguage |
description | Provides additional (human-readable) - information based on a default language. | optional | string |
descriptions | Can be used to support (human-readable) - information in different languages. Also see MultiLanguage. | optional | Map of MultiLanguage |
forms | Set of form hypermedia controls that describe - how an operation can be performed. Forms are - serializations of Protocol Bindings. The array cannot be empty. | mandatory | Array of Form |
uriVariables | Define URI template variables according to [[RFC6570]] as collection
- based on DataSchema declarations. The individual variables DataSchema cannot be an ObjectSchema or an ArraySchema since each variable needs
- to be serialized to a string inside the href upon the execution of the operation.
- If the same variable is both declared in Thing level uriVariablesand in Interaction Affordance level,
- the Interaction Affordance level variable takes precedence. | optional | Map of DataSchema |
The class InteractionAffordance has the following subclasses:
PropertyAffordanceAn Interaction Affordance that exposes state of the - Thing. This state can then be retrieved (read) and/or updated (write). - Things can also choose to - make Properties observable by pushing the new state after - a change.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
observable | A hint that indicates whether Servients hosting
- the Thing and Intermediaries should provide a
- Protocol Binding that supports the observeproperty and unobserveproperty operations
- for this Property. | with default | boolean |
Property instances are also instances of
- the class DataSchema. Therefore, it can contain the
- type, unit,
- readOnly and writeOnly
- members, among others.
PropertyAffordance is a Subclass of the
- InteractionAffordance Class and
- the DataSchema Class.
- When a Form instance is within a
- PropertyAffordance instance, the value
- assigned to op MUST be one of readproperty,
- writeproperty, observeproperty,
- unobserveproperty or an Array
- containing a combination of these terms.
- It is considered to be good practice that each observeproperty has a corresponding
- unobserveproperty unless the protocol supports implicit unsubscription mechanisms
- (e.g., heartbeat to detect connection loss).
- The observation mechanism depends on the underlying protocol or sub-protocol. Having said that, it is not - guaranteed that the current Property value will be provided once the subscription is initiated. Hence, it may be - necessary to read the current Property value before/after the subscription to get a first value. -
ActionAffordanceAn Interaction Affordance that allows to invoke a - function of the Thing, which manipulates state (e.g., - toggling a lamp on or off) or triggers a process on the - Thing (e.g., dim a lamp over time).
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
input | Used to define the input data schema of the - Action. | optional | DataSchema |
output | Used to define the output data schema of the - Action. | optional | DataSchema |
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. | with default | boolean |
idempotent | Indicates whether the Action is idempotent - (=true) or not. Informs whether the Action can be - called repeatedly with the same result, if present, - based on the same input. | with default | boolean |
synchronous | Indicates whether the action is synchronous (=true) or not. - A synchronous action means that the response of action contains all the information - about the result of the action and no further querying about the status of the action - is needed. Lack of this keyword means that no claim on the synchronicity of the - action can be made. | optional | boolean |
ActionAffordance is a Subclass of the
- InteractionAffordance Class.
- When a Form instance is within an
- ActionAffordance instance, the value
- assigned to op MUST
- either be invokeaction, queryaction,
- cancelaction or an
- Array
- containing a combination of these terms.
-
EventAffordanceAn Interaction Affordance that describes an event - source, which asynchronously pushes event data to - Consumers (e.g., overheating - alerts).
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
subscription | Defines data that needs to be passed upon - subscription, e.g., filters or message format for - setting up Webhooks. | optional | DataSchema |
data | Defines the data schema of the Event instance - messages pushed by the Thing. | optional | DataSchema |
dataResponse | Defines the data schema of the Event response messages sent by the consumer in a response to a data message. | optional | DataSchema |
cancellation | Defines any data that needs to be passed to - cancel a subscription, e.g., a specific message to - remove a Webhook. | optional | DataSchema |
EventAffordance is a Subclass of the
- InteractionAffordance Class.
- When
- a Form instance is within an EventAffordance
- instance, the value assigned to op
- MUST be either
- subscribeevent,
- unsubscribeevent, or both terms within an
- Array.
- It is considered to be good practice that each subscribeevent has a corresponding unsubscribeevent unless the protocol
- supports implicit unsubscription mechanisms (e.g., heartbeat to detect connection loss).
VersionInfoMetadata of a Thing that provides version information - about the TD document. If required, additional version - information such as firmware and hardware version (term - definitions outside of the TD namespace) can be extended - via the TD Context Extension - mechanism.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
instance | Provides a version indicator of this TD. - | mandatory | string |
model | Provides a version indicator of the underlying TM. - | optional | string |
It is recommended that the values within instances and model of
- the VersionInfo Class follow the
- semantic versioning pattern, where a sequence of three
- numbers separated by a dot indicates the major version,
- minor version, and patch version, respectively. See
- [SEMVER] for
- details.
MultiLanguageA Map providing a set of human-readable texts in different languages identified by language tags described in [[BCP47]]. See for example usages of this container in a Thing Description instance.
-Each name of the MultiLanguage Map MUST be a language tag as defined in [[!BCP47]].
- Each value of the MultiLanguage Map MUST be of type string.
-
+ TD Processors should be aware of + certain special cases when processing bidirectional text. + + TD Processors SHOULD take care + to use bidi isolation when presenting strings to users, particularly when embedding in surrounding text + (e.g., for Web user interface). Mixed direction text can occur in any language, even when the language is properly identified. +
++ + TD producers SHOULD attempt to provide mixed direction strings in a way that can be displayed + successfully by a naive user agent. + + For example, if an RTL string begins with an LTR run (such as a number or a brand or trade name in Latin + script), including an RLM character at the start of the string or wrapping opposite direction runs in bidi + controls can assist in proper display. +
++ Strings on the Web: Language and Direction Metadata [string-meta] provides some guidance and illustrates a number of pitfalls when using bidirectional text. +
+
+ In addition to the explicitly provided
+ Interaction Affordances
+ in the properties, actions, and events
+ Maps, a
+ Thing can also provide
+ meta-interactions, which are indicated by Form instances in its optional forms
+ Array.
+ When the forms Array of
+ a Thing instance contains
+ Form instances, it MUST contain op member with the string values assigned to
+ the name op, either directly or within an
+ Array, MUST be one of the following
+ operation types: readallproperties, writeallproperties,
+ readmultipleproperties, writemultipleproperties,
+ observeallproperties, unobserveallproperties, queryallactions,
+ subscribeallevents, or unsubscribeallevents.
+ (See an example for an usage of form in a Thing
+ instance.)
+
+ The data schema for each of the property meta-interactions is constructed by combining the data schemas of
+ each PropertyAffordance instance in a single ObjectSchema instance, where the
+ properties Map of the
+ ObjectSchema instance contains each data schema of the
+ PropertyAffordances identified by the name of the corresponding
+ PropertyAffordances instance.
+
+ If not specified otherwise (e.g., through a
+ TD Context Extension), the request
+ data of the readmultipleproperties operation is an
+ Array that contains the intended
+ PropertyAffordances instance names, which is serialized to the content type specified by the
+ Form instance.
+
InteractionAffordance+ Metadata of a Thing that shows the possible choices to + Consumers, thereby suggesting how + Consumers may interact with the + Thing. There are many types of potential affordances, but + W3C WoT defines three types of Interaction Affordances: + Properties, Actions, and Events. +
+| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
@type |
+ JSON-LD keyword to label the object with semantic tags (or types). | +optional | +
+ string or
+ Array of
+ string
+ |
+
title |
+ + Provides a human-readable title (e.g., display a text for UI representation) based on a default + language. + | +optional | +
+ string
+ |
+
titles |
+ + Provides multi-language human-readable titles (e.g., display a text for UI representation in + different languages). Also see MultiLanguage. + | +optional | +
+ Map of MultiLanguage
+ |
+
description |
+ Provides additional (human-readable) information based on a default language. | +optional | +
+ string
+ |
+
descriptions |
+ + Can be used to support (human-readable) information in different languages. Also see + MultiLanguage. + | +optional | +
+ Map of MultiLanguage
+ |
+
forms |
+ + Set of form hypermedia controls that describe how an operation can be performed. Forms are + serializations of Protocol Bindings. The array cannot be empty. + | +mandatory | +
+ Array of Form
+ |
+
uriVariables |
+
+ Define URI template variables according to [[RFC6570]] as collection based on DataSchema
+ declarations. The individual variables DataSchema cannot be an ObjectSchema or an ArraySchema since
+ each variable needs to be serialized to a string inside the href upon the execution of
+ the operation. If the same variable is both declared in Thing level
+ uriVariablesand in Interaction Affordance level, the Interaction Affordance level
+ variable takes precedence.
+ |
+ optional | +
+ Map of DataSchema
+ |
+
The class InteractionAffordance has the following subclasses:
PropertyAffordance
+ ActionAffordance
+ EventAffordance
+ PropertyAffordance+ An Interaction Affordance that exposes state of the Thing. This state can then be retrieved (read) and/or + updated (write). Things can also choose to make Properties observable by pushing the new state after a + change. +
+| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
observable |
+
+ A hint that indicates whether Servients hosting the Thing and Intermediaries should provide a
+ Protocol Binding that supports the observeproperty and
+ unobserveproperty operations for this Property.
+ |
+ with default | +
+ boolean
+ |
+
+ Property instances are also instances of the class DataSchema.
+ Therefore, it can contain the type, unit, readOnly and
+ writeOnly members, among others.
+
+ PropertyAffordance is a
+ Subclass of the
+ InteractionAffordance
+ Class and the DataSchema
+ Class.
+ When a Form instance is within a PropertyAffordance instance, the value assigned to
+ op MUST be one of readproperty, writeproperty,
+ observeproperty, unobserveproperty or an
+ Array containing a combination of
+ these terms.
+
+ It is considered to be good practice that each observeproperty has a corresponding
+ unobserveproperty unless the protocol supports implicit unsubscription mechanisms (e.g.,
+ heartbeat to detect connection loss).
+
+ The observation mechanism depends on the underlying protocol or sub-protocol. Having said that, it is not + guaranteed that the current Property value will be provided once the subscription is initiated. + Hence, it may be necessary to read the current Property value before/after the subscription to get + a first value. +
+ActionAffordance+ An Interaction Affordance that allows to invoke a function of the Thing, which manipulates state (e.g., + toggling a lamp on or off) or triggers a process on the Thing (e.g., dim a lamp over time). +
+| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
input |
+ Used to define the input data schema of the Action. | +optional | +
+ DataSchema
+ |
+
output |
+ Used to define the output data schema of the Action. | +optional | +
+ DataSchema
+ |
+
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. + | +with default | +
+ boolean
+ |
+
idempotent |
+ + Indicates whether the Action is idempotent (=true) or not. Informs whether the Action can be called + repeatedly with the same result, if present, based on the same input. + | +with default | +
+ boolean
+ |
+
synchronous |
+ + Indicates whether the action is synchronous (=true) or not. A synchronous action means that the + response of action contains all the information about the result of the action and no further + querying about the status of the action is needed. Lack of this keyword means that no claim on the + synchronicity of the action can be made. + | +optional | +
+ boolean
+ |
+
+ ActionAffordance is a
+ Subclass of the
+ InteractionAffordance
+ Class.
+ When a Form instance is within an ActionAffordance instance, the value assigned to op MUST
+ either be invokeaction, queryaction, cancelaction or an
+ Array
+ containing a combination of these terms.
+
+
EventAffordance+ An Interaction Affordance that describes an event source, which asynchronously pushes event data to + Consumers (e.g., overheating alerts). +
+| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
subscription |
+ + Defines data that needs to be passed upon subscription, e.g., filters or message format for setting + up Webhooks. + | +optional | +
+ DataSchema
+ |
+
data |
+ Defines the data schema of the Event instance messages pushed by the Thing. | +optional | +
+ DataSchema
+ |
+
dataResponse |
+ + Defines the data schema of the Event response messages sent by the consumer in a response to a data + message. + | +optional | +
+ DataSchema
+ |
+
cancellation |
+ + Defines any data that needs to be passed to cancel a subscription, e.g., a specific message to + remove a Webhook. + | +optional | +
+ DataSchema
+ |
+
+ EventAffordance is a
+ Subclass of the
+ InteractionAffordance
+ Class.
+ When a Form instance is within an EventAffordance instance, the value assigned to
+ op
+ MUST be either
+ subscribeevent, unsubscribeevent, or both terms within an
+ Array.
+
+ It is considered to be good practice that each subscribeevent has a corresponding
+ unsubscribeevent unless the protocol supports implicit unsubscription mechanisms (e.g.,
+ heartbeat to detect connection loss).
+
VersionInfo+ Metadata of a Thing that provides version information about the TD document. If required, additional + version information such as firmware and hardware version (term definitions outside of the TD namespace) + can be extended via the + TD Context Extension mechanism. +
+| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
instance |
+ Provides a version indicator of this TD. | +mandatory | +
+ string
+ |
+
model |
+ Provides a version indicator of the underlying TM. | +optional | +
+ string
+ |
+
+ It is recommended that the values within instances and model of the
+ VersionInfo Class follow
+ the semantic versioning pattern, where a sequence of three numbers separated by a dot indicates the major
+ version, minor version, and patch version, respectively. See [SEMVER] for details.
+
MultiLanguage+ A Map providing a set of human-readable texts in different languages identified by language tags + described in [[BCP47]]. See for example usages of + this container in a Thing Description instance. +
+
+ Each name of the MultiLanguage Map MUST be a language tag as defined in
+ [[!BCP47]].
+
+ Each value of the MultiLanguage Map MUST be of type string.
+
+
A data schema is an abstract notation for data contained in data formats.
++ The data schema vocabulary definition reflects a very common subset of the terms defined by JSON Schema + [[?JSON-SCHEMA]]. A JSON Schema [[?JSON-SCHEMA]] processor for + JSON Schema draft 7 can consume a data + schema. It is noted that data schema definitions within Thing Description instances are not limited to this + defined subset and may use additional terms found in JSON Schema using a TD Context Extension for the + additional terms as described in , otherwise these terms are + semantically ignored by TD Processors + (for details about semantic processing, please refer to + and the documentation under the namespace IRIs, e.g., + https://www.w3.org/2019/wot/td). +
+
+ In a TD, concrete data formats are specified in Forms (see ) using content types. When
+ the value of a content type in an instance of the Form is application/json, the data schema can
+ be processed directly by JSON Schema processors. Otherwise, Web of Things (WoT) Binding Templates
+ [[?WOT-BINDING-TEMPLATES]] defines data schema's available mappings to other content types such as XML
+ [[?xml]]. If the content type in an instance of the Form is not application/json and if no
+ mapping is defined for the content type, specifying a data schema does not make sense for the content type.
+
+ The following table contains content types which MAY use data schema to describe the structure of their + payloads. +
+| Format | +Content Type | +
|---|---|
| JSON/CBOR | +
+ application/json + application/ld+json + application/senml+json + application/cbor + application/senml+cbor + |
+
| XML/EXI | +
+ application/xml + application/senml+xml + application/exi + application/senml-exi + |
+
DataSchemaMetadata that describes the data format used. It can be used for validation.
+| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
@type |
+ JSON-LD keyword to label the object with semantic tags (or types) | +optional | +
+ string or
+ Array of
+ string
+ |
+
title |
+ + Provides a human-readable title (e.g., display a text for UI representation) based on a default + language. + | +optional | +
+ string
+ |
+
titles |
+ + Provides multi-language human-readable titles (e.g., display a text for UI representation in + different languages). Also see MultiLanguage. + | +optional | +
+ Map of MultiLanguage
+ |
+
description |
+ Provides additional (human-readable) information based on a default language. | +optional | +
+ string
+ |
+
descriptions |
+ + Can be used to support (human-readable) information in different languages. Also see + MultiLanguage. + | +optional | +
+ Map of MultiLanguage
+ |
+
const |
+ Provides a constant value. | +optional | +any type | +
default |
+ + Supply a default value. The value SHOULD validate against the data schema in which it resides. + | +optional | +any type | +
unit |
+ + Provides unit information that is used, e.g., in international science, engineering, and business. + To preserve uniqueness, it is recommended that the value of the unit points to a semantic definition + (also see Section + Semantic Annotations). + | +optional | +
+ string
+ |
+
oneOf |
+ + Used to ensure that the data is valid against one of the specified schemas in the array. This can be + used to describe multiple input or output schemas. + | +optional | +
+ Array of DataSchema
+ |
+
enum |
+ Restricted set of values provided as an array. | +optional | +Array of any type | +
readOnly |
+ + Boolean value that is a hint to indicate whether a property interaction / value is read only (=true) + or not (=false). + | +with default | +
+ boolean
+ |
+
writeOnly |
+ + Boolean value that is a hint to indicate whether a property interaction / value is write only + (=true) or not (=false). + | +with default | +
+ boolean
+ |
+
format |
+ + Allows validation based on a format pattern such as "date-time", "email", "uri", etc. (Also see + below.) + | +optional | +
+ string
+ |
+
type |
+ + Assignment of JSON-based data types compatible with JSON Schema (one of boolean, integer, number, + string, object, array, or null). + | +optional | +
+ anyURI (one
+ of object, array, string, number,
+ integer, boolean, or null)
+ |
+
The class DataSchema has the following subclasses:
ArraySchema
+ BooleanSchema
+ NumberSchema
+ IntegerSchema
+ ObjectSchema
+ StringSchema
+ NullSchema
+
+ The format string values are known from a fixed set of values and their corresponding format
+ rules defined in [JSON-SCHEMA] (Section 7.3 Defined Formats in particular).
+ Servients MAY use the format value to perform additional validation accordingly.
+ When a value that is not found in the known set of values is assigned to format, such a
+ validation SHOULD succeed.
+
any type (e.g., const,
+ default) follow data types compatible with JSON Schema (boolean, integer, number, string,
+ object, array, or null).
+
+ The format term is not widely implemented by JSON Schema tools. In addition, the term
+ format is being discussed by the JSON Schema standardisation community and may be replaced by
+ another mechanism or removed in a future JSON Schema version.
+
ArraySchema
+ Metadata describing data of type Array.
+ This Subclass is indicated by the
+ value array assigned to type in DataSchema instances.
+
| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
items |
+ Used to define the characteristics of an array. | +optional | +
+ DataSchema or Array of
+ DataSchema
+ |
+
minItems |
+ Defines the minimum number of items that have to be in the array. | +optional | +
+ unsignedInt
+ |
+
maxItems |
+ Defines the maximum number of items that have to be in the array. | +optional | +
+ unsignedInt
+ |
+
BooleanSchema
+ Metadata describing data of type boolean. This
+ Subclass is indicated by the value
+ boolean assigned to type in DataSchema instances.
+
NumberSchema
+ Metadata describing data of type number. This
+ Subclass is indicated by the value
+ number assigned to type in DataSchema instances.
+
| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
minimum |
+ + Specifies a minimum numeric value, representing an inclusive lower limit. Only applicable for + associated number or integer types. + | +optional | +
+ double
+ |
+
exclusiveMinimum |
+ + Specifies a minimum numeric value, representing an exclusive lower limit. Only applicable for + associated number or integer types. + | +optional | +
+ double
+ |
+
maximum |
+ + Specifies a maximum numeric value, representing an inclusive upper limit. Only applicable for + associated number or integer types. + | +optional | +
+ double
+ |
+
exclusiveMaximum |
+ + Specifies a maximum numeric value, representing an exclusive upper limit. Only applicable for + associated number or integer types. + | +optional | +
+ double
+ |
+
multipleOf |
+ + Specifies the multipleOf value number. The value must strictly greater than 0. Only applicable for + associated number or integer types. + | +optional | +
+ double
+ |
+
IntegerSchema
+ Metadata describing data of type integer. This
+ Subclass is indicated by the value
+ integer assigned to type in DataSchema instances.
+
| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
minimum |
+ + Specifies a minimum numeric value, representing an inclusive lower limit. Only applicable for + associated number or integer types. + | +optional | +
+ integer
+ |
+
exclusiveMinimum |
+ + Specifies a minimum numeric value, representing an exclusive lower limit. Only applicable for + associated number or integer types. + | +optional | +
+ integer
+ |
+
maximum |
+ + Specifies a maximum numeric value, representing an inclusive upper limit. Only applicable for + associated number or integer types. + | +optional | +
+ integer
+ |
+
exclusiveMaximum |
+ + Specifies a maximum numeric value, representing an exclusive upper limit. Only applicable for + associated number or integer types. + | +optional | +
+ integer
+ |
+
multipleOf |
+ + Specifies the multipleOf value number. The value must strictly greater than 0. Only applicable for + associated number or integer types. + | +optional | +
+ integer
+ |
+
ObjectSchema
+ Metadata describing data of type
+ Object. This
+ Subclass is indicated by the value
+ object assigned to type in DataSchema instances.
+
| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
properties |
+ Data schema nested definitions. | +optional | +
+ Map of DataSchema
+ |
+
required |
+
+ Defines which members of the object type are mandatory, i.e. which members are mandatory in the
+ payload that is to be sent (e.g. input of invokeaction, writeproperty) and
+ what members will be definitely delivered in the payload that is being received (e.g. output of
+ invokeaction, readproperty)
+ |
+ optional | +
+ Array of
+ string
+ |
+
StringSchema
+ Metadata describing data of type string. This
+ Subclass is indicated by the value
+ string assigned to type in DataSchema instances.
+
| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
minLength |
+ Specifies the minimum length of a string. Only applicable for associated string types. | +optional | +
+ unsignedInt
+ |
+
maxLength |
+ Specifies the maximum length of a string. Only applicable for associated string types. | +optional | +
+ unsignedInt
+ |
+
pattern |
+ + Provides a regular expression to express constraints of the string value. The regular expression + must follow the [[ECMA-262]] dialect. + | +optional | +
+ string
+ |
+
contentEncoding |
+ + Specifies the encoding used to store the contents, as specified in [[RFC2045]] (Section 6.1) and + [[RFC4648]]. + | +optional | +
+ string
+ (e.g., 7bit, 8bit, binary, quoted-printable,
+ base16, base32, or base64)
+ |
+
contentMediaType |
+ Specifies the MIME type of the contents of a string value, as described in [[RFC2046]]. | +optional | +
+ string
+ (e.g., image/png, or audio/mpeg)
+ |
+
+ The length of a string (i.e., minLength and maxLength) is defined as the number
+ of Unicode code points, as defined by [[RFC8259]]. Note that some
+ user-perceived characters
+ are composed of more than one Unicode code point. Arbitrary index values might not fall on these grapheme
+ boundaries, so truncation according to maxLength might alter the appearance or meaning of the
+ string.
+
NullSchema
+ Metadata describing data of type null. This subclass is indicated by the value
+ null assigned to type in DataSchema instances. This Subclass
+ describes only one acceptable value, namely null. It is important to note that
+ null does not mean the absence of a value. It is analogous to null in
+ JavaScript, None in Python, null in Java and nil in Ruby
+ programming languages. It can be used as part of a oneOf declaration, where it is used to
+ indicate, that the data can also be null.
+
A data schema is an abstract notation for data contained in data formats.
-- The data schema vocabulary definition reflects a very common subset of the terms defined by JSON Schema - [[?JSON-SCHEMA]]. A JSON Schema [[?JSON-SCHEMA]] processor for - JSON Schema draft 7 can consume a data - schema. It is noted that data schema definitions within Thing Description instances are not limited to this - defined subset and may use additional terms found in JSON Schema using a TD Context Extension for the - additional terms as described in , otherwise these terms are - semantically ignored by TD Processors - (for details about semantic processing, please refer to - and the documentation under the namespace IRIs, e.g., - https://www.w3.org/2019/wot/td). -
+
- In a TD, concrete data formats are specified in Forms (see ) using content types. When
- the value of a content type in an instance of the Form is application/json, the data schema can
- be processed directly by JSON Schema processors. Otherwise, Web of Things (WoT) Binding Templates
- [[?WOT-BINDING-TEMPLATES]] defines data schema's available mappings to other content types such as XML
- [[?xml]]. If the content type in an instance of the Form is not application/json and if no
- mapping is defined for the content type, specifying a data schema does not make sense for the content type.
+ This specification provides a selection of well-established security mechanisms that are directly built into
+ protocols eligible as Protocol Bindings for W3C WoT or are widely in use with those protocols. The
+ current set of HTTP security schemes is partly based on
+ OpenAPI 3.0.1
+ (see also [[?OPENAPI]]). However while the HTTP security schemes, Vocabulary, and syntax given in
+ this specification share many similarities with OpenAPI, they are not compatible.
- The following table contains content types which MAY use data schema to describe the structure of their - payloads. + Generally, security schemes require some form of secure transport to be effective, such as TLS or DTLS. + Requirements for the use of secure transport are given in Section + in this document and in the Security Considerations section of [[wot-architecture11]].
-| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
@type |
+ JSON-LD keyword to label the object with semantic tags (or types). | +optional | +
+ string or
+ Array of
+ string
+ |
+
description |
+ Provides additional (human-readable) information based on a default language. | +optional | +
+ string
+ |
+
descriptions |
+ + Can be used to support (human-readable) information in different languages. Also see + MultiLanguage. + | +optional | +
+ Map of MultiLanguage
+ |
+
proxy |
+ + URI of the proxy server this security configuration provides access to. If not given, the + corresponding security configuration is for the endpoint. + | +optional | +
+ anyURI
+ |
+
scheme |
+ Identification of the security mechanism being configured. | +mandatory | +
+ string
+ (e.g., nosec, combo, basic, digest,
+ bearer, psk, oauth2, apikey, or
+ auto)
+ |
+
The class SecurityScheme has the following subclasses:
NoSecurityScheme
+ AutoSecurityScheme
+ ComboSecurityScheme
+ BasicSecurityScheme
+ DigestSecurityScheme
+ APIKeySecurityScheme
+ BearerSecurityScheme
+ PSKSecurityScheme
+ OAuth2SecurityScheme
+ NoSecurityScheme
+ A security configuration corresponding to identified by the
+ Vocabulary Term
+ nosec (i.e., "scheme": "nosec"), indicating there is no authentication or other
+ mechanism required to access the resource.
+
AutoSecurityScheme
+ An automatic authentication security configuration identified by the term auto (i.e.,
+ "scheme": "auto"). This scheme indicates that the security parameters are going to be
+ negotiated by the underlying protocols at runtime, subject to the respective specifications for the
+ protocol (e.g. [[!RFC8288]] for Basic Authentication when using HTTP).
+
ComboSecurityScheme
+ A combination of other security schemes identified by the Vocabulary Term combo (i.e.,
+ "scheme": "combo"). Elements of this scheme define various ways in which other named schemes
+ defined in securityDefinitions, including other
+ ComboSecurityScheme definitions, are to be combined to
+ create a new scheme definition.
+ Exactly one of either oneOf or allOf vocabulary terms MUST be
+ included.
+
+ Only security scheme definitions which can be used together can be combined with allOf. For
+ example, it is not possible in general to combine different OAuth 2.0 flows together using
+ allOf unless one applies to a proxy and one to the endpoint. Note that when multiple named
+ security scheme definitions are listed in a security field the same semantics apply as in an
+ allOf combination (and the same limitations on allowable combinations). The
+ oneOf combination is equivalent to using different security schemes on forms that are
+ otherwise identical. In this sense a oneOf scheme is not an essential feature but it does
+ avoid redundancy in such cases.
+
| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
oneOf |
+ + Array of two or more strings identifying other named security scheme definitions, any one of which, + when satisfied, will allow access. Only one may be chosen for use. + | +mandatory | +
+ Array of
+ string
+ |
+
allOf |
+ + Array of two or more strings identifying other named security scheme definitions, all of which must + be satisfied for access. + | +mandatory | +
+ Array of
+ string
+ |
+
BasicSecurityScheme
+ Basic Authentication [RFC7617] security configuration identified by the
+ Vocabulary Term
+ basic (i.e., "scheme": "basic"), using an unencrypted username and password.
+
| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
name |
+ Name for query, header, cookie, or uri parameters. | +optional | +
+ string
+ |
+
in |
+ Specifies the location of security authentication information. | +with default | +
+ string (one
+ of header, query, body, cookie, or
+ auto)
+ |
+
DigestSecurityScheme
+ Digest Access Authentication [RFC7616] security configuration identified by the
+ Vocabulary Term
+ digest (i.e., "scheme": "digest"). This scheme is similar to basic
+ authentication but with added features to avoid man-in-the-middle attacks.
+
| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
name |
+ Name for query, header, cookie, or uri parameters. | +optional | +
+ string
+ |
+
in |
+ Specifies the location of security authentication information. | +with default | +
+ string (one
+ of header, query, body, cookie, or
+ auto)
+ |
+
qop |
+ Quality of protection. | +with default | +
+ string (one
+ of auth, or auth-int)
+ |
+
APIKeySecurityScheme
+ API key authentication security configuration identified by the
+ Vocabulary Term
+ apikey (i.e., "scheme": "apikey"). This scheme is to be used when the access
+ token is opaque, for example when a key in an unknown or proprietary format is provided by a cloud service
+ provider. In this case the key may not be using a standard token format. This scheme indicates that the
+ key provided by the service provider needs to be supplied as part of service requests using the mechanism
+ indicated by the "in" field.
+
| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
name |
+ Name for query, header, cookie, or uri parameters. | +optional | +
+ string
+ |
+
in |
+ Specifies the location of security authentication information. | +with default | +
+ string (one
+ of header, query, body, cookie,
+ uri, or auto)
+ |
+
BearerSecurityScheme
+ Bearer Token [RFC6750] security configuration identified by the
+ Vocabulary Term
+ bearer (i.e., "scheme": "bearer") 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. For format, the value
+ jwt indicates conformance with [RFC7519], jws indicates conformance with [RFC7797], cwt indicates conformance with [RFC8392], and jwe indicates conformance with [RFC7516], with values for alg interpreted consistently with those standards.
+ Other formats and algorithms for bearer tokens MAY be specified in vocabulary extensions.
+
| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
authorization |
+ URI of the authorization server. | +optional | +
+ anyURI
+ |
+
name |
+ Name for query, header, cookie, or uri parameters. | +optional | +
+ string
+ |
+
in |
+ Specifies the location of security authentication information. | +with default | +
+ string (one
+ of header, query, body, cookie, or
+ auto)
+ |
+
alg |
+ Encoding, encryption, or digest algorithm. | +with default | +
+ string
+ (e.g., ES256, or ES512-256)
+ |
+
format |
+ Specifies format of security authentication information. | +with default | +
+ string
+ (e.g., jwt, cwt, jwe, or jws)
+ |
+
PSKSecurityScheme
+ Pre-shared key authentication security configuration identified by the
+ Vocabulary Term
+ psk (i.e., "scheme": "psk"). This is meant to identify that a standard is used
+ for pre-shared keys such as TLS-PSK [[RFC4279]], and that the ciphersuite used for keys will be
+ established during protocol negotiation.
+
| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
identity |
+ Identifier providing information which can be used for selection or confirmation. | +optional | +
+ string
+ |
+
OAuth2SecurityScheme
+ OAuth 2.0 authentication security configuration for systems conformant with [[!RFC6749]] and [[!RFC8252]],
+
+ identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2").
+
| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
authorization |
+ + URI of the authorization server. + | +optional | +
+ anyURI
+ |
+
token |
+ URI of the token server. | +optional | +
+ anyURI
+ |
+
refresh |
+ URI of the refresh server. | +optional | +
+ anyURI
+ |
+
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. The values associated with a form SHOULD be chosen from those defined in an
+ OAuth2SecurityScheme active on that form.
+ |
+ optional | +
+ string or
+ Array of
+ string
+ |
+
flow |
+ Authorization flow. | +mandatory | +
+ string
+ (e.g., code, or client)
+ |
+
+ For the code flow both authorization and token
+ vocabulary terms MUST be included.
+ For the client flow token vocabulary term MUST be included.
+ For the client flow authorization vocabulary term MUST NOT be
+ included.
+
+ The mandatory elements for each flow are summarized in the following table:
+
| Format | -Content Type | +Element | +code |
+ client |
|---|---|---|---|---|
| JSON/CBOR | -
- application/json - application/ld+json - application/senml+json - application/cbor - application/senml+cbor - |
+ authorization |
+ mandatory | +omit | +
| XML/EXI | -
- application/xml - application/senml+xml - application/exi - application/senml-exi - |
+ token |
+ mandatory | +mandatory | +
DataSchemaMetadata that describes the data format used. It can - be used for validation.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
@type | JSON-LD keyword to label the object with semantic tags (or types) | optional | string or Array of string |
title | Provides a human-readable title (e.g., display - a text for UI representation) based on a default - language. | optional | string |
titles | Provides multi-language human-readable titles - (e.g., display a text for UI representation in - different languages). Also see MultiLanguage. | optional | Map of MultiLanguage |
description | Provides additional (human-readable) - information based on a default language. | optional | string |
descriptions | Can be used to support (human-readable) - information in different languages. Also see MultiLanguage. | optional | Map of MultiLanguage |
const | Provides a constant value. | optional | any type |
default | Supply a default value. The value SHOULD validate against the data schema in which it resides. | optional | any type |
unit | Provides unit information that is used, e.g., - in international science, engineering, and - business. To preserve uniqueness, it is recommended that - the value of the unit points to a semantic definition (also see Section Semantic Annotations). | optional | string |
oneOf | Used to ensure that the data is valid against - one of the specified schemas in the array. This can be used to describe multiple input or output schemas. | optional | Array of DataSchema |
enum | Restricted set of values provided as an - array. | optional | Array of any type |
readOnly | Boolean value that is a hint to indicate - whether a property interaction / value is read only - (=true) or not (=false). | with default | boolean |
writeOnly | Boolean value that is a hint to indicate - whether a property interaction / value is write - only (=true) or not (=false). | with default | boolean |
format | Allows validation based on a format pattern - such as "date-time", "email", "uri", etc. (Also see - below.) | optional | string |
type | Assignment of JSON-based data types compatible - with JSON Schema (one of boolean, integer, number, - string, object, array, or null). | optional | anyURI (one of object, array, string, number, integer, boolean, or null) |
The class DataSchema has the following subclasses:
The format string values are known from a
- fixed set of values and their corresponding format rules
- defined in [JSON-SCHEMA]
- (Section 7.3 Defined Formats in particular). Servients MAY use the
- format value to perform additional
- validation accordingly. When a value that is
- not found in the known set of values is assigned to
- format, such a validation SHOULD succeed.
any type (e.g., const, default) follow data types compatible with JSON Schema (boolean, integer, number, string, object, array, or null).
- The format term is not widely implemented by JSON Schema tools.
- In addition, the term format is being discussed by the JSON Schema standardisation community and may be replaced by another mechanism or removed in a future JSON Schema version.
ArraySchemaMetadata describing data of type Array. This
- Subclass is indicated by the
- value array assigned to type in
- DataSchema instances.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
items | Used to define the characteristics of an - array. | optional | DataSchema or Array of DataSchema |
minItems | Defines the minimum number of items that have - to be in the array. | optional | unsignedInt |
maxItems | Defines the maximum number of items that have - to be in the array. | optional | unsignedInt |
BooleanSchemaMetadata describing data of type boolean.
- This Subclass is indicated by the
- value boolean assigned to type
- in DataSchema instances.
NumberSchemaMetadata describing data of type number.
- This Subclass is indicated by the
- value number assigned to type
- in DataSchema instances.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
minimum | Specifies a minimum numeric value, representing an inclusive lower limit. Only - applicable for associated number or integer - types. | optional | double |
exclusiveMinimum | Specifies a minimum numeric value, representing an exclusive lower limit. Only - applicable for associated number or integer - types. | optional | double |
maximum | Specifies a maximum numeric value, representing an inclusive upper limit. Only - applicable for associated number or integer - types. | optional | double |
exclusiveMaximum | Specifies a maximum numeric value, representing an exclusive upper limit. Only - applicable for associated number or integer - types. | optional | double |
multipleOf | Specifies the multipleOf value number. The value must strictly greater than 0. Only applicable for associated number or integer types. | optional | double |
IntegerSchemaMetadata describing data of type integer.
- This Subclass is indicated by the
- value integer assigned to type
- in DataSchema instances.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
minimum | Specifies a minimum numeric value, representing an inclusive lower limit. Only - applicable for associated number or integer - types. | optional | integer |
exclusiveMinimum | Specifies a minimum numeric value, representing an exclusive lower limit. Only - applicable for associated number or integer - types. | optional | integer |
maximum | Specifies a maximum numeric value, representing an inclusive upper limit. Only - applicable for associated number or integer - types. | optional | integer |
exclusiveMaximum | Specifies a maximum numeric value, representing an exclusive upper limit. Only - applicable for associated number or integer - types. | optional | integer |
multipleOf | Specifies the multipleOf value number. The value must strictly greater than 0. Only applicable for associated number or integer types. | optional | integer |
ObjectSchemaMetadata describing data of type Object.
- This Subclass is indicated by the
- value object assigned to type
- in DataSchema instances.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
properties | Data schema nested definitions. | optional | Map of DataSchema |
required | Defines which members of the object type are mandatory, i.e. which members are mandatory in the payload that is to be sent (e.g. input of invokeaction, writeproperty) and what members will be definitely delivered in the payload that is being received (e.g. output of invokeaction, readproperty) | optional | Array of string |
StringSchemaMetadata describing data of type string.
- This Subclass is indicated by the
- value string assigned to type
- in DataSchema instances.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
minLength | Specifies the minimum length of a string. Only applicable for associated string types. | optional | unsignedInt |
maxLength | Specifies the maximum length of a string. Only applicable for associated string types. | optional | unsignedInt |
pattern | Provides a regular expression to express constraints of the string value. The regular expression must follow the [[ECMA-262]] dialect. | optional | string |
contentEncoding | Specifies the encoding used to store the contents, as specified in [[RFC2045]] (Section 6.1) and [[RFC4648]]. | optional | string (e.g., 7bit, 8bit, binary, quoted-printable, base16, base32, or base64) |
contentMediaType | Specifies the MIME type of the contents of a string value, as described in [[RFC2046]]. | optional | string (e.g., image/png, or audio/mpeg) |
The length of a string (i.e., minLength and
- maxLength) is defined as the number
- of Unicode code points, as defined by [[RFC8259]].
- Note that some user-perceived characters are composed of more than one Unicode code point. Arbitrary index values might not fall on these grapheme boundaries, so truncation according to maxLength might alter the appearance or meaning of the string.
-
NullSchemaMetadata describing data of type null. This subclass is indicated by the value null assigned to type in DataSchema instances.
- This Subclass describes only one acceptable value, namely null.
- It is important to note that null does not mean the absence of a value. It is analogous to null in JavaScript, None in Python, null in Java and nil in Ruby programming languages.
- It can be used as part of a oneOf declaration, where it is used to indicate, that the data can also be null.
refresh- This specification provides a selection of well-established security mechanisms that are directly built into - protocols eligible as Protocol Bindings for W3C WoT or are widely in use with those protocols. The - current set of HTTP security schemes is partly based on - OpenAPI 3.0.1 - (see also [[?OPENAPI]]). However while the HTTP security schemes, Vocabulary, and syntax given in - this specification share many similarities with OpenAPI, they are not compatible. -
+
- Generally, security schemes require some form of secure transport to be effective, such as TLS or DTLS.
- Requirements for the use of secure transport are given in Section
- in this document and in the Security Considerations section of [[wot-architecture11]].
+ The present model provides a representation for (typed) Web links and Web forms exposed by a Thing.
+ The Link class definition reflects a very common subset of the terms defined in Web Linking
+ [[!RFC8288]]. The defined terms can be used, e.g., to describe the relation to another Thing such as
+ a Lamp Thing is controlled by a Switch Thing. The Form class corresponds to a
+ newly introduced form of hypermedia control to manipulate the state of Things (and other Web
+ resources).
SecuritySchemeMetadata describing the configuration of a security
- mechanism. The value assigned to the name
- scheme MUST be defined within a
- Vocabulary
- included in the Thing Description,
- either in the standard Vocabulary defined
- in § 5. TD
- Information Model or in a TD Context
- Extension.
-
- For all security schemes, - any keys, passwords, or other sensitive information directly providing access - MUST NOT be stored in the TD and should instead - be shared and stored out-of-band via other mechanisms. - The purpose of a TD is to describe how to access a Thing if and only if a Consumer - already has authorization, and is not meant be used to grant that authorization. -
Each security scheme object used in a TD defines a set of requirements to be met before access can be granted. - We say a security scheme is satisfied when all its requirements are met. - In some cases requirements from multiple security schemes will have to be met before access can be granted. -
- Security schemes generally may require additional authentication
- parameters, such as a password or key.
- The location of this information is indicated by the
- value associated with the name in, often in combination with the value associated with name.
- The value associated with in can take one of the following values:
-
header:name.query:name.body:name.
- When used in the context of a
- body security information location, the value of name
- MUST be in the form of a JSON pointer [[!RFC6901]] relative to
- the root of the input DataSchema for each interaction it is used with.
- Since this value is not a fragment identifier, and is not relative to the root of the TD but
- to whichever data schemas the security scheme is bound to, this value should not start with #;
- it is a "pure" JSON pointer.
- Since this value is not a fragment identifier, it also does not
- need to URL-encode special characters.
- The targeted element may or may not already exist at the specified location in the referenced object or array schema (consequently the mechanism is not applicable to simple types).
- If it does not, it will be inserted. This avoids having to duplicate definitions in the data schemas of
- every interaction.
- When an element
- of a data schema indicated by a JSON pointer indicated in a body locator
- does not already exist in the indicated schema, it MUST
- be possible to insert the indicated element
- at the location indicated by the pointer.
- The JSON pointer
- used in the body locator MAY
- use the "-" character to indicate a non-existent array element when
- it is necessary to insert an element after the last element of an existing array.
-
- The element referenced
- (or created) by a
- body security information location
- MUST be required and of type "string".
- If name is not given, it is assumed the entire body
- is to be used as the security parameter.
- cookie:name.
- uri:name.
- This is more general than the query mechanism but more complex.
- The value uri
- SHOULD be specified
- for the name in in a security scheme only if
- query is not applicable.
- The URIs provided
- in interactions where a security scheme using uri as the value for in
- MUST be a URI template including the defined variable.
-
- auto:auto
- is set for the in field of a SecurityScheme,
- then the name field SHOULD NOT be set.
- In this case, the application of the SecurityScheme is subject to
- the respective specification for the given protocol (e.g. [[!RFC8288]] when using the
- BasicSecurityScheme with HTTP).
-
- If multiple parameters are needed for a security scheme, repeat the security scheme definition for
- each parameter and combine them using a combo security scheme and allOf.
- In some cases parameters may not actually be secret but a user may wish to leave them
- out of the TD to help protect privacy. As an example of this, some security mechanisms
- require both a client identifier and a secret key. In theory, the client identifier is
- public however it may be hard to update and pose a tracking risk. In such a case it can
- be provided as an additional security parameter so it does not appear in the TD.
-
- The names of URI variables
- declared in a SecurityScheme
- MUST be distinct from all other URI variables
- declared in the TD.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
@type | JSON-LD keyword to label the object with semantic tags (or types). | optional | string or Array of string |
description | Provides additional (human-readable) - information based on a default language. | optional | string |
descriptions | Can be used to support (human-readable) - information in different languages. Also see MultiLanguage. | optional | Map of MultiLanguage |
proxy | URI of the proxy server this security - configuration provides access to. If not given, the - corresponding security configuration is for the - endpoint. | optional | anyURI |
scheme | Identification of the security mechanism being - configured. | mandatory | string (e.g., nosec, combo, basic, digest, bearer, psk, oauth2, apikey, or auto) |
The class SecurityScheme has the following subclasses:
NoSecuritySchemeA security configuration corresponding to identified
- by the Vocabulary Term
- nosec (i.e., "scheme":
- "nosec"), indicating there is no authentication or
- other mechanism required to access the resource.
AutoSecuritySchemeAn automatic authentication security configuration identified by the term auto (i.e., "scheme": "auto"). This scheme indicates that the security parameters are going to be negotiated by the underlying protocols at runtime, subject to the respective specifications for the protocol (e.g. [[!RFC8288]] for Basic Authentication when using HTTP).
ComboSecuritySchemeA combination of other security schemes identified by the Vocabulary Term combo (i.e., "scheme": "combo"). Elements of this scheme define various ways in which other named schemes defined in securityDefinitions, including other ComboSecurityScheme definitions, are to be combined to create a new scheme definition. Exactly one of either oneOf or allOf vocabulary terms MUST be included. Only security scheme definitions which can be used together can be combined with allOf. For example, it is not possible in general to combine different OAuth 2.0 flows together using allOf unless one applies to a proxy and one to the endpoint. Note that when multiple named security scheme definitions are listed in a security field the same semantics apply as in an allOf combination (and the same limitations on allowable combinations). The oneOf combination is equivalent to using different security schemes on forms that are otherwise identical. In this sense a oneOf scheme is not an essential feature but it does avoid redundancy in such cases.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
oneOf | Array of two or more strings identifying other named security scheme definitions, any one of which, when satisfied, will allow access. Only one may be chosen for use. | mandatory | Array of string |
allOf | Array of two or more strings identifying other named security scheme definitions, all of which must be satisfied for access. | mandatory | Array of string |
BasicSecuritySchemeBasic Authentication [RFC7617]
- security configuration identified by the Vocabulary Term basic (i.e.,
- "scheme": "basic"), using an unencrypted
- username and password.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
name | Name for query, header, cookie, or uri - parameters. | optional | string |
in | Specifies the location of security - authentication information. | with default | string (one of header, query, body, cookie, or auto) |
DigestSecuritySchemeDigest Access Authentication [RFC7616]
- security configuration identified by the Vocabulary Term digest (i.e.,
- "scheme": "digest"). This scheme is similar
- to basic authentication but with added features to avoid
- man-in-the-middle attacks.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
name | Name for query, header, cookie, or uri - parameters. | optional | string |
in | Specifies the location of security - authentication information. | with default | string (one of header, query, body, cookie, or auto) |
qop | Quality of protection. | with default | string (one of auth, or auth-int) |
APIKeySecuritySchemeAPI key authentication security configuration
- identified by the Vocabulary Term
- apikey (i.e., "scheme":
- "apikey").
- This scheme is to be used when the access token is opaque,
- for example when a key in an unknown or proprietary format is provided by a cloud service provider.
- In this case the key may not be using a standard token format.
- This scheme indicates that the key provided by the service provider
- needs to be supplied as part
- of service requests using the mechanism indicated by the "in" field.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
name | Name for query, header, cookie, or uri - parameters. | optional | string |
in | Specifies the location of security - authentication information. | with default | string (one of header, query, body, cookie, uri, or auto) |
BearerSecuritySchemeBearer Token [RFC6750]
- security configuration identified by the Vocabulary Term bearer (i.e.,
- "scheme": "bearer") 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. For format, the value
- jwt indicates conformance with
- [RFC7519],
- jws indicates conformance with
- [RFC7797],
- cwt indicates conformance with
- [RFC8392], and
- jwe indicates conformance with
- [RFC7516], with
- values for alg interpreted consistently with
- those standards. Other formats and
- algorithms for bearer tokens MAY be specified in vocabulary
- extensions.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
authorization | URI of the authorization server. | optional | anyURI |
name | Name for query, header, cookie, or uri - parameters. | optional | string |
in | Specifies the location of security - authentication information. | with default | string (one of header, query, body, cookie, or auto) |
alg | Encoding, encryption, or digest algorithm. | with default | string (e.g., ES256, or ES512-256) |
format | Specifies format of security authentication - information. | with default | string (e.g., jwt, cwt, jwe, or jws) |
PSKSecuritySchemePre-shared key authentication security configuration
- identified by the Vocabulary Term
- psk (i.e., "scheme":
- "psk").
- This is meant to identify that a standard is used for pre-shared keys such as TLS-PSK [[RFC4279]],
- and that the ciphersuite used for keys will be established during protocol negotiation.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
identity | Identifier providing information which can be - used for selection or confirmation. | optional | string |
OAuth2SecuritySchemeOAuth 2.0 authentication security configuration
- for systems conformant with [[!RFC6749]] and [[!RFC8252]], identified
- by the Vocabulary Term oauth2 (i.e.,
- "scheme": "oauth2").
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
authorization | URI of the authorization server. | optional | anyURI |
token | URI of the token server. | optional | anyURI |
refresh | URI of the refresh server. | optional | anyURI |
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. The values associated with a
- form SHOULD be chosen from those defined in an
- OAuth2SecurityScheme active on that
- form. | optional | string or Array of string |
flow | Authorization flow. | mandatory | string (e.g., code, or client) |
For
- the
+ A link can be viewed as a statement of the form "link context has a
+ relation type resource at link target", where the optional target attributes may further describe the resource.
+
+ The code flow both authorization and token vocabulary terms
- MUST be included. For
- the client flow token vocabulary term MUST be included.
- For the
- client flow authorization vocabulary term MUST NOT be included.
- The mandatory elements for each flow are summarized in the
- following table:
+
+ Link
+
+
+
+
+
+ Vocabulary term
+ Description
+ Assignment
+ Type
+
+
+ hrefTarget IRI of a link or submission target of a form.
+ mandatory
+
+
+ anyURI
+
+
+ type
+ Target attribute providing a hint indicating what the media type [RFC2046] of the result of dereferencing the link should be.
+
+ optional
+
+
+ string
+
+
+ relA link relation type identifies the semantics of a link.
+ optional
+
+
+ string
+
+
+ anchor
+ Overrides the link context (by default the Thing itself identified by its
+ id) with the
+ given URI or IRI.
+ optional
+
+
+ anyURI
+
+
+ sizes
+ Target attribute that specifies one or more sizes for the referenced icon. Only applicable for
+ relation type "icon". The value pattern follows {Height}x{Width} (e.g., "16x16", "16x16 32x32").
+
+ optional
+
+
+ string
+
+
+
+ hreflang
+ The hreflang attribute specifies the language of a linked document. The value of this must be a
+ valid language tag [[BCP47]].
+
+ optional
+
+
+ string or
+ Array of
+ string
+ hreflang attribute is allowed to be a string or array in this
+ version of the spec. Depending on the result of [[LINKSET-MEDIA-TYPES]] the values of
+ hrefLang can be restricted to array only.
- Element codeclientauthorizationmandatory omit tokenmandatory mandatory refreshoptional optional
- The present model provides a representation for (typed) Web links and Web forms exposed by a Thing.
- The Link class definition reflects a very common subset of the terms defined in Web Linking
- [[!RFC8288]]. The defined terms can be used, e.g., to describe the relation to another Thing such as
- a Lamp Thing is controlled by a Switch Thing. The Form class corresponds to a
- newly introduced form of hypermedia control to manipulate the state of Things (and other Web
- resources).
-
LinkA link can be viewed as a statement of the form - "link context has a relation - type resource at link target", - where the optional target attributes may - further describe the resource.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
href | Target IRI of a link or submission target of a - form. | mandatory | anyURI |
type | Target attribute providing a hint indicating - what the media type [RFC2046] - of the result of dereferencing the link should - be. | optional | string |
rel | A link relation type identifies the semantics - of a link. | optional | string |
anchor | Overrides the link context (by default the
- Thing itself identified by its id)
- with the given URI or IRI. | optional | anyURI |
sizes | Target attribute that specifies one or more sizes for the referenced icon. - Only applicable for relation type "icon". The value pattern follows - {Height}x{Width} (e.g., "16x16", "16x16 32x32"). | optional | string |
hreflang | The hreflang attribute specifies the language of a linked document. The value of this must be a valid language tag [[BCP47]]. | optional | string or Array of string |
- The hreflang attribute is allowed to be a string or array in this version of the spec. Depending on the result of [[LINKSET-MEDIA-TYPES]] the values of hrefLang can be restricted to array only.
-
Link relations can be used to describe relations such as to other Things (e.g., a Switch Thing controls a Lamp Thing), to a specific kind of Thing Models (e.g., a Thing Description - is an instance of a specific Thing Model), or to further documentations information (e.g., device manual of a Thing). It is recommended to reuse existing and established - Link Relation definitions from IANA. -
-In the following a best practice relation type table is introduced that is recommended to use within WoT Thing Description - or Thing Model instances. -
-| Value | -Occurrence | -Explanation | -Source of value origin | -||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
+ + Link relations can be used to describe relations such as to other Things (e.g., a Switch Thing controls a + Lamp Thing), to a specific kind of Thing Models (e.g., a Thing Description is an instance of a specific + Thing Model), or to further documentations information (e.g., device manual of a Thing). It is recommended + to reuse existing and established + Link Relation definitions from IANA. + ++ In the following a best practice relation type table is introduced that is recommended to use within WoT + Thing Description or Thing Model instances. + +
|
+
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
href | Target IRI of a link or submission target of a - form. | mandatory | anyURI |
contentType | Assign a content type based on a media type
- (e.g., text/plain) and potential
- parameters (e.g., charset=utf-8) for
- the media type [RFC2046]. | with default | string |
contentCoding | Content coding values indicate an encoding - transformation that has been or can be applied to a - representation. Content codings are primarily used - to allow a representation to be compressed or - otherwise usefully transformed without losing the - identity of its underlying media type and without - loss of information. Examples of content coding - include "gzip", "deflate", etc. . | optional | string |
security | Set of security definition names, chosen from
- those defined in securityDefinitions.
- These must all be satisfied for access to resources. | optional | string or Array of 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. The values associated with a
- form SHOULD be chosen from those defined in an
- OAuth2SecurityScheme active on that
- form. | optional | string or Array of string |
response | This optional term can be used if, e.g., the - output communication metadata differ from input - metadata (e.g., output contentType differ from the - input contentType). The response name contains - metadata that is only valid for the primary response - messages. | optional | ExpectedResponse |
additionalResponses | This optional term can be used if additional expected responses - are possible, e.g. for error reporting. Each additional response needs to be - distinguished from others in some way (for example, by specifying - a protocol-specific error code), and may also have its own data schema. | optional | Array of AdditionalExpectedResponse |
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 such as long polling
- (longpoll), WebSub [websub]
- (websub), Server-Sent Events
- (sse) [html] (also known as
- EventSource). Please note that there is no
- restriction on the subprotocol selection and other
- mechanisms can also be announced by this
- subprotocol term. | optional | string (e.g., longpoll, websub, or sse) |
op | Indicates the semantic intention of performing - the operation(s) 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 for which and allows the client to select - the correct form for the operation required. op can - be assigned one or more interaction verb(s) each - representing a semantic intention of an - operation. | with default | string or Array of string (one of readproperty, writeproperty, observeproperty, unobserveproperty, invokeaction, queryaction, cancelaction, subscribeevent, unsubscribeevent, readallproperties, writeallproperties, readmultipleproperties, writemultipleproperties, observeallproperties, unobserveallproperties, subscribeallevents, unsubscribeallevents, or queryallactions) |
Possible values for the contentCoding
- property can be found, e.g., in the
- IANA HTTP content coding registry.
The list of possible operation types of a form is - fixed. As of this version of the specification, it only - includes the well-known types necessary to implement the - WoT interaction model described in [wot-architecture11]. - Future versions of the standard may extend this list but - operations types - MUST be restricted to the values in the - table below.
- -| Operation Type | -Description | -
|---|---|
| readproperty | -Identifies the read operation on - Property Affordances to retrieve the - corresponding data. | -
| writeproperty | -Identifies the write operation on - Property Affordances to update the - corresponding data. | -
| observeproperty | -Identifies the observe operation on - Property Affordances to be notified with - the new data when the Property is - updated. | -
| unobserveproperty | -Identifies the unobserve - operation on Property Affordances to stop - the corresponding notifications. | -
| invokeaction | -Identifies the invoke operation on - Action Affordances to perform the - corresponding action. | -
| queryaction | -Identifies the querying operation on - Action Affordances to get the status of the - corresponding action. | -
| cancelaction | -Identifies the cancel operation on - Action Affordances to cancel the ongoing - corresponding action. | -
| subscribeevent | -Identifies the subscribe operation - on Event Affordances to be notified by - the Thing when the event occurs. | -
| unsubscribeevent | -Identifies the unsubscribe - operation on Event Affordances to stop - the corresponding notifications. | -
| readallproperties | -Identifies the readallproperties - operation on a Thing to retrieve the - data of all Properties in a single interaction. | -
| writeallproperties | -Identifies the writeallproperties - operation on a Thing to update the - data of all writable Properties in a single interaction. | -
| readmultipleproperties | -Identifies the readmultipleproperties - operation on a Thing to retrieve the - data of selected Properties in a single interaction. | -
| writemultipleproperties | -Identifies the writemultipleproperties - operation on a Thing to update the - data of selected writable Properties in a single interaction. | -
| observeallproperties | -Identifies the observeallproperties operation on - Properties to be notified with new data when any Property is - updated. | -
| unobserveallproperties | -Identifies the unobserveallproperties operation on - Properties to stop notifications from all Properties in a - single interaction. | -
| queryallactions | -Identifies the queryallactions operation on a Thing to get the status of - all Actions in a single interaction. | -
| subscribeallevents | -Identifies the subscribeallevents operation on Events to subscribe - to notifications from all Events in a single interaction. | -
| unsubscribeallevents | -Identifies the unsubscribeallevents operation on Events to unsubscribe - from notifications from all Events in a single interaction. | -
item
+ predecessor-version
+ controlledBy
+ Form+ A form can be viewed as a statement of "To perform an operation type operation on + form context, make a request method request to submission target" where the optional form fields may further describe the required request. In Thing + Descriptions, the form context is the surrounding Object, such as Properties, Actions, and + Events or the Thing itself for meta-interactions. +
+| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
href |
+ Target IRI of a link or submission target of a form. | +mandatory | +
+ anyURI
+ |
+
contentType |
+
+ Assign a content type based on a media type (e.g., text/plain) and potential parameters
+ (e.g., charset=utf-8) for the media type [RFC2046].
+ |
+ with default | +
+ string
+ |
+
contentCoding |
+ + Content coding values indicate an encoding transformation that has been or can be applied to a + representation. Content codings are primarily used to allow a representation to be compressed or + otherwise usefully transformed without losing the identity of its underlying media type and without + loss of information. Examples of content coding include "gzip", "deflate", etc. . + | +optional | +
+ string
+ |
+
security |
+
+ Set of security definition names, chosen from those defined in securityDefinitions.
+ These must all be satisfied for access to resources.
+ |
+ optional | +
+ string or
+ Array of
+ 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. The values associated with a form SHOULD be chosen from those defined in an
+ OAuth2SecurityScheme active on that form.
+ |
+ optional | +
+ string or
+ Array of
+ string
+ |
+
response |
+ + This optional term can be used if, e.g., the output communication metadata differ from input + metadata (e.g., output contentType differ from the input contentType). The response name contains + metadata that is only valid for the primary response messages. + | +optional | +
+ ExpectedResponse
+ |
+
additionalResponses |
+ + This optional term can be used if additional expected responses are possible, e.g. for error + reporting. Each additional response needs to be distinguished from others in some way (for example, + by specifying a protocol-specific error code), and may also have its own data schema. + | +optional | +
+ Array of AdditionalExpectedResponse
+ |
+
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 such as long polling
+ (longpoll), WebSub [websub] (websub), Server-Sent Events (sse) [html] (also known as EventSource). Please note that there is no restriction on the subprotocol
+ selection and other mechanisms can also be announced by this subprotocol term.
+ |
+ optional | +
+ string
+ (e.g., longpoll, websub, or sse)
+ |
+
op |
+ + Indicates the semantic intention of performing the operation(s) 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 for which and allows the client to select the correct form for the operation required. op can be + assigned one or more interaction verb(s) each representing a semantic intention of an operation. + | +with default | +
+ string or
+ Array of
+ string (one
+ of readproperty, writeproperty, observeproperty,
+ unobserveproperty, invokeaction, queryaction,
+ cancelaction, subscribeevent, unsubscribeevent,
+ readallproperties, writeallproperties,
+ readmultipleproperties, writemultipleproperties,
+ observeallproperties, unobserveallproperties,
+ subscribeallevents, unsubscribeallevents, or queryallactions)
+ |
+
+ Possible values for the contentCoding property can be found, e.g., in the
+
+ IANA HTTP content coding registry.
+
+ The list of possible operation types of a form is fixed. As of this version of the specification, it only + includes the well-known types necessary to implement the WoT interaction model described in [wot-architecture11]. Future versions of the standard may extend this list but + operations types MUST be restricted to the values in the table below. +
-- A Thing Description of a WoT producer may have multiple forms entries with, e.g., different - protocol and/or content types declarations that a Consumer could possibly support. In that case - the Consumer may choose any form entry that works (e.g., the protocol and content type is supported) for them. - When one form is chosen, it is expected that the Consumer will continue to use it as long as possible - for every new interaction with the WoT producer. -
+| Operation Type | +Description | +
|---|---|
| readproperty | +Identifies the read operation on Property Affordances to retrieve the corresponding data. | +
| writeproperty | +Identifies the write operation on Property Affordances to update the corresponding data. | +
| observeproperty | ++ Identifies the observe operation on Property Affordances to be notified with the new data when the + Property is updated. + | +
| unobserveproperty | ++ Identifies the unobserve operation on Property Affordances to stop the corresponding + notifications. + | +
| invokeaction | +Identifies the invoke operation on Action Affordances to perform the corresponding action. | +
| queryaction | ++ Identifies the querying operation on Action Affordances to get the status of the corresponding + action. + | +
| cancelaction | ++ Identifies the cancel operation on Action Affordances to cancel the ongoing corresponding action. + | +
| subscribeevent | ++ Identifies the subscribe operation on Event Affordances to be notified by the Thing when the event + occurs. + | +
| unsubscribeevent | ++ Identifies the unsubscribe operation on Event Affordances to stop the corresponding notifications. + | +
| readallproperties | ++ Identifies the readallproperties operation on a Thing to retrieve the data of all Properties in a + single interaction. + | +
| writeallproperties | ++ Identifies the writeallproperties operation on a Thing to update the data of all writable + Properties in a single interaction. + | +
| readmultipleproperties | ++ Identifies the readmultipleproperties operation on a Thing to retrieve the data of selected + Properties in a single interaction. + | +
| writemultipleproperties | ++ Identifies the writemultipleproperties operation on a Thing to update the data of selected + writable Properties in a single interaction. + | +
| observeallproperties | ++ Identifies the observeallproperties operation on Properties to be notified with new data when any + Property is updated. + | +
| unobserveallproperties | ++ Identifies the unobserveallproperties operation on Properties to stop notifications from all + Properties in a single interaction. + | +
| queryallactions | ++ Identifies the queryallactions operation on a Thing to get the status of all Actions in a single + interaction. + | +
| subscribeallevents | ++ Identifies the subscribeallevents operation on Events to subscribe to notifications from all + Events in a single interaction. + | +
| unsubscribeallevents | ++ Identifies the unsubscribeallevents operation on Events to unsubscribe from notifications from all + Events in a single interaction. + | +
+ A Thing Description of a WoT producer may have multiple forms entries with, e.g., different + protocol and/or content types declarations that a Consumer could possibly support. In that case the + Consumer may choose any form entry that works (e.g., the protocol and content type is supported) for them. + When one form is chosen, it is expected that the Consumer will continue to use it as long as + possible for every new interaction with the WoT producer. +
-
- Protocols that can be used with TDs follow request-response or eventing mechanisms.
- The Data Schema of an affordance generally correlates with the op keywords used in forms.
- The table below informatively summarizes the available data schema related terms with the op keywords.
-
| Operation Type | -Consumer to Thing DataSchema Correlation | -Thing to Consumer DataSchema Correlation | -
|---|---|---|
| readproperty | -No correlation. | -All fields in the Property Affordance without "writeOnly":true. |
-
| writeproperty | -All fields in the Property Affordance without "readOnly":true. |
- No correlation. additionalResponses can be used in the form level. |
-
| observeproperty | -No correlation. | -All fields in the Property Affordance without "writeOnly":true. |
-
| unobserveproperty | -No correlation. | -No correlation. | -
| invokeaction | -Value of the input key. |
- Value of the output key. |
-
| queryaction | -No correlation. | -No correlation. additionalResponses can be used in the form level. |
-
| cancelaction | -No correlation. | -No correlation. additionalResponses can be used in the form level. |
-
| subscribeevent | -Value of the subscription key with all fields without "readOnly":true |
- Value of the subscription key with all fields without "writeOnly":true |
-
| unsubscribeevent | -Value of the subscription key with all fields without "readOnly":true |
- Value of the subscription key with all fields without "writeOnly":true |
-
- Writing to a property does not necessarily mean that a new value will be sent to the Consumer observing the property. - It depends on the protocol and implementation. -
-
- Further specification of how to map operations to data schemas, as well as mapping meta operations such as readallproperties
- can be found in the respective protocol specification of the [[WOT-BINDING-TEMPLATES]].
-
+ Protocols that can be used with TDs follow request-response or eventing mechanisms. The Data Schema of
+ an affordance generally correlates with the op keywords used in forms. The
+ table below informatively summarizes the available data schema related terms with the
+ op keywords.
+
The optional response name-value pair can
- be used to provide metadata for the expected response
- message.
- With the core vocabulary, it only includes
- content type information, but TD Context Extensions could
- be applied. If no
- response name-value pair is provided, it
- MUST be assumed
- that the content type of the response is equal to the
- content type assigned to the Form instance. Note
- that contentType within an
- ExpectedResponse
- Class does not
- have a Default Value. For instance, if
- the value of the content type of the form is
- application/xml the assumed value of the
- content type of the response will be also
- application/xml.
- In some cases additional responses might be possible.
- One example of this is error responses but in some cases
- there might also be additional successful responses.
- In this case, the response name-value pair
- is still used for the primary response but
- additionalResponses may also be provided,
- whose value is an array of AdditionalExpectedResponse
- objects.
- Each additional response must be distinguished in some way from the primary
- response, either by contentType or by
- protocol-specific settings such as error code header values.
- Each additional response may also have a data schema
- which can differ from the normal output data schema for the
- interaction.
-
In some use cases, input and output data might be
- represented in a different form, for instance an Action
- that accepts JSON, but returns an image. In such a case,
- the optional response name-value pair can
- describe the content type of the expected response.
- If the content type of
- the expected response differs from the content type of
- the form, the Form instance MUST include a name-value
- pair with the name response.
- For instance, an ActionAffordance could only
- accept application/json for its input data,
- while it will respond with an image/jpeg
- content type for its output data. In that case the
- content types differ and the response
- name-value pair has to be used to provide response
- content type (image/jpeg) information to the
- Consumer.
- Similar considerations apply to additional responses,
- although in this case the contentType is optional
- if it is the same as the input content Type (e.g. JSON).
- If the content type of
- an additional expected response differs from the content type of
- the form, the Form instance MUST include an entry in the array
- associated with the name additionalResponses
- that includes a value for the name contentType.
- If the data schema of
- an additional expected response differs from the output data schema of
- the interaction, the Form instance MUST include an entry in the array
- associated with the name additionalResponses that
- includes a value for the name schema.
-
- The different cases on the variation of request and response are explained above. - The tables at summarize these cases in a concise manner. -
+| Operation Type | +Consumer to Thing DataSchema Correlation | +Thing to Consumer DataSchema Correlation | +
|---|---|---|
| readproperty | +No correlation. | +All fields in the Property Affordance without "writeOnly":true. |
+
| writeproperty | +All fields in the Property Affordance without "readOnly":true. |
+ No correlation. additionalResponses can be used in the form level. |
+
| observeproperty | +No correlation. | +All fields in the Property Affordance without "writeOnly":true. |
+
| unobserveproperty | +No correlation. | +No correlation. | +
| invokeaction | +Value of the input key. |
+ Value of the output key. |
+
| queryaction | +No correlation. | +No correlation. additionalResponses can be used in the form level. |
+
| cancelaction | +No correlation. | +No correlation. additionalResponses can be used in the form level. |
+
| subscribeevent | +
+ Value of the subscription key with all fields without "readOnly":true
+ |
+
+ Value of the subscription key with all fields without "writeOnly":true
+ |
+
| unsubscribeevent | +
+ Value of the subscription key with all fields without "readOnly":true
+ |
+
+ Value of the subscription key with all fields without "writeOnly":true
+ |
+
+ Writing to a property does not necessarily mean that a new value will be sent to the Consumer observing + the property. It depends on the protocol and implementation. +
+
+ Further specification of how to map operations to data schemas, as well as mapping meta operations such
+ as readallproperties
+ can be found in the respective protocol specification of the [[WOT-BINDING-TEMPLATES]].
+
+ The optional response name-value pair can be used to provide metadata for the expected
+ response message. With the core vocabulary, it only includes content type information, but TD Context
+ Extensions could be applied.
+ If no response name-value pair is provided, it MUST be assumed that the content type of
+ the response is equal to the content type assigned to the Form instance.
+ Note that contentType within an
+ ExpectedResponse
+ Class does not have a
+ Default Value. For instance,
+ if the value of the content type of the form is application/xml the assumed value of the
+ content type of the response will be also application/xml.
+
+ In some cases additional responses might be possible. One example of this is error responses but in some
+ cases there might also be additional successful responses. In this case, the
+ response name-value pair is still used for the primary response but
+ additionalResponses may also be provided, whose value is an array of
+ AdditionalExpectedResponse objects. Each additional response must be distinguished in some
+ way from the primary response, either by contentType or by protocol-specific settings such
+ as error code header values. Each additional response may also have a data schema which can differ from
+ the normal output data schema for the interaction.
+
+ In some use cases, input and output data might be represented in a different form, for instance an
+ Action that accepts JSON, but returns an image. In such a case, the optional
+ response name-value pair can describe the content type of the expected response.
+ If the content type of the expected response differs from the content type of the form, the
+ Form instance MUST include a name-value pair with
+ the name response.
+ For instance, an ActionAffordance could only accept application/json for its
+ input data, while it will respond with an image/jpeg content type for its output data. In
+ that case the content types differ and the response
+ name-value pair has to be used to provide response content type (image/jpeg) information to
+ the
+ Consumer.
+
+ Similar considerations apply to additional responses, although in this case the
+ contentType is optional if it is the same as the input content Type (e.g. JSON).
+ If the content type of an additional expected response differs from the content type of the form, the
+ Form instance MUST include an entry in the array
+ associated with the name additionalResponses that includes a value for the name
+ contentType.
+ If the data schema of an additional expected response differs from the output data schema of the
+ interaction, the Form instance MUST include an
+ entry in the array associated with the name additionalResponses that includes a value for
+ the name schema.
+
+ The different cases on the variation of request and response are explained above. The tables at + summarize these cases in a concise manner. +
+ExpectedResponseCommunication metadata describing the expected response message for the primary response.
+| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
contentType |
+
+ Assign a content type based on a media type (e.g., text/plain) and potential parameters
+ (e.g., charset=utf-8) for the media type [RFC2046].
+ |
+ mandatory | +
+ string
+ |
+
AdditionalExpectedResponseCommunication metadata describing the expected response message for additional responses.
+| Vocabulary term | +Description | +Assignment | +Type | +
|---|---|---|---|
success |
+ Signals if an additional response should not be considered an error. | +with default | +
+ boolean
+ |
+
contentType |
+
+ Assign a content type based on a media type (e.g., text/plain) and potential parameters
+ (e.g., charset=utf-8) for the media type [RFC2046].
+ |
+ with default | +
+ string
+ |
+
schema |
+
+ Used to define the output data schema for an additional response if it differs from the default
+ output data schema. Rather than a DataSchema object, the name of a previous definition
+ given in a schemaDefinitions map must be used.
+ |
+ optional | +
+ string
+ |
+
ExpectedResponseCommunication metadata describing the expected - response message for the primary response.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
contentType | Assign a content type based on a media type
- (e.g., text/plain) and potential
- parameters (e.g., charset=utf-8) for
- the media type [RFC2046]. | mandatory | string |
AdditionalExpectedResponseCommunication metadata describing the expected - response message for additional responses.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
success | Signals if an additional response should not be considered an error. | with default | boolean |
contentType | Assign a content type based on a media type
- (e.g., text/plain) and potential
- parameters (e.g., charset=utf-8) for
- the media type [RFC2046]. | with default | string |
schema | Used to define the output data schema
- for an additional response if it differs from the default
- output data schema.
- Rather than a DataSchema object, the
- name of a previous definition given in a
- schemaDefinitions map must be used. | optional | string |
Each Binding Template Subspecification is an independent document that has a separate list of authors - and publication date. This section explains the binding mechanism by giving requirements per respective binding category and links to the respective subspecification. These can be found in sections [[[#protocol-bindings]]], [[[#payload-bindings]]] and - [[[#platform-bindings]]]. + and publication date. This section explains the binding mechanism by giving requirements per respective + binding category and links to the respective subspecification. These can be found in sections + [[[#protocol-bindings]]], [[[#payload-bindings]]] and [[[#platform-bindings]]].
- As an extension of [[[#payload-bindings-dataschema]]], this section collects examples of different payloads
- and their corresponding DataSchema.
- These are from well-known IoT Platforms and Standards and aim to illustrate the various ways a payload can
- look like and how one can describe it with a Data Schema.
-
+ As an extension of [[[#payload-bindings-dataschema]]], this section collects examples of different payloads and
+ their corresponding DataSchema. These are from well-known IoT Platforms and Standards and aim to
+ illustrate the various ways a payload can look like and how one can describe it with a Data Schema.
+
- SenML [[RFC8428]] might use the following construct: -
+SenML [[RFC8428]] might use the following construct:
-
- ++ |
+
- A Batch Collection according to OCF[[OCF]] may be structured like this: -
+A Batch Collection according to OCF[[OCF]] may be structured like this:
-
- ++ |
+
- And an IPSO Smart Object on LWM2M [[LWM2M]] might look like the following: -
+And an IPSO Smart Object on LWM2M [[LWM2M]] might look like the following:
-
- ++ |
+
- This document summarizes the discussions on simplifying the JSON-LD 1.0-based WoT Thing Description and proposes a simplified TD serialization based on JSON-LD 1.1. - The proposal lists the features of the TD core model and gives use cases per feature. - The proposed "Simplified TD" serialization is given in the form of extensive examples. - Specification text will be added when merging this proposal into the WoT Thing Description Editors' Draft. - For convenience, examples of the JSON-LD 1.0 serialization and the alternative JSON Web Thing Description (a.k.a. JSON-TD) are given for comparison. - This document concludes with a list of differences in the proposals. + This document summarizes the discussions on simplifying the JSON-LD 1.0-based + WoT Thing Description and proposes a + simplified TD serialization based on JSON-LD 1.1. + The proposal lists the features of the TD core model and gives use cases per feature. The proposed "Simplified + TD" serialization is given in the form of extensive examples. Specification text will be added when merging this + proposal into the WoT Thing Description + Editors' Draft. For convenience, examples of the + JSON-LD 1.0 serialization and the alternative + JSON Web Thing Description (a.k.a. JSON-TD) + are given for comparison. This document concludes with a list of differences in the proposals.
+
- The WoT Thing Description based on JSON-LD 1.0 has been criticized for several limitations including complexity and the JSON-LD 1.0 array structures and keywords even when no semantic annotations are used. - This lead to an alternative draft, the JSON Web Thing Description, with a pure JSON serialization, which however, would fragment W3C WoT due to incompatible models behind the serializations. - To remedy the situation, this document proposes a simplified TD serialization based on JSON-LD 1.1, - thereby combining both requirements: - machine-understandability through a formal Linked Data model from the original WoT Thing Description and improved usability from the JSON Web Thing Description. - Being able to conduct these simplifications first required a full understanding of the requirements, which have been analyzed by the Working Group since its chartering. - This technical deep-dive completed around TPAC 2017 (Burlingame), where the Working Group announced to change the goal toward simplification from there onward. + The WoT Thing Description based on + JSON-LD 1.0 has been criticized for several limitations including complexity and the JSON-LD 1.0 array + structures and keywords even when no semantic annotations are used. This lead to an alternative draft, the + JSON Web Thing Description, with a pure + JSON serialization, which however, would fragment W3C WoT due to incompatible models behind the serializations. + To remedy the situation, this document proposes a simplified TD serialization based on + JSON-LD 1.1, thereby combining both requirements: + machine-understandability through a formal Linked Data model from the original WoT Thing Description and + improved usability from the JSON Web Thing Description. Being able to conduct these simplifications first + required a full understanding of the requirements, which have been analyzed by the Working Group since its + chartering. This technical deep-dive completed around TPAC 2017 (Burlingame), where the Working Group announced + to change the goal toward simplification from there onward.
- Many discussions are rooted on the question whether a certain feature should be included or not. - This section lists the features currently included in the TD core model and backs them by use cases. + Many discussions are rooted on the question whether a certain feature should be included or not. This section + lists the features currently included in the + TD core model and backs + them by use cases.
- To represent a contract between applications with programming APIs and IoT devices with network APIs,
- the communication with Things must be modeled with a formal interaction model.
- This describes not only
- Based on the Web Thing Model - and results of the COMPOSE project - the WoT Interest Group explored a threefold of Interactions, which was - adopted by the WoT Working Group after 2 years of stability: + Based on the Web Thing Model and results of the + COMPOSE project + the WoT Interest Group explored a threefold of Interactions, which was adopted by the WoT Working Group after + 2 years of stability:
- Properties expose internal state of a Thing that can be directly accessed (get) and optionally manipulated (set). - Things can also choose to make Properties observable by pushing the new state (not an event) after a change; - this must follow eventual consistency (also see CAP Theorem). + Properties expose internal state of a Thing that can be directly accessed (get) and optionally manipulated + (set). Things can also choose to make Properties observable by pushing the new state (not an event) after a + change; this must follow eventual consistency (also see + CAP Theorem).
- Actions offer functions of the Thing. - These functions may manipulate the interal state of a Thing in a way that is not possible through setting Properties. - Examples are changing internal state that is not exposed as Property, changing multiple Properties, changing Properties over time or with a process that shall not be disclosed. - Actions may also be pure functions, that is, they do not use any internal state at all, e.g., for processing input data and returning the result directly. + Actions offer functions of the Thing. These functions may manipulate the interal state of a Thing in a way + that is not possible through setting Properties. Examples are changing internal state that is not exposed as + Property, changing multiple Properties, changing Properties over time or with a process that shall not be + disclosed. Actions may also be pure functions, that is, they do not use any internal state at all, e.g., for + processing input data and returning the result directly.
- The 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 occured events. + The 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 occured events.
- Interactions exchange data using representation formats (e.g., JSON),
- which are identified by Media Types (e.g., application/json.
- Usually, applications use generic serialization formts without
- application-specific definitions (cf. JSON). Thus, TDs also needs to
- include metadata about the data model used, so-called schemas.
+ Interactions exchange data using representation formats (e.g., JSON), which are identified by Media Types
+ (e.g., application/json. Usually, applications use generic serialization formts without
+ application-specific definitions (cf. JSON). Thus, TDs also needs to include metadata about the data model
+ used, so-called schemas.
- JSON reflects the state of the art of data interchange formats. - It is not focused on how data is represented by a specific system - (e.g., in 16 bits), but only on the fundamentals of the information. + JSON reflects the state of the art of data interchange formats. It is not focused on how data is represented + by a specific system (e.g., in 16 bits), but only on the fundamentals of the information.
- CBOR is a concise binary representation that is related to JSON. - It can express all JSON structures, but also has additional - features such as a binary type to improve over base64-encoded blobs. + CBOR is a concise binary representation that is related to JSON. It can express all JSON structures, but + also has additional features such as a binary type to improve over base64-encoded blobs.
- A popular validation schema for JSON data is JSON Schema. - It defines a vocabulary and a syntax to specify a schema for data validation - at the syntactic level. -
-- The Web of Things aims at semantic interoperability for Things. For this, - + A popular validation schema for JSON data is JSON Schema. It defines a + vocabulary and a syntax to specify a schema for data validation at the syntactic level.
+The Web of Things aims at semantic interoperability for Things. For this,
- Directly using the JSON Schema syntax within the TD breaks paradigms. - Two different implementations would be needed to conduct validation. - At least JSON Schema could be reused. - However, semantic queries and resoning could not work on data structures, - that is, make sense of the data in relation to the Thing and its - context. + Directly using the JSON Schema syntax within the TD breaks paradigms. Two different implementations would be + needed to conduct validation. At least JSON Schema could be reused. However, semantic queries and resoning + could not work on data structures, that is, make sense of the data in relation to the Thing and its context.
- The TD has a top-level security field to carry security
- metadata such as the required authorization mechanism, authorization
- server, required root certificates, etc.
+ The TD has a top-level security field to carry security metadata such as the required
+ authorization mechanism, authorization server, required root certificates, etc.
- The TD Interactions have a form field to carry protocol-specific metadata such as method used and header fields required.
- The concept of machine understandable forms matches the requirement of RAML, Swagger, OpenAPI for RESTful Web APIs.
+ The TD Interactions have a form field to carry protocol-specific metadata such as method used and
+ header fields required. The concept of machine understandable forms matches the requirement of RAML, Swagger,
+ OpenAPI for RESTful Web APIs.
- The W3C Web of Things was charted to counter the fragmentation in the IoT. - Creating yet another standard does not help here, as existing standards with strong domain-specific knowledge have shown to hold out. - Thus, W3C WoT was charted to describe and complement existing IoT platforms and standards. - For this, a TD must be able to describe how a client can communicate successfully with a server. + The W3C Web of Things was charted to counter the fragmentation in the IoT. Creating yet another standard does + not help here, as existing standards with strong domain-specific knowledge have shown to hold out. Thus, W3C + WoT was charted to describe and complement existing IoT platforms and standards. For this, a TD must be able + to describe how a client can communicate successfully with a server.
- Up to date, not even so-called RESTful Web services managed to follow a single guidline when designing their API. - Requests always have to be tailored for each service (cf. usage of Swagger/OpenAPI). + Up to date, not even so-called RESTful Web services managed to follow a single guidline when designing their + API. Requests always have to be tailored for each service (cf. usage of Swagger/OpenAPI).
- To reflect this situation in the TD, where a situation similar to RESTful APIs is expected for Things, - a TD is able to include so called form descriptions, which go beyond Web linking: - The not only describe the relation to a target resource and attributes of the target resource, - but also descriptions how to interact with that resource, that is, - how a client has to formulate requests (e.g., header fields or payloads). + To reflect this situation in the TD, where a situation similar to RESTful APIs is expected for Things, a TD + is able to include so called form descriptions, which go beyond Web linking: The not only describe the + relation to a target resource and attributes of the target resource, but also descriptions how to interact + with that resource, that is, how a client has to formulate requests (e.g., header fields or payloads).
- So far, there is no single IoT protocol to rule them all. - The only convergence visible is a trend toward Internet protocols defined by the IETF and other bodies such as OASIS. - Yet still every IoT platform and standard tends to introduce small variations, thereby creating protocol dialects. + So far, there is no single IoT protocol to rule them all. The only convergence visible is a trend toward + Internet protocols defined by the IETF and other bodies such as OASIS. Yet still every IoT platform and + standard tends to introduce small variations, thereby creating protocol dialects.
- To allow for convergence of currently deployed IoT protocols and to be future proof for new protocols that might emerge as de facto standards, - the TD has protocol bindings as explicit extension point. + To allow for convergence of currently deployed IoT protocols and to be future proof for new protocols that + might emerge as de facto standards, the TD has protocol bindings as explicit extension point.
- The WoT Binding Templates document serves as catalog - to pick the right communication metadata for well-known IoT protocols. - The templates provide vocabulary to describe the required protocol stack configuration (e.g., specific header fields) and security mechanisms in the TD. + The WoT Binding Templates document serves as + catalog to pick the right communication metadata for well-known IoT protocols. The templates provide + vocabulary to describe the required protocol stack configuration (e.g., specific header fields) and security + mechanisms in the TD.
Binding Templates are mainly expected for dialects of the Web protocols HTTP/1.1, HTTP/2, and CoAP, - standardized sub-protocols for WebSockets, - and widely deployed IoT protocols such as AMQP or MQTT profiles (e.g., Amazon IoT). + standardized sub-protocols for WebSockets, and widely deployed IoT protocols such as AMQP or MQTT profiles + (e.g., Amazon IoT).
- The Web of Things is centered on things. During runtime, data and metadata are primarily exchanged among machines for machines. - Furthermore, WoT content is produced by a large number of machines. - Thus, machine assistance is also needed for consuming the data and bulding viable business cases. + The Web of Things is centered on things. During runtime, data and metadata are primarily exchanged among + machines for machines. Furthermore, WoT content is produced by a large number of machines. Thus, machine + assistance is also needed for consuming the data and bulding viable business cases.
- Semantic annotations are based on JSON-LD, which gives meaning to JSON field names and values
- by defining the terms used in the @context and linking them to Link Data.
- TDs can be annotated as follows:
+ Semantic annotations are based on JSON-LD, which gives meaning to JSON field names and values by defining
+ the terms used in the @context and linking them to Link Data. TDs can be annotated as follows:
@type array- The W3C has no knowledge in the concrete application domains of Web of Things. - Thus, the W3C is not standardizing any domain-specific vocabulary. + The W3C has no knowledge in the concrete application domains of Web of Things. Thus, the W3C is not + standardizing any domain-specific vocabulary.
- Still, domain-specific vocabularies are of utmost importance for semantic interoperability. - Thus, the TD has an explicit extension point that comes for free when using JSON-LD and Linked Data. + Still, domain-specific vocabularies are of utmost importance for semantic interoperability. Thus, the TD has + an explicit extension point that comes for free when using JSON-LD and Linked Data.
- The TD now has a top-level link field to carry links to other Web resources.
-
The TD now has a top-level link field to carry links to other Web resources.
-
+- This requirement lead to the choice of a JSON-based format for the TD. -
+This requirement lead to the choice of a JSON-based format for the TD.
- The Web of Things is centered on things. During runtime, data and metadata are primarily exchanged among machines for machines. - Furthermore, WoT content is produced by a large number of machines. - Thus, machine assistance is also needed for consuming the data and bulding viable business cases. + The Web of Things is centered on things. During runtime, data and metadata are primarily exchanged among + machines for machines. Furthermore, WoT content is produced by a large number of machines. Thus, machine + assistance is also needed for consuming the data and bulding viable business cases.
- Thus, TDs must not only be machine-readible, but machine-understandable. - Moreover, the TD metadata can help to make optimized runtime data - (i.e., no metadata included in the live data exchanged) - also machine-understandable. + Thus, TDs must not only be machine-readible, but machine-understandable. Moreover, the TD metadata can help to + make optimized runtime data (i.e., no metadata included in the live data exchanged) also + machine-understandable. +
+- This requirement lead to the choice of JSON-LD, an existing W3C standard - for machine-understandable JSON documents based on Linked Data vocabularies. + This requirement lead to the choice of JSON-LD, an existing W3C standard for machine-understandable JSON + documents based on Linked Data vocabularies.
- Applications consuming TDs should be able to easily introspect the - capabilites, possible interactions, and other metadata of the corresponding Things. + Applications consuming TDs should be able to easily introspect the capabilites, possible interactions, and + other metadata of the corresponding Things.
- In particular the WoT Scripting API benefits from - an alternative structure of the TD, such as separated entry points for Properties, Actions, and Events. + In particular the WoT Scripting API benefits from an + alternative structure of the TD, such as separated entry points for Properties, Actions, and Events.
- Implementations for the PlugFest showed that basically every developer is counting on defaults,
- that is, certain elements can be omitted as their meaning is known implicitly or even irrelevant.
- Examples are omitting the security metadata for test Things that use no-security,
- omitting the writable flag for read-only Properties,
- or omitting inputSchema/outputSchema for Actions that do not take arguments and/or return nothing.
+ Implementations for the PlugFest showed that basically every developer is counting on defaults, that is,
+ certain elements can be omitted as their meaning is known implicitly or even irrelevant. Examples are omitting
+ the security metadata for test Things that use no-security, omitting the
+ writable flag for read-only Properties, or omitting inputSchema/outputSchema
+ for Actions that do not take arguments and/or return nothing.
- Treating the JSON-LD TD strictly as Linked Data document, a collection of triples, would not allow for such defaults, and hence convenience. - Linked Data underly the open-world assumption. - That means, when a TD is omitting statements (e.g., writable flag), then the consumer cannot make any assumptions about its actual value. + Treating the JSON-LD TD strictly as Linked Data document, a collection of triples, would not allow for such + defaults, and hence convenience. Linked Data underly the + open-world assumption. That means, when a TD + is omitting statements (e.g., writable flag), then the consumer cannot make any assumptions about its actual + value.
- Based on the knowledge that it is a TD, the consumer could, however, apply a set rules, which infer the defaults. - This leads to the preprocessing introduced in the next section. + Based on the knowledge that it is a TD, the consumer could, however, apply a set rules, which infer the + defaults. This leads to the preprocessing introduced in the next section.
- Be conservative in what you do, be liberal in what you accept from others. - Applying Postel's law + Be conservative in what you do, be liberal in what you accept from others. Applying + Postel's law fosters interoperability and should also be used in the Web of Things.
-- This requirement also leads to a preprocessing step that can fill in - defaults and correct minor issues. -
+This requirement also leads to a preprocessing step that can fill in defaults and correct minor issues.
- The Simpified TD proposal aims at solving the requirements given in the previous section. -
+The Simpified TD proposal aims at solving the requirements given in the previous section.
The main change and enabler for a simplified TD is introducing a preprocessing step.
- The main change and enabler for a simplified TD is introducing a - preprocessing step. -
-- Due to the open-world assumption, - some preprocessing of the TD is required. - The rules to fill in defaults could be applied in the following way: -
- Normalizing the TD in a preprocessing step also helps for robustness. - Thus, this is a favorable solution. + Due to the open-world assumption, some + preprocessing of the TD is required. The rules to fill in defaults could be applied in the following way:
+Normalizing the TD in a preprocessing step also helps for robustness. Thus, this is a favorable solution.
- JSON-LD 1.1 Frameing can be used to define and apply the preprocessing steps. + JSON-LD 1.1 Frameing can be used to define + and apply the preprocessing steps.
- NOTE: Even with JSON-LD 1.1 available, there are still open issues.
- For instance, the object key becomes the @id of the Property node defined in the object value:
- To derive sensible triples, the object key would need to be declared either as "blank node" by prefixing with _:,
- or the container mechanism must be able generate relative @ids to avoid conflicts when an object key appears twice at different levels.
+ NOTE: Even with JSON-LD 1.1 available, there are still open issues. For instance, the object key
+ becomes the @id of the Property node defined in the object value: To derive sensible triples, the
+ object key would need to be declared either as "blank node" by prefixing with _:, or the
+ container mechanism must be able generate relative @ids to avoid conflicts when an object key
+ appears twice at different levels.
- When TDs are not a valid JSON-LD document due to necessary preprocessing or simply an omitted @context,
- they need their own media type registered with IANA.
-
- We propose application/td+json.
+ When TDs are not a valid JSON-LD document due to necessary preprocessing or simply an omitted
+ @context, they need their own media type registered with IANA.
We propose application/td+json.
link
- The Working Draft for the Prague 2018 PlugFest already adopted a top-level link field,
- so that a TD can express relations to other Things or other Web resources.
+ The Working Draft for the Prague 2018 PlugFest already adopted a top-level link field, so that
+ a TD can express relations to other Things or other Web resources.
- Note that because the TD is JSON-LD, such relations were always possible and are actually always expressed for all top-level fields (it is Linked Data).
- Having the term link makes it explicit that the elements included there are actual Web Links to fetchable Web resources,
- opposed to Linked Data URIs ("IRIs") that are often only an identifier without an actual Web resource.
+ Note that because the TD is JSON-LD, such relations were always possible and are actually always expressed
+ for all top-level fields (it is Linked Data). Having the term link makes it explicit that the
+ elements included there are actual Web Links to fetchable Web resources, opposed to Linked Data URIs
+ ("IRIs") that are often only an identifier without an actual Web resource.
description
- The term description is very useful and shall become part of the TD core vocabulary for both Thing and Interactions.
+ The term description is very useful and shall become part of the TD core vocabulary for both
+ Thing and Interactions.
name
- The term name would not be the identifier for Interactions anymore.
- Following JSON-LD 1.1, the object key would become @id, which would serve as handle to select Interactions, e.g., for the Scripting API.
+ The term name would not be the identifier for Interactions anymore. Following JSON-LD 1.1, the
+ object key would become @id, which would serve as handle to select Interactions, e.g., for the
+ Scripting API.
- With that, name becomes either obsolete or rather could be used as optional, human-readible label.
- As a result, for Things, name becomes a mandatory label.
- For Interactions, the new, optional term label is used.
+ With that, name becomes either obsolete or rather could be used as optional, human-readible
+ label. As a result, for Things, name becomes a mandatory label. For Interactions, the new,
+ optional term label is used.
id
- On the top level, id will become important for security and identity management.
- It identifies the instance of Thing and also serves as the @base for all other @id definitions (e.g., of Interactions).
- Only this fully enables the object notation of Interactions (opposed to the previous array notation).
- The top-level id must be mandatory and internally maps to the @id of the Thing.
- Therefore, a Thing id must be a URI (which includes URNs).
+ On the top level, id will become important for security and identity management. It identifies
+ the instance of Thing and also serves as the @base for all other @id definitions
+ (e.g., of Interactions). Only this fully enables the object notation of Interactions (opposed to the
+ previous array notation). The top-level id must be mandatory and internally maps to the
+ @id of the Thing. Therefore, a Thing id must be a URI (which includes URNs).
- For Interactions, @id would be the handle for scripts and it would
- enable references to and between Interactions, e.g., for
- cross-Property constraints or for expressing relations between an
- action and one or more Properties. Note that this would result
- automatically from the object structure listing Interactions
- because of JSON-LD 1.1 (Node Identifier Indexing).
+ For Interactions, @id would be the handle for scripts and it would enable references to and
+ between Interactions, e.g., for cross-Property constraints or for expressing relations between an action and
+ one or more Properties. Note that this would result automatically from the object structure listing
+ Interactions because of JSON-LD 1.1 (Node Identifier Indexing).
- To enable alignment with other technologies such as JSON Schema, the Simplified TD needs a few small changes to the TD core model. - It has to be evaluated if these changes are actually breaking changes (i.e., a JSON-LD 1.0 TD would create different triples than a Simplified TD). + To enable alignment with other technologies such as JSON Schema, the Simplified TD needs a few small changes + to the TD core model. It has to be evaluated if these changes are actually breaking changes (i.e., a JSON-LD + 1.0 TD would create different triples than a Simplified TD).
- +
- Using the term properties also for the object field names of complex Properties (i.e., "type": "object") aligns the TD with JSON Schema syntax.
- This results in recursive Properties, where
-
DataSchema RDF-typeforms field are Interaction Properties.forms field.
- properties also for the object field names of complex Properties (i.e.,
+ "type": "object") aligns the TD with JSON Schema syntax. This results in recursive Properties,
+ where
+ DataSchema RDF-typeforms field are Interaction Properties.forms field.
+
- When no @context is given, the Simplified TD context
- is assumed based on the media type (file location needs update for adoption).
- The current TD context also needs an additional definition of @base set to the Thing's @id,
- so that the object representation of Interactions produces correct @ids for the Interactions.
+ When no @context is given, the
+ Simplified TD context
+ is assumed based on the media type (file location needs update for adoption). The current TD context also
+ needs an additional definition of @base set to the Thing's @id, so that the object
+ representation of Interactions produces correct @ids for the Interactions.
@@ -635,20 +662,24 @@- +Simplified TD by Example
} }
- When @context is given, the Simplified TD context
- is applied last to ensure that the terms of the TD core vocabulary are valid and not shadowed by other contexts.
+ When @context is given, the
+ Simplified TD context
+ is applied last to ensure that the terms of the TD core vocabulary are valid and not shadowed by other
+ contexts.
- The first example reflects the minimal option.
- It contains no semantic annotations, nor human-readible decorators such as name or description.
+ The first example reflects the minimal option. It contains no semantic annotations, nor human-readible
+ decorators such as name or description.
{
"name": "Lamp",
@@ -748,10 +779,10 @@ Minimal Simplified TD
}
{
"@context": { "iot": "https://iot.schema.org/" },
@@ -871,27 +902,26 @@ Annotated Simplified TD (with semantics)
}
This section summerizes the status of the JSON-LD 1.0-based Thing Description (until Prague 2018 WD).
- + +This section summerizes the status of the JSON-LD 1.0-based Thing Description (until Prague 2018 WD).
+ +
- This example reflects the minimal option.
- It contains no semantic annotations, nor human-readible decorators such as name or description.
-
+ This example reflects the minimal option. It contains no semantic annotations, nor human-readible decorators
+ such as name or description.
+
+
{
"@context": "https://w3c.github.io/wot/w3c-wot-td-context.jsonld",
"name": "Lamp",
@@ -980,12 +1010,12 @@ Minimal JSON-LD
"mediaType": "application/ld+json"
}]
}
-
-
-