This document describes a formal model and a common representation for a Web of Things (WoT) Thing Description. A Thing Description describes the metadata and interfaces of Things, where a Thing is an abstraction of a physical or virtual entity that provides interactions to and participates in the Web of Things. Thing Descriptions provide a set of interactions based on a small vocabulary that makes it possible both to integrate diverse devices and to allow diverse applications to interoperate. Thing Descriptions, by default, are encoded in a JSON format that also allows JSON-LD processing. The latter provides a powerful foundation to represent knowledge about Things in a machine-understandable way. A Thing Description instance can be hosted by the Thing itself or hosted externally when a Thing has resource restrictions (e.g., limited memory space) or when a Web of Things-compatible legacy device is retrofitted with a Thing Description.

Implementers need to be aware that this specification is considered unstable. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation phase should subscribe to the repository and take part in the discussions.

Introduction

The Thing Description (TD) is a central building block in the W3C Web of Things (WoT) and can be considered as the entry point of a Thing (much like the index.html of a Web site). The TD consists of semantic metadata for the Thing itself, an interaction model based on WoT's Properties, Actions, and Events paradigm, a semantic schema to make data models machine-understandable, and features for Web Linking to express relations among Things.

Properties can be used for sensing and controlling parameters, such as getting the current value or setting an operation state. Actions model invocation of physical (and hence time-consuming) processes, but can also be used to abstract RPC-like calls of existing platforms. Events are used for the push model of communication where notifications, discrete events, or streams of values are sent asynchronously to the receiver. In general, the TD provides metadata for different communication bindings identified by URI schemes [[!IANA-URI-SCHEMES]] (e.g., "http", "coap", etc.), content types based on media types (e.g., "application/json", "application/xml", "application/cbor", "application/exi" etc.) [[!IANA-MEDIA-TYPES]], and security mechanisms (for authentication, authorization, confidentiality, etc.). Serialization of TD instances is based on JSON and includes at least the TD core vocabulary as JSON names as defined in this specification document.

Example 1 shows a simple TD instance in such a JSON serializiation and depicts WoT's Properties, Actions, and Events paradigm by describing a lamp Thing with the name MyLampThing.

Based on this content, we know there exists one Property interaction resource with the name status. In addition, information is provided to indicate that this Property is accessible via (the secure form of) the HTTP protocol with a GET method at the URI https://mylamp.example.com/status (announced within the forms structure by the href name), and will return a string status value. The use of the GET method is not stated explicitly, but is one of the default assumptions defined by this document and explained in [[!WOT-PROTOCOL-BINDING]].

In a similar manner, an Action is specified to toggle the switch status using the POST method applied to the https://mylamp.example.com/toggle resource, where POST is again a default assumption for invoking Actions.

The Event pattern enables a mechanism for asynchronous messages to be sent by a Thing. Here, a subscription to be notified upon a possible overheating event of the lamp can be obtained by using the HTTP with its long polling sub-protocol at https://mylamp.example.com/oh.

This example also specifies the basic security scheme, requiring a username and password for access. Note that a security scheme is first given a name in a securityDefinition and then activated by specifying that name in a security section. In combination with the use of the HTTP protocol this example demonstrates the use of HTTP Basic Authentication. Specification of at least one security scheme at the top level is mandatory, and gives the default access requirements for every resource. However, security schemes can also be specified per-form, with configurations given at the form level overriding configurations given at the Thing level, allowing for the specification of fine-grained access control. It is also possible to use a special nosec security scheme to indicate that no access control mechanisms are used. Additional examples will be provided later.

The TD in Example 1 reflects some additional defined default assumptions that are not explicitly described. For example, the content type of the exchange format of the interactions is assumed to be JSON (=contentType) and the Property status resource is not readOnly as well as not observable. Specifically, the TD specification defines vocabulary terms (e.g., readOnly, writeOnly, observable, contentType) that have default values. If these vocabulary terms are not explicitly used in a Thing Description instance, the Thing Description processor follows default assumptions for interpretation as defined in this specification. The Full tab in Example 1 shows the identical information of the simple form of the Thing Description instance, but includes these mentioned implicit vocabulary terms with its default values.

The Thing Description offers the possibility to add context knowledge from different namespaces. This mechanism can be used to add additional semantics, such as specific domain knowledge, to the content of the Thing Description instance, and to specify some configurations and behavior of the underlying communication protocols declared in the forms field. Example 2 extends the TD sample from Example 1 and uses the @context known from JSON-LD to introduce the http context. This context is used to specify explicitly the http methods for the property and action within the forms.

The TD can be also processed as an RDF-based model. In that case, the Thing Description instance needs to be transformed into valid JSON-LD first which will be specified in this document.

Terminology

Generic WoT terminology is defined in [[!WOT-ARCHITECTURE]]: Thing, Thing Description (in short TD), Web of Things (in short WoT), WoT Interface etc.

Namespaces

The namespace for the W3C Thing Description vocabulary as defined in this document is http://www.w3.org/ns/td.

Using content negotiation, this namespace serves either the TD ontology file (Turtle) or the TD context file (JSON-LD).

Conformance

As well as all sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [[!RFC2119]].

A Thing Description instance complies with this specification if it follows the normative statements in Section and Section regarding Thing Description serialization.

A JSON Schema [[?JSON-SCHEMA-VALIDATION]] is provided in Annex to validate Thing Description instances based on JSON serialization.

In the future some information about RDF validation will be provided.

Information Model

This section introduces the Thing Description information model. The Thing Description Information model serves as the conceptual basis for the serialization and processing of Thing Description described in later sections in this document.

Overview

The W3C Thing Description provides a set of vocabulary for describing physical and virtual Things. In general, the Thing Description vocabulary set is grouped in three modules:

An overview of this vocabulary with its class context and class relation is given by the following three figures. Vocabulary terms identify members within the TD information model. Both the terms shown on the left side of " : " (i.e. colon) in the boxes representing classes and the terms labelling the arrows constitute the vocabulary terms of Thing Description information model. Please note that the figures reflect the vocabulary terms and structure as they would be used in a Thing Description instance (see Section ).

The following diagrams are automatically generated from the ontology files. The layout will be improved in one of the next TD updates.

TD core model figure
TD core model (Click SVG file)
TD data schema model figure
TD data schema model (Click SVG file)
TD security model figure
TD security model (Click SVG file)

A detailed description of the vocabulary of the TD core model, TD data schema model and TD security model is given in the following sub-sections.

All vocabulary restrictions noted in tables in Section , , and MUST be followed, including mandatory items.

The section explains how to serialize these vocabulary terms to a Thing Description instance using a JSON-based representation. It also defines default values for some mandatory vocabulary and explains the options how they can be serialized.

Core Vocabulary Definition

Note that for now securityDefinitions are mandatory at the top level of a Thing since there needs to be at least one definition available for use in the top-level mandatory security block. However, a future extension may allow in-place anonymous definitions within security blocks in which case this requirement may be relaxed.

Thing

Describes a physical and/or virtual Thing (may represent one or more physical and/or virtual Things) in the Web of Things context. When a concrete Thing is defined in a Thing Description, it is called an "thing resource".

Vocabulary termDescriptionMandatoryType
@contextKnown from JSON-LD, @context is used to define short-hand names called terms that are used throughout a TD document.

The first item in the JSON-LD context array MUST be the namespace "http://www.w3.org/ns/td", optionally followed by one or more local namespaces. Each optional namespace specifed for a Thing context MUST be bound to an unique prefix.
yesarray of JSON-LD contexts
@typeKnown from JSON-LD, @type is used to state that a thing resource is an instance of a class. One or more classes can be specified.

Each string in the value array represents a class.
noarray of string
idunique identifier of the Thing (URI, e.g. custom URN).yesanyURI
nameName of the Thing.yesstring
descriptionProvides additional (human-readable) information based on a default language.nostring
descriptionsCan be used to support (human-readable) information in different languages.noMultiLanguage
versionProvides version information.noVersionInfo
createdProvides information when the TD instance was created.nostring
lastModifiedProvides information when the TD instance was last modified.nostring
supportProvides information about the TD maintainer (e.g., author, link or telephone number to get support, etc).nostring
baseDefine the base URI that is valid for all defined local interaction resources. All other URIs in the TD must then be resolved using the algorithm defined in [[!RFC3986]].noanyURI
propertiesAll Property-based interaction patterns of the Thing.noProperty
actionsAll Action-based interaction patterns of the Thing.noAction
eventsAll Event-based interaction patterns of the Thing.noEvent
formsIndicates one or more endpoints at which operation(s) on this resource are accessible. In this version of TD, all operations that can be described at the Thing level are concerning how to interact with the Thing's Property interaction resources collectively at once.noarray of Form
securitySet of security definition names, chosen from those defined in securityDefinitions. These must all be satisfied for access to resources at or below the current level, if not overridden at a lower level.yesarray of string
securityDefinitionsSet of named security configurations (definitions only). Not actually applied unless names are used in a security section.yesSecurityScheme

Similar to Pattern, Action and Event classes, all of which are subclasses of InteractionPattern, the definition of Thing class also contains the forms term. When a forms term member is present in a Thing instance, the value(s) of op in the forms MUST be one of readallproperties, writeallproperties, readmultipleproperties or writemultipleproperties. (See an example.)

For readallproperties operation's output, readmultipleproperties operation's output, writeallproperties operation's input and writemultipleproperties operation's input, payloads are assigned an object type schema with its properties equal to the Thing's property resources. For readmultipleproperties operation's input, payloads are assigned a string array type schema with its items each equal to one of the names of The Thing's property resources.

InteractionPattern

Three interaction patterns are defined as subclasses: Property, Action and Event. When a concrete Property, Action or Event is defined in a Thing Description, it is called an "interaction resource". Interactions between Things can be as simple as one Thing accessing another Thing's data to get or (in the case the data is also writable) change the representation of data such as metadata, status or mode. A Thing may also be interested in getting asynchronously notified of future changes in another Thing, or may want to initiate a process served in another Thing that may take some time to complete and monitor the progress. Interactions between Things may involve exchanges of data between them. This data can be either given as input by the client Thing, returned as output by the server Thing or both.

Vocabulary termDescriptionMandatoryType
@typeKnown from JSON-LD, @type is used to state that an interaction resource is an instance of a class. One or more classes can be specified.

Each string in the value array represents a class.
noarray of string
titleProvides a human-readable title (e.g., display a text for UI representation) of the interaction pattern based on a default language.nostring
titlesProvides multi-language human-readable titles (e.g., display a text for UI representation in different languages) of the interaction pattern.noMultiLanguage
descriptionProvides additional (human-readable) information based on a default language.nostring
descriptionsCan be used to support (human-readable) information in different languages.noMultiLanguage
formsIndicates one or more endpoints at which operation(s) on this resource are accessible.yesarray of Form
uriVariablesDefine URI template variables as collection based on DataSchema declarations.noDataSchema

The class InteractionPattern has the following subclasses:

Each instance of a Property, Action, and Event class MUST have an identifier that is unique within the context of a Thing Description document.

Property

Properties expose internal state of a Thing that can be directly retrieved (get) and optionally modified (set). In addition, 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).

Vocabulary termDescriptionMandatoryType
observableIndicates whether a remote servient can subscribe to ("observe") the Property, to receive change notifications or periodic updates (true/false).yesboolean

Property class is a subclass of the class InteractionPattern. When a forms term member is present in a Property instance, the value(s) of op in the forms MUST be one of readproperty, writeproperty or observeproperty.

Property instances are also instances of the class DataSchema. Therefore, it can contain the type, unit, readOnly and writeOnly members, among others.

Action

Actions offer functions of the Thing. These functions may manipulate the internal state of a Thing in a way that is not possible through setting Properties. Examples are changing internal state that is not exposed as a Property, changing multiple Properties, changing Properties over time or with a process that should not be disclosed. Actions may also be pure functions, that is, they may not use any internal state at all, and may simply process input data and return a result that directly depends only on the input given.

Vocabulary termDescriptionMandatoryType
inputUsed to define the input data schema of the action.noDataSchema
outputUsed to define the output data schema of the action.noDataSchema
safeSignals 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.yesboolean
idempotentIndicates 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.yesboolean

Action class is a subclass of the class InteractionPattern. When a forms term member is present in an Action instance, the value(s) of op in the forms MUST be invokeaction.

Event

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 events that have occurred.

Vocabulary termDescriptionMandatoryType
subscriptionDefines data that needs to be passed upon subscription, e.g., filters or message format for setting up Webhooks.noDataSchema
dataDefines the data schema of the Event instance messages pushed by the Thing.noDataSchema
cancellationDefines any data that needs to be passed to cancel a subscription, e.g., a specific message to remove a Webhook.noDataSchema

Event class is a subclass of the class InteractionPattern. When a forms term member is present in an Event instance, the value(s) of op in the forms MUST be one of subscribeevent or unsubscribeevent.

Form

Communication metadata indicating where a service can be accessed by a client application. An interaction might have more than one form.

Vocabulary termDescriptionMandatoryType
hrefURI of the endpoint where an interaction pattern is provided.yesanyURI
contentTypeAssign a content type based on a media type [[!IANA-MEDIA-TYPES]] (e.g., 'application/json) and (optional) parameters (e.g., 'charset=utf-8').yesstring
responseThis optional term can be used if, e.g., the output communication metadata differ from input metdata (e.g., output contentType differ from the input contentType). The response name contains metadata that is only valid for the reponse messages.noExpectedResponse
opIndicates 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.noarray of string Each entry representing an interaction verb (one of readproperty, writeproperty, observeproperty, unobserveproperty, invokeaction, subscribeevent, unsubscribeevent, readallproperties, writeallproperties, readmultipleproperties, or writemultipleproperties)
subprotocolIndicates 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 (e.g., Long Polling, Webhooks).nostring (one of longpoll, or webhook)
securitySet of security definition names, chosen from those defined in securityDefinitions. These must all be satisfied for access to resources at or below the current level, if not overridden at a lower level.noarray of string
scopesSet 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.noarray of string

Link

A Web link, as specified by IETF RFC 8288 (https://tools.ietf.org/html/rfc8288).

Vocabulary termDescriptionMandatoryType
hrefURI of the endpoint where an interaction pattern is provided.yesanyURI
typeProvides a hint indicating what the media type [[!IANA-MEDIA-TYPES]] of the result of dereferencing the link should be.nostring
relIndicates the relation to an other Thing.nostring
anchorBy default, the context of a link is the URL of the representation it is associated with, and is serialised as a URI. When present, the anchor parameter overrides this with another URI, such as a fragment of this resource, or a third resource (i.e., when the anchor value is an absolute URI).noanyURI

VersionInfo

Carries version information about the TD instance. If required, additional version information such as firmware and hardware version (term definitions outside of the TD namespace) can be extended here.

Vocabulary termDescriptionMandatoryType
instanceProvides a version identicator of this TD instance.yesstring

ExpectedResponse

Communication metadata for response messages (e.g., contentType of the response).

Vocabulary termDescriptionMandatoryType
contentTypeAssign a content type based on a media type [[!IANA-MEDIA-TYPES]] (e.g., 'application/json) and (optional) parameters (e.g., 'charset=utf-8').nostring

MultiLanguage

Container to provide human-readable text in different languages using language tags described in [[!BCP47]]. Each used language tags code MUST be decleared as vocabulary term member of this container (e.g., en, de, ja, zh-Hans, zh-Hant).

Note that in protocols such as HTTP that have an ability to negotiate content based on languages, those terms (e.g. description and title) intended for carrying texts in a default language SHOULD be used instead of this container when the texts are served as a result such negotiation.

Data Schema Vocabulary Definition

<<<<<<< HEAD

The data schema definition reflecting a very common subset of the terms defined in JSON Schema [[?JSON-SCHEMA-VALIDATION]]. It is noted that data schema definitions within Thing Description instances are not limited to this defined subset and MAY use additional terms you find in JSON Schema. It that case it is recommended to use context association for that additional terms as described in , otherwise these terms are semantically ignored (also see ).

DataSchema

=======

DataSchema

Vocabulary termDescriptionMandatoryType
@contextKnown from JSON-LD, @context is used to define short-hand names called terms that are used in a DataSchema.

The first item in the JSON-LD context array MUST be the namespace "https://www.w3.org/ns/json-schema", optionally followed by one or more local namespaces. Each optional namespace MUST be bound to an unique prefix.
yesarray of JSON-LD contexts
@typeKnown from JSON-LD, @type is used to state that values described by the DataSchema are instances of a class. One or more classes can be specified.

Each string in the value array represents a class.
noarray of string
titleProvides a human-readable title (e.g., display a text for UI representation) of the interaction pattern based on a default language.nostring
>>>>>>> 517f69ed411291c87291e0564387a3b60ffc4ac3
Vocabulary termDescriptionMandatoryType
@contextKnown from JSON-LD, @context is used to define short-hand names called terms that are used in a DataSchema.

The first item in the JSON-LD context array MUST be the namespace "https://www.w3.org/ns/json-schema", optionally followed by one or more local namespaces. Each optional namespace specified for a DataSchema context MUST be bound to an unique prefix.
yesarray of JSON-LD contexts
@typeKnown from JSON-LD, @type is used to state that values described by the DataSchema are instances of a class. One or more classes can be specified.

Each string in the value array represents a class.
noarray of string
titleProvides a human-readable title (e.g., display a text for UI representation) of the interaction pattern based on a default language.nostring
titlesProvides multi-language human-readable titles (e.g., display a text for UI representation in different languages) of the interaction pattern.noMultiLanguage
descriptionProvides additional (human-readable) information based on a default language.nostring
descriptionsCan be used to support (human-readable) information in different languages.noMultiLanguage
typeAssignment of JSON-based data types compatible with JSON Schema (one of boolean, integer, number, string, object, array, or null).nostring (one of object, array, string, number, integer, boolean, or null)
constProvides a constant value.noany type
unitProvides unit information that is used, e.g., in international science, engineering, and business.nostring
oneOfUsed to ensure that the data is valid against one of the specified schemas in the array.noarray of DataSchema
enumRestricted set of values provided as an array.noarray of any type
readOnlyBoolean value that indicates whether a property interaction / value is read only (=true) or not (=false).yesboolean
writeOnlyBoolean value that indicates whether a property interaction / value is write only (=true) or not (=false).yesboolean

The class DataSchema has the following subclasses:

ArraySchema

A JSON array specification ("type": "array").

Vocabulary termDescriptionMandatoryType
itemsUsed to define the characteristics of an array.noDataSchema
minItemsDefines the minimum number of items that have to be in the array.nounsignedInt
maxItemsDefines the maximum number of items that have to be in the array.nounsignedInt

BooleanSchema

A JSON boolean value specification ("type": "boolean").

NumberSchema

A JSON number value specification ("type": "number").

Vocabulary termDescriptionMandatoryType
minimumSpecifies a minimum numeric value. Only applicable for associated number or integer types.nodouble
maximumSpecifies a maximum numeric value. Only applicable for associated number or integer types.nodouble

IntegerSchema

A JSON integer value specification, that is, numbers without a fractional part ("type": "integer").

Vocabulary termDescriptionMandatoryType
minimumSpecifies a minimum numeric value. Only applicable for associated number or integer types.nointeger
maximumSpecifies a maximum numeric value. Only applicable for associated number or integer types.nointeger

ObjectSchema

A JSON object specification ("type": "object").

Vocabulary termDescriptionMandatoryType
propertiesData schema nested definitions.noDataSchema
requiredDefines which members of the object type are mandatory.noarray of string

StringSchema

A JSON string value specification ("type": "string").

NullSchema

A JSON null value specification ("type": "null"). If the type of null then it has only one acceptable value, namely null. E.g., it can be used as part of oneOf declaration, where it is used to indicate, that a data schema can also be null.

Security Vocabulary Definition

For the core TD vocabulary only well-established security mechanisms are supported, such as those built into protocols supported by WoT or already in wide use with those protocols. The current set of HTTP security schemes is partly based on OpenAPI 3.0.1 (see also [[?OPENAPI]]). Note however that while the HTTP security schemes, vocabulary and syntax given in this specification share many similarities with OpenAPI they are not fully compatible. Also, since OpenAPI primarily targets web services built around HTTP, it does not cover the full set of use cases required for the IoT. Security schemes appropriate for IoT-centered protocols such as CoAP [[?RFC7252]] and MQTT [[?MQTT]] are therefore also included.

The vocabulary extension mechanism of the WoT Thing Description allows for additional security schemes if needed. However, for more information about what additional security schemes or modifications are under discussion for the core WoT vocabulary (and to file issues if you have a request) please visit the WoT Security TF repository.

SecurityScheme

Vocabulary termDescriptionMandatoryType
@contextKnown from JSON-LD, @context is used to define short-hand names called terms that are used in a SecurityScheme.

The first item in the JSON-LD context array MUST be the namespace "https://www.w3.org/ns/wot-security", optionally followed by one or more local namespaces. Each optional namespace specified for a SecurityScheme context MUST be bound to an unique prefix.
yesarray of JSON-LD contexts
@typeKnown from JSON-LD, @type is used to state that a security mechanism configured by the SecurityScheme is an instance of a class. One or more classes can be specified.

Each string in the value array represents a class.
noarray of string
schemeIdentification of security mechanism being configured.yesstring (one of nosec, basic, cert, digest, bearer, pop, psk, public, oauth2, or apikey)
descriptionProvides additional (human-readable) information based on a default language.nostring
proxyURI of the proxy server this security configuration provides access to. If not given, the corresponding security configuration is for the endpoint.noanyURI

The class SecurityScheme has the following subclasses:

NoSecurityScheme

A security configuration corresponding to ("scheme": "nosec"), indicating there is no authentication or other mechanism required to access the resource.

BasicSecurityScheme

Basic authentication security configuration ("scheme": "basic"), using an unencrypted username and password. This scheme should be used with some other security mechanism providing confidentiality, for example, TLS.

Vocabulary termDescriptionMandatoryType
inSpecifies the location of security authentication information (one of header, query, body, or cookie).yesstring
nameName for query, header, or cookie parameters.nostring

DigestSecurityScheme

Digest authentication security configuration ("scheme": "digest"). This scheme is similar to basic authentication but with added features to avoid man-in-the-middle attacks.

Vocabulary termDescriptionMandatoryType
qopQuality of protection (one of auth or auth-int).yesstring
inSpecifies the location of security authentication information (one of header, query, body, or cookie).yesstring
nameName for query, header, or cookie parameters.nostring

APIKeySecurityScheme

API key authentication security configuration ("scheme": "apikey"). This is for the case where the access token is opaque and is not using a standard token format.

Vocabulary termDescriptionMandatoryType
inSpecifies the location of security authentication information (one of header, query, body, or cookie).yesstring
nameName for query, header, or cookie parameters.nostring

BearerSecurityScheme

Bearer token authentication security configuration ("scheme": "bearer"). This scheme is intended for situations where bearer tokens are used independently of OAuth2. If the oauth2 scheme is specified it is not generally necessary to specify this scheme as well as it is implied.

Vocabulary termDescriptionMandatoryType
authorizationURI of the authorization server.noanyURI
algEncoding, encryption, or digest algorithm (one of MD5, ES256, or ES512-256).yesstring
formatSpecifies format of security authentication information (one of jwt, jwe, or jws).yesstring
inSpecifies the location of security authentication information (one of header, query, body, or cookie).yesstring
nameName for query, header, or cookie parameters.nostring

CertSecurityScheme

Certificate-base asymmetric key security configuration ("scheme": "cert").

Vocabulary termDescriptionMandatoryType
identityPre-shared key identity.nostring

PSKSecurityScheme

Pre-shared key authentication security configuration ("scheme": "psk").

Vocabulary termDescriptionMandatoryType
identityPre-shared key identity.nostring

PublicSecurityScheme

Raw public key asymmetric key security configuration ("scheme": "public").

Vocabulary termDescriptionMandatoryType
identityPre-shared key identity.nostring

PoPSecurityScheme

Proof-of-possession token authentication security configuration ("scheme": "pop").

Vocabulary termDescriptionMandatoryType
authorizationURI of the authorization server.noanyURI
algEncoding, encryption, or digest algorithm (one of MD5, ES256, or ES512-256).yesstring
formatSpecifies format of security authentication information (one of jwt, jwe, or jws).yesstring
inSpecifies the location of security authentication information (one of header, query, body, or cookie).yesstring
nameName for query, header, or cookie parameters.nostring

OAuth2SecurityScheme

OAuth2 authentication security configuration ("scheme": "oauth2"). For the implicit flow the authorization and scopes are required. For the password and client flows both token and scopes are required. For the code flow authorization, token, and scopes are required.

Vocabulary termDescriptionMandatoryType
authorizationURI of the authorization server.noanyURI
tokenURI of the token server.noanyURI
refreshURI of the refresh server.noanyURI
scopesSet 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.noarray of string
flowAuthorization flow (one of implicit, password, client, or code).yesstring

Thing Description Serialization

Thing Description instances are modeled and structured based on Section . This section defines a TD serialization based on JSON [[!RFC8259]].

Basic Representation Format Assumptions

In order to enable this convergence, all vocabulary terms defined in Section will have a JSON name representation.

The data types of the vocabulary as defined in Section will be transformed to JSON-based types. The following rules are used for vocabulary terms based on some simple type definitions:

For JSON-based Thing Description serialization, if values are not given for certain mandatory fields, default values MUST be assumed. Default values for these fields are given in the following table:

Vocabulary term Default value Context
@context "http://www.w3.org/ns/td" Thing
@context "https://www.w3.org/ns/json-schema" DataSchema
@context "https://www.w3.org/ns/wot-security" SecurityScheme
readOnly false
writeOnly false
observable false
contentType application/json
safe false
idempotent false
in header BasicSecurityScheme
DigestSecurityScheme
BearerSecurityScheme
PoPSecurityScheme
in query APIKeySecurityScheme
qop auth DigestSecurityScheme
alg ES256 BearerSecurityScheme
PoPSecurityScheme
format jwt BearerSecurityScheme
PoPSecurityScheme
flow implicit OAuth2SecurityScheme

A Thing Description instance serialization MAY omit one ore more vocabulary terms that are mandatory () AND have default values based on the table above. In this specification, this form is referred to as Simple Thing Description representation. The processing of such Simple Thing Description representation will be explained in . When a Thing Description instance carry all mandatory vocabulary terms we will call this representation as Full Thing Description.

In addition, Thing Description instances MAY contain additional JSON-LD keywords such as @context and @type. With these the Thing Description can be easily extended. You can find additional details in the Section . In the case of @type usage in the Thing Description instance, the @type MUST be serialized as JSON String or as JSON array of strings when multiple values are assigned to @type.

All vocabulary terms in Section associated with more complex class-based types are defined separately for structured JSON type transformation in the following subsections.

Thing as a whole

The root object of a Thing Description instance MAY include the @context name known from JSON-LD with the value URI of the Thing description context file http://www.w3.org/ns/td.

{  
    "@context": "http://www.w3.org/ns/td",
    ...
}

http://www.w3.org/ns/td uses content negotiation to return the context file. Thus, it must be fetched with an Accept header set to application/ld+json.

When a single Thing Description instance involves several contexts, additional namespaces with prefixes MUST be appended to the @context array structure. This option proves relevant if one wants to extend the existing Thing Description context without modifying it. For instance:

{
    "@context": ["http://www.w3.org/ns/td",
                {"iot": "http://example.org/iot"}],
    ...
}

Each mandatory and optional member name as defined in the class Thing MUST be serialized as a JSON name in the root object of the Thing Description instance.

The type of the members properties, actions, events, version, and securityDefinitions MUST be a JSON object.

The type of the members forms, links, scopes, and security MUST be a JSON array.

A TD snippet based on the defined members of the class Thing without the optional member @context is given below:

{
    "id": "urn:dev:wot:com:example:servient:myThing",
    "name": "MyThing",
    "description": "Human readable information.",
    "descriptions": {...},
    "support": "mailto:support@example.com",
    "securityDefinitions": {...},
    "security": [...],
    "base": "https://servient.example.com/",
    "lastModified" : "2018-11-15T09:12:43.124Z",
    "created" : "2018-11-14T19:10:23.824Z",
    "version" : {...},
    "properties": {...},
    "actions": {...},
    "events": {...},
    "links": [...],
    "forms": [...]
}

Alternatively, the same example can be written instead to explicitly include the (semantic) names used by JSON-LD, namely @context and @type:

{
    "@context": "http://www.w3.org/ns/td",
    "@type": "Thing",
    "id": "urn:dev:wot:com:example:servient:myThing",
    "name": "MyThing",
    "description": "Human readable information.",
    "descriptions": {...},
    "support": "mailto:support@example.com",
    "securityDefinitions": {...},
    "security": [...],
    "base": "https://servient.example.com/",
    "lastModified" : "2018-11-15T09:12:43.124Z",
    "created" : "2018-11-14T19:10:23.824Z",
    "version" : {...},
    "properties": {...},
    "actions": {...},
    "events": {...},
    "links": [...],
    "forms": [...]
}

In that case the content can be directly associated as Thing Description based on the namespace http://www.w3.org/ns/td provided in the @context. The "@type": "Thing" associates an instantiations of the Thing class as defined in Section .

properties

Properties (and sub-properties) offered by a Thing MUST be collected in the JSON-object based properties member with (unique) Property names as JSON names.

Each mandatory and optional vocabulary term as defined in the class Property, as well as its two superclasses InteractionPattern and DataSchema, MUST be serialized as a JSON name within a Property object. This means that at the level of an interaction property instance, the vocabulary terms of InteractionPattern and DataSchema can be presented at the same time.

The type of the member forms MUST be serialized as a JSON array.

A TD snippet based on the defined members is given below:

actions

Actions offered by a Thing MUST be collected in the JSON-object based actions member with (unique) Action names as JSON names.

Each optional vocabulary term as defined in the class Action and its superclass InteractionPattern MUST be serialized as a JSON name within an Action object.

The type of the members input and output MUST be serialized as a JSON object.

The names input and output rely on the the class DataSchema and will follow the serialization introduction provided in .

The type of the member forms MUST be serialized as a JSON array.

A TD snippet based on the defined members is given below:

events

Events offered by a Thing MUST be collected in the JSON-object based events member with (unique) Event names as JSON names.

Each optional vocabulary term as defined in the class Event, as well as its two superclasses InteractionPattern and DataSchema, MUST be serialized as a JSON name within an Event object.

The type of the members subscription, data, and cancellation MUST be serialized as a JSON object.

The JSON names of subscription, data, and cancellation rely on the the class DataSchema and will follow the serialization introduction provided in .

The type of the member forms MUST be serialized as a JSON array.

A TD snippet based on the defined members is given below:

forms

Each mandatory and optional vocabulary term as defined in the class Form, MUST be serialized as a JSON name.

If required, the type of the member response MUST be serialized as a JSON object.

If required, forms MAY be supplemented with protocol-specific vocabulary terms identified with a prefix. See also .

A TD snippet based on the defined members is given below:

{
  "@context": ["http://www.w3.org/ns/td",
    {"http": "http://www.w3.org/2011/http#"}],
  ...
  "securityDefinitions": {
      "basic_sc": {"scheme":"basic", "in":"header"}
  },
    ...
    "forms": [{
        "href" : "http://mytemp.example.com:5683/temp",
        "contentType": "application/json",
        "http:methodName": "POST",
        "op": ["writeproperty"],
        "security": ["basic_sc"]
    }]
    ...
}

href may also carry an URI that contains dynamic variables such as p and d in http://192.168.1.25/left?p=2&d=1. In that case the URI can be defined as template as defined in [[!RFC6570]]: http://192.168.1.25/left{?p,d}

In such a case these variables in the URI MUST be collected in the JSON-object based uriVariables member with the associated (unique) variables names as JSON names.

Each defined JSON name of the uriVariables collection MUST rely on the the class DataSchema.

A TD snippet using URI template and uriVariables is given below:

        "@context": ["http://www.w3.org/ns/td",
            {"http": "http://www.w3.org/2011/http#"},
            {"eg": "http://www.example.org/iot"}],
        ...
        "actions": {
            "LeftDown": {
              "uriVariables": {
                "p" : { "type": "integer", "minimum": 0, "maximum": 16, "@type": "eg:SomeKindOfAngle" },
                "d" : { "type": "integer", "minimum": 0, "maximum": 1, "@type": "eg:Direction" }
                }
              },
              "forms": [{
                "http:method": "GET",
                "href" : "http://192.168.1.25/left{?p,d}"
              }]
            }
        ...
    

The contentType is used to assign a media types [[!IANA-MEDIA-TYPES]] and MAY contain one or more parameters as attribute-value pair separated by a ; character. Example:

    ...
    "contentType" : "text/plain; charset=utf-8"
    ...

In some use cases, the form metadata of the interaction pattern must be distinguished between request and response based messages. E.g., an action 'takePhoto' defines an input to submit parameter settings of a camera (aperture priority, timer,..) using json as content type (="contentType":"application/json"). The output of this action is the photo taken, which is available in jpeg format, for example. In such cases, the response can be used to provide a response content type (e.g., "contentType":"image/jpeg").

If the response member is used in forms, it MUST contain the contentType as defined in class ExpectedResponse.

A form snippet with the response member is listed below based on the use case of the action 'takePhoto' described above:

    "@context": ["http://www.w3.org/ns/td",
        {"http": "http://www.w3.org/2011/http#"}],
    ...
    "forms": [
        {
          "href": "http://upsq1c.local:9191/api/frame/crop",
          "contentType": "application/json",
          "op": ["invokeaction"],
          "http:methodName": "POST",
          "response": {
            "contentType": "image/jpeg"
          }
        }
      ]
    ...

When forms is present at the top level, it can be used to describe meta interactions supported by a Thing instance. For example, operations "readallproperties" and "writeallproperties" are meta interactions by which clients can read and write all properties of the thing at once. In the example below, forms is used at the top level, and the clients can access end point (i.e. https://mylamp.example.com/allproperties) both to read or write all properties (i.e. "on", "brightness" and "timer" property) of the thing in a single interaction.

{
    "@context": ["http://www.w3.org/ns/td",
        {"http": "http://www.w3.org/2011/http#"}],
    "id": "urn:dev:wot:com:example:servient:lamp",
    ...
    "forms": [
        {
          "href": "https://mylamp.example.com/allproperties",
          "contentType": "application/json",
          "op": ["readallproperties"],
          "http:methodName": "GET"
        },
        {
          "href": "https://mylamp.example.com/allproperties",
          "contentType": "application/json",
          "op": ["writeallproperties"],
          "http:methodName": "PUT"
        }
    ],
    ...
    "properties": {
        "on": {
          "type": "boolean",
          "forms": [...]
        },
        "brightness": {
          "type": "number",
          "forms": [...]
        },
        "timer": {
          "type": "integer",
          "forms": [...]
        }
    },
    ...
}

securityDefinitions and security

Each mandatory and optional vocabulary term as defined in the class SecurityScheme, MUST be serialized as a JSON name.

The following TD snippet shows a simple security configuration specifying basic username/password authentication in the header. The value of in given is actually the default value of header. First, a named security configuration must be given in a securityDefinitions block. Second, that definition must be activated in a security block.

   ...
   "securityDefinitions": {
       "basic_sc": {
           "scheme": "basic",
           "in": "header"
       }
   },
   ...
   "security": ["basic_sc"]
   ...

Here is a more complex example: a TD snippet showing digest authentication on a proxy combined with bearer token authentication on an endpoint. Here the default value of in in the digest scheme, header, is implied.

    ...
    "securityDefinitions": {
        "basic_sc": {
           "scheme": "digest",
           "proxy": "https://portal.example.com/"
        },
        "bearer_sc": {
           "in":"header",
           "scheme": "bearer",
           "format": "jwt",
           "alg": "ES256",
           "authorization": "https://servient.example.com:8443/"
        }
    },
    ...
    "security": ["basic_sc","bearer_sc"],
    ...

Security configuration is mandatory. Every Thing MUST have at least one security scheme specified at the top level. Security schemes MAY also be specified at the form level. In this case, definitions at the form level override (completely replace) all definitions given at the top level.

The nosec security scheme is provided for the case that no security is needed. The minimal security configuration for a Thing is configuration of the nosec security scheme at the top level, as in the following example:

{
    "id": "urn:dev:wot:com:example:servient:myThing",
    "name": "MyThing",
    "description": "Human readable information.",
    "support": "https://servient.example.com/contact",
    "securityDefinitions": {"nosec_sc": {"scheme": "nosec"}},
    "security": ["nosec_sc"],
    "properties": {...},
    "actions": {...},
    "events": {...},
    "links": [...]
}

To give a more complex example, suppose we have a Thing where all interactions require basic authentication except for one interaction for which no authentication is required. In the following, the nosec scheme for the security configuration in the overheating event to indicate no authentication is required. For the status property and the toggle action, however, basic authentication is required as defined at the top level of the Thing.

{
    ...
    "securityDefinitions": {
        "nosec_sc": {"scheme": "nosec"},
        "basic_sc": {"scheme": "basic"}
    },
    "security": ["basic_sc"],
    ...
    "properties": {
        "status": {
            ...
            "forms": [{
                "href": "https://mylamp.example.com/status",
                "contentType": "application/json",
            }]
        }
    },
    "actions": {
        "toggle": {
            ...
            "forms": [{
                "href": "https://mylamp.example.com/toggle",
                "contentType": "application/json"
            }]
        }
    },
    "events": {
        "overheating": {
            ...
            "forms": [{
                "href": "https://mylamp.example.com/oh",
                "contentType": "application/json",
                "security": ["nosec_sc"] 
            }]
        }
    }
}

Security configurations can also can be specified for different forms within the same interaction. This may be required for devices that support multiple protocols, for example CoAP [[?RFC7252]] and HTTP, with support for different security mechanisms. This is also useful when alternative authentication mechanisms are allowed. Here is a TD snippet demonstrating three possible ways to access a resource: via HTTPS with basic authentication, via HTTPS via digest authentication, or via CoAPS with an API key. In other words, the use of multiple security configurations at the same level provides a way to combine security mechanisms an in "OR" fashion. In contrast, putting multiple security configurations in the same security member combines them in an "AND" fashion, since in that case they would all need to be satisfied to allow access to the resource. Note that a security declaration is still mandatory at the Thing level. Here we use a nosec scheme for symmetry but could also have used any one of the other ones as it will be overridden in each form.

    "securityDefinitions": {
        "nosec_sc": {"scheme": "nosec"},
        "basic_sc": {"scheme": "basic"},
        "digest_sc": {"scheme": "digest","qop":"auth","in":"header"},
        "apikey_sc": {"scheme": "apikey","in":"header"}
    },
    "security": ["nosec_sc"]
    ...
    "properties": {
        "status": {
            ...
            "forms": [
                {
                    "href": "https://mylamp.example.com/status",
                    "contentType": "application/json",
                    "security": ["basic_sc"]
                },
                {
                    "href": "https://mylamp.example.com/status",
                    "contentType": "application/json",
                    "security": ["digest_sc"]
                },
                {
                    "href": "coaps://mylamp.example.com:5683/status",
                    "contentType": "application/json",
                    "security": ["apikey_sc"]
                }
            ]
        }
    },
    ...

As another more complex example, OAuth2 makes use of scopes. These are identifiers that may appear in tokens and must match with corresponding identifiers in a resource to allow access to that resource. For example, in the following, the "status" property can be read by users using bearer tokens containing the scope "limited" but the "configure" action can only be used when the interaction is invoked with a token containing the "special" scope. Scopes are not identical to roles but are often associated with them; for example, perhaps only those in an administrative role can perform "special" interactions. Tokens can have more than one scope. In this example, an administrator would probably be issued tokens with both the "limited" and "special" scopes while ordinary users would only be issued tokens with the "limited" scope.

    ...
    "securityDefinitions": {
        "oauth2_sc": {
            "scheme": "oauth2",
            ...
            "scopes": ["limited","special"]
        }
    },
    "security": ["oauth2_sc"],
    "properties": {
        "status": {
            ...
            "forms": [
                {
                    "href": "https://scopes.example.com/status",
                    "contentType": "application/json",
                    "scopes": ["limited"]
                }
            ]
        }
    },
    "action": {
        "configure": {
            ...
            "forms": [
                {
                    "href": "https://scopes.example.com/configure",
                    "contentType": "application/json",
                    "scopes": ["special"]
                }
            ]
        }
    },
    ...

version

The mandatory vocabulary term as defined in the class VersionInfo, MUST be serialized as a JSON name.

The recommended version identification pattern value is to rely on the semantic versioning policy: [[?SemVer]]

A TD snippet based on the defined members is given below:

        ...
        "version": {"instance":"1.2.1"}
        ...
    

The version container MAY be used to provide additional application and/or device specific version information based on terms from non-TD namespaces.

A TD snippet based on such additional version metadata from a v context is given below:

        "@context": ["http://www.w3.org/ns/td",
                    {"v": "http://www.example.org/versioningTerms#"}],
        ...
        "version": {"instance":"1.2.1", "v:firmware": "0.9.1", "v:hardware": "1.0"}
        ...
    

Data Schema Representation

The data schema concept within the Thing Description is based on a subset of JSON schema terms. The data schema concept is applied to the properties interaction declaration, input and output within actions interaction declaration, subscription, data and cancellation within events interaction declaration, and uriVariables that can be used within the forms container.

Each mandatory and optional vocabulary term as defined in the class DataSchema, MUST be serialized as a JSON name.

The type of the members properties and items MUST be serialized as a JSON object.

The type of the member enum, required, and oneOf MUST be serialized as a JSON array.

A TD snippet based on the defined members is given below:

        ...
        "type": "object",
        "properties": {
            "status": {
                "title": "Status",
                "type": "string",
                "enum": ["On", "Off", "Error"]
            },
            "brightness": {
                "title": "Brightness value",
                "type": "number",
                "minimum": 0.0,
                "maximum": 100.0
            },
            "rgb": {
                "title": "RGB color value",
                "type": "array",
                "items" : {
                    "type" : "number",
                    "minimum": 0,
                    "maximum": 255
                },
                "minItems": 3,
                "maxItems": 3
            }
        },
        ...
        

The terms readOnly and writeOnly MAY be used to signalize which data members are exchanged for a read request (e.g., read an interaction property) and which one for a write process (e.g. write an interaction property).

An TD snippet with the usage of readOnly and writeOnly is given below:

    ...
        "properties": {
            "status": {
              "description": "Read or write On/Off status.",
              "type": "object",
              "properties": {
                "latestStatus": {
                  "type": "string",
                  "enum": ["On", "Off"],
                  "readOnly": true
                },
                "newStatusValue": {
                  "type": "string",
                  "enum": ["On", "Off"],
                  "writeOnly": true
                }
              },
              forms:[...]
            }
          }
    ...

If the interaction property status is read, the status data is returned using latestStatus in the payload. To manipulate the status of the interaction property, the new value must be provided by assigning newStatusValue in the payload.

As an additional feature, a Thing Description instance allows the usage of the term unit within data schema definitions. This can be used to associates some unit information to some data members. The unit values can be free selected, however, it is recommended to select units based on existing definitions by integrating the corresponding namespace context (e.g., from Smart Appliances REFerence (SAREF) ontology or Ontology of units of Measure (OM)).

    {
    "@context": ["http://www.w3.org/ns/td",
                {"om": "http://www.wurvoc.org/vocabularies/om-1.8/"}],
    ...
    "properties": {
        "latestValues": {
            "description": "Provides all current values of the weather station.",
            "type": "object",
            "properties": {
            "temperature": {
                "type": "number",
                "minimum" : -32.5,
                "maximum" : -55.2,
                "unit": "om:degree_Celsius"
            },
            "humidity": {
                "type": "number",
                "minimum" : 0,
                "maximum" : 100,
                "unit": "om:percent"
            }
            },
            forms:[...]
        }
    }
    ...

titles and descriptions

The vocabulary terms titles and descriptions enables human-readable text description in multi-languages using language tags described in [[!BCP47]]. Whenever the vocabulary terms titles and descriptions can be used, both MUST be serialized as JSON Object. The member names of the JSON Object MUST be the language tags as defined in [[!BCP47]] (e.g., "en", "de", "ja", "zh-Hans", "zh-Hant"). The value of each member MUST be serialized as JSON string.

A TD snippet using titles and descriptions in different levels is given below:

                    {
                        "name": "MyThing",
                        "descriptions": {
                            "en":"Human readable information.",
                            "de": "Menschenlesbare Informationen.",
                            "ja" : "人間が読むことができる情報",
                            "zh-Hans" : "人们可阅读的信息", 
                            "zh-Hant" : "人們可閱讀的資訊"
                        },
                        ...
                        "properties": {
                            "on": {
                                "titles": {
                                    "en": "On/Off",
                                    "de": "An/Aus",
                                    "ja": "オンオフ",
                                    "zh-Hans": "开关",
                                    "zh-Hant": "開關" },
                                "type": "boolean",
                                "forms": [...]
                            },
                            "status": {
                                "titles": {
                                    "en": "Status",
                                    "de": "Zustand",
                                    "ja": "状態",
                                    "zh-Hans": "状态",
                                    "zh-Hant": "狀態" },
                                "type": "object",
                                ...
                    }
                    

TD instances may also additional use title and description beside of titles and descriptions. If title and titles description and descriptions are defined at the same time at the JSON level, title and description MAY be seen as default text.

            {
                "name": "MyThing",
                "description": "Menschenlesbare Informationen.",
                "descriptions": {
                    "en":"Human readable information.",
                    "de": "Menschenlesbare Informationen.",
                    "ja" : "人間が読むことができる情報",
                    "zh-Hans" : "人们可阅读的信息", 
                    "zh-Hant" : "人們可閱讀的資訊"
                },
                ...
                "properties": {
                    "on": {
                        "title" : "An/Aus",
                        "titles": {
                            "en": "On/Off",
                            "de": "An/Aus",
                            "ja": "オンオフ",
                            "zh-Hans": "开关",
                            "zh-Hant": "開關" },
                        "type": "boolean",
                        "forms": [...]
                    },
                    "status": {
                        "title" : "Zustand",
                        "titles": {
                            "en": "Status",
                            "de": "Zustand",
                            "ja": "状態",
                            "zh-Hans": "状态",
                            "zh-Hant": "狀態" },
                        "type": "object",
                        ...
            }
            

Context Extension

In addition to the standard vocabulary definitions as defined in Section , the Thing Description offers the possibility to add context knowledge from different namespaces. This mechanism can be used to enrich the content of the Thing Description instances with additional (e.g., domain specific) semantics. In addition, it can also be used to specify some configurations and behaviors of the underlying communication protocols announced in the forms field.

For this extension the Thing Description uses the @context mechanism known from JSON-LD. The usage and serializiation of the @context within the Thing Description is specified in Section .

When adding additional vocabulary to a Thing Description instance, it is recommended that these vocabulary be linked to a namespace context that is within the JSON name @context container is specified.

If included namespaces are based on class definitions such as those provided by the RDF Schema or OWL, the Things Description also allows the use of @type known from JSON-LD to associate the affiliation to a class.

        {
            "@context": [
                "http://www.w3.org/ns/td",
                {"om": "http://www.wurvoc.org/vocabularies/om-1.8/"},
                {"saref": "https://w3id.org/saref#"}
            ],
            "@type": "Thing",
            ...
            "properties": {
                "Temperature": {
                    "@type": "saref:Temperature",
                    "description": "Temperature value of the weather station",
                    "om:unit_of_measure": "om:degree_Celsius",
                    "readOnly": true,
                    "observable": true,
                    "writeOnly": false,
                    "type": "number",
                    "forms" : [...]
                },
                ...
            }
        }
    

With the context extension in the Thing Description, communication metadata can be supplemented or specified in the declarations forms. This is useful when default assumptions as defined in [[[!WOT-PROTOCOL-BINDING]]] need to be overwritten.

The following example shows a property "brightness" that offers a read, write, and observe operation within the forms deceleration.

For the read operation, the deceleration follows the default assumption to execute an HTTP GET as defined in [[[!WOT-PROTOCOL-BINDING]]]. The write operation overwrites the default assumption (= HTTP PUT) and declares with the context extension the HTTP POST method to be used for this operation. In order to observe this property, the context extension is used here to announce that an HTTP GET is always running to follow the long poll mechanism.

Media Type

The JSON-based serialization of the TD is identified by the media type [[!IANA-MEDIA-TYPES]] application/td+json.

CoAP-based WoT implementations can use the experimental Content-Format 65100 until a proper identifier has been registered.

The media type application/td+json MUST be also associated with the JSON-LD context http://www.w3.org/ns/td. That means that this media type can also be used for contextual identification of the vocabulary within a (simplified) TD instance that may omit the @context name term.

Neither the application/td+json content type nor a CoAP Content-Format identifier have been registered with IANA yet.

Implementation Notes

Thing Description Processing and Interpretation

The minimum requirement to read the content of a Thing Description instance is a (simple) JSON parser.

For reasons of simplification and/or compactness, exchanged Thing Descriptions instances may omit mandatory vocabulary terms that have default value assumptions (aka Simple Thing Description representation). In this case, the Thing Description Processor must follow the default assumptions for these vocabulary terms: If the name terms readOnly, writeOnly, and/or observable are not present within a properties interaction definition, the default value defined in MUST be assumed.

If the name terms idempotent and/or safe are not present within an actions interaction definition, the default value defined in MUST be assumed.

If the contentType name term is not present within a forms definition, the default value as defined in MUST be assumed.

The accompanying document [[!WOT-PROTOCOL-BINDING]] is recommended for interpreting the protocol-specific information that is typical defined within the forms container.

To integrate a Thing Description instance with external knowledge and contextual information (like iot.schema.org annotations), the use of JSON-LD and RDF-based tools and libraries is highly recommended, as explained in the next sub-section.

Transformation to JSON-LD & RDF

A Thing Description instance MAY also be represented in RDF for further integration with other RDF datasets and ontologies. A bidirectional transformation exists between the plain JSON representation of a Thing Description instance and its alternative RDF representation. More details on the RDF representation are given in the TD ontology documentation [[wot-td-ontology]], In terms of implementation, the JSON representation can first be turned into JSON-LD 1.0, for which a standard transformation to RDF exists with numerous implementations [[json-ld-api]]. In contrast to plain JSON, a JSON-LD object can have a context (@context), an identifier (@id) and a type (@type). In this section, we define a procedure to add these three keys to the JSON objects of a Thing Description instance.

Because the data models of JSON and RDF are not strictly equivalent, a pure transformation to JSON-LD would not be fully reversible. The original structure of the Thing Description instance can be preserved by using JSON pointers as JSON-LD identifiers [[rfc6901]]. A JSON pointer is a string encoding a path in a JSON document, like /properties/status that "points" to the status property in the examples of Sec. . JSON pointers can be defined as relative to a base IRI to be valid JSON-LD identifiers.

A JSON document is a tree of JSON values. JSON objects and arrays can have edges to children values, annotated with JSON keys (plain strings or integers). JSON strings, numbers, integers and booleans, as well as null values, are leaf nodes. The transformation algorithm from plain JSON to JSON-LD is a traversal of a Thing Description instance (a JSON document), as follows:

  1. Let identifier be the id value and base the base value of the Thing Description instance's root object. For every JSON object object in the Thing Description instance:

    1. Contruct a JSON pointer pointer for the current JSON value. If object is not an index container (see index container list below) and if object has no @id key, assign the concatenation of identifier and pointer to the @id key of object.
    2. If object is an instance of one of the classes from Sec. (see type mapping below), initialize type with the corresponding class names. Let type definition be the value of object for the key @type. If type definition is not defined, initialize it as an empty array. If it is not an array, define it as a singleton array containing type definition. Then, append type to it.
    3. If object is the root object of the Thing Description instance, the root object of a data schema or a security definition, initialize context with the corresponding JSON-LD context (see index container list below). Let context definition be the value of object for the key @context. If context definition is not defined, initialize it as an empty array. If it is not an array, define it as a singleton array containing context definition. Then, append context to it.
    4. If object has key href, resolve its value with base as a base URI, as per Sec. 5 of [[rfc3986]].

The following tables give regular expressions on JSON pointers to implement the conditionals above.

Regular Expression
/properties
/actions
/events
/properties(/.*)?/properties
/actions/[^/]*/input(/.*)?/properties
/actions/[^/]*/output(/.*)?/properties
/events/[^/]*/data(/.*)?/properties
/events/[^/]*/subscription(/.*)?/properties
/events/[^/]*/cancellation(/.*)?/properties
Index container list
Regular Expression Type
(empty string) Thing
/properties/[^/]* Property
/actions/[^/]* Action
/events/[^/]* Event
(/.*)?/forms/[0-9]* Form
(/.*)?/forms/[0-9]*/response ExpectedResponse
/links/[0-9]* Link
/version Versioning
/properties/[^/]* DataSchema
/actions/[^/]*/input DataSchema
/actions/[^/]*/output DataSchema
/events/[^/]*/data DataSchema
/events/[^/]*/subscription DataSchema
/events/[^/]*/cancellation DataSchema
Type mapping
Regular Expression Context
(empty string) http://www.w3.org/ns/td
/properties/[^/]* http://www.w3.org/ns/json-schema
/actions/[^/]*/input idem
/actions/[^/]*/output idem
/events/[^/]*/data idem
/events/[^/]*/subscription idem
/events/[^/]*/cancellation idem
/security/[^/]* http://www.w3.org/ns/wot-security
Context mapping

Currently, the context served at http://www.w3.org/ns/td is a JSON-LD 1.1 context. The complete transformation will therefore fail.

Currently, no context is served at http://www.w3.org/ns/json-schema and http://www.w3.org/ns/wot-security.

The algorithm will not correctly process TD identifiers (IRIs) that do not finish with the path component (e.g. urn:example:thing#someFragment).

Behavioral Constraints

The following assertions relate to the behavior of components of a WoT system, as opposed to the representation or information model of the TD. However, note that TDs are descriptive, and must in particular may be used to describe pre-existing network interfaces. In these cases, assertions cannot be made that constrain the behaviour of such pre-existing interfaces. Instead, the assertions must be interpreted as constraints on the TD to accurately represent such interfaces.

Security Behavior

To enable secure interoperation, security configurations must accurately reflect the requirements of the Thing:

Some security protocols may ask for authentication information dynamically, including required encoding or encryption schemes. One consequence of the above is that if a protocol asks for a form of security credentials or an encoding or encryption scheme not declared in the Thing Description then the Thing Description is to be considered invalid.

Data Constraints

The data schemas provided in the TD should accurately represent the data payloads returned and accepted by the described Thing in the interactions specified in the TD. In general, clients should follow the data schemas strictly, not generating anything not given in the WoT Thing Description, but should accept additional data from the server not given explicitly in the WoT Thing Decription for that server. In general, servers are described by WoT Thing Descriptions, but clients are constrained to follow WoT Thing Descriptions when interacting with servers.

Example Thing Description Instances

MyLampThing Example with CoAP Binding

Feature list of the Thing:

{
    "id": "urn:dev:wot:com:example:servient:lamp",
    "name": "MyLampThing",
    "description" : "MyLampThing uses JSON serialization",
    "securityDefinitions": {"psk_sc":{"scheme": "psk"}},
    "security": ["psk_sc"],
    "properties": {
        "status": {
            "description" : "Shows the current status of the lamp",
            "type": "string",
            "forms": [{
                "href": "coaps://mylamp.example.com/status"
            }]
        }
    },
    "actions": {
        "toggle": {
            "description" : "Turn on or off the lamp",
            "forms": [{
                "href": "coaps://mylamp.example.com/toggle"
            }]
        }
    },
    "events": {
        "overheating": {
            "description" : "Lamp reaches a critical temperature (overheating)",
            "data": {"type": "string"},
            "forms": [{
                "href": "coaps://mylamp.example.com/oh"
            }]
        }
    }
}

MyLightSensor Example with MQTT Binding

Feature list of the Thing:

        {
            "name": "MyLightSensor",
            "id": "urn:dev:wot:com:example:servient:lightsensor",
            "securityDefinitions": {"nosec_sc": {"scheme": "nosec"}},
            "security": ["nosec_sc"],
            "events": {
                "lightSensor": {
                    "data":{"type": "integer"},
                    "forms": [
                        {
                            "href": "mqtt://192.168.1.187:1883/lightSensor",
                            "contentType" : "text/plain"
                        }
                    ]
                }
            } 
        }

Security and Privacy Considerations

In general the security measures taken to protect a WoT system will depend on the threats and attackers that system may face and the value of the assets needs to protect. A detailed discussion of security and privacy considerations for the Web of Things, including a threat model that can be adapted to various circumstances, is presented in the informative document [[!WOT-SECURITY-CONSIDERATIONS]]. This section discusses only security and privacy risks and possible mitigations directly relevant to the WoT Thing Description.

A WoT Thing Description can describe both secure and insecure network interfaces. When a Thing Description is retro-fitted to an existing network interface, no change in the security status of the network interface is to be expected.

When designing new devices and services for use with the WoT, we have documented a suggested set of best practices in [[!WOT-SECURITY-BEST-PRACTICES]] to improve security. This best-practices document may be updated as security measures evolve. Following these practices does not guarantee security, but it at least will help to avoid common known vulnerabilities.

The use of a WoT Thing Description introduces the security and privacy risks given in the following sections. After each risk, we suggest some possible mitigations.

Context Dereferencing Privacy Risk

Deferencing the vocabulary files given in the @context member of any JSON-LD document can be a privacy risk. In the case of the WoT, an attacker can observe the network traffic produced by such deferences and can use the metadata of the dereference, such as the destination IP address, to infer information about the device especially if domain-specific vocabularies are used. This is a risk even if the connection is encrypted, and is related to DNS privacy leaks.

Mitigation:
Avoid actual dereferencing of vocabulary files. Vocabulary files should be cached whenever possible. Ideally they would be made immutable, built into the interpreting device, and not derefenced at all, with the URI in the @context member serving only as an identifier of the (known) vocabulary. This requires the use of strict version control, as updates should use a new URI to ensure that existing URIs can refer to immutable data. Use well-known standard vocabulary files whenever possible to improve the chances that the context file will be available locally to systems interpreting the metadata in a Thing Description.
Immutable Identifiers Privacy Risk

The fact that a Thing Description contains a unique identifier means that should it be associated with a person it can be used to track that person and therefore pose a risk to privacy.

Mitigation:
All identifiers should be mutable, and there should be a mechanism to update the id of a Thing. Specifically, the id of a Thing should not be fixed in hardware. This does, however, conflict with the Linked Data ideal that identifiers are fixed URIs. In many circumstances it will be acceptable to only allow updates to identifiers if a Thing is reinitialized. In this case as a software entity the old Thing ceases to exist and a new Thing is created. This can be sufficient to break a tracking chain when, for example, a device is sold to a new owner. Alternatively, if more frequent changes are desired during the operational phase of a device, a mechanism can be put into place to notify only authorized users of the change in identifier when a change is made. Note however that some classes of devices, e.g. medical devices, may require immutable IDs by law in some jurisdictions. In this case extra attention should be paid to secure access to files, such as Thing Descriptions, containing such immutable identifiers.

Fingerprinting Privacy Risk

As noted above, the id member in a TD can pose a privacy risk. However, even if the id is updated as described to mitigate its tracking risk, it may still be possible to associate a TD with a particular physical device, and from there to a person, through fingerprinting.

Mitigation:
Only authorized users should be provided access to the Thing Description for a Thing. If the TD is only distributed to authorized users through secure and confidential channels, for example through a directory service that requires authentication, the risk can be minimized.
TD Interception and Tampering Security Risk

Intercepting and tampering with TDs can be used to launch man-in-the-middle attacks, for example by rewriting URLs in TDs to redirect accesses to a malicious intermediary that can capture or manipulate data.

Mitigation:
Obtain Thing Descriptions only through mutually authenticated channels. This ensures that the client and the server are both sure of the identity of the other party to the communication. This is also necessary in order to deliver TDs only to authorized users.
Context Interception and Tampering Security Risk

Intercepting and tampering with context files can be used to facilitate attacks by modifying the interpretation of vocabulary.

Mitigation:
Ideally context files would only be obtained through authenticated channels but it is notable (and unfortunate) that many contexts are indicated using HTTP URLs, which are vulnerable to interception and modification if dereferenced. However, if context files are immutable and cached, and dereferencing is avoided whenever possible, then this risk can be reduced.
Inferencing of Personally Identifiable Information Privacy Risk

In many locales, in order to protect the privacy of users, there are legal requirements for the handling of personally identifiable information, that is, information that can be associated with a particular person. Such information can of course be generated by IoT devices directly. However, the existence and metadata of IoT devices (the kind of data stored in a Thing Description) can also contain or be used to infer personally identifiable information. This information can be as simple as the fact that a certain person owns a certain type of device, which can lead to additional inferences about that person.

Mitigation:
Treat a Thing Description associated with a personal device as if it contained personally identifiable information. As an example application of this principle, consider how to obtain user consent. Consent for usage of personally identifiable data generated by a Thing is often obtained when a Thing is paired with system consuming the data, which is frequently also when the Thing Description is registered with a local directory or the system consuming the Thing Description in order to access the device. In this case consent for using data from a Thing can be combined with consent for accessing the Thing's Thing Description. As a second example, if we consider a TD to contain personally identifiable information, then it should not be retained indefinitely or used for purposes other than those for which consent was given.

JSON Schema for TD Instance Validation

Below is a JSON Schema [[?JSON-SCHEMA-VALIDATION]] for syntactically validating Thing Description instances serialized in JSON based format.

The Thing Description defined by this document allows for adding external vocabularies by using @context mechanism known from JSON-LD, and the terms in those external vocabularies can be used in addition to the terms defined in Section . For this reason, the below JSON schema is intentionally non-strict in that regard. You can replace the value of additionalProperties schema property true with false in order to perform a strict validation.

{
    "title": "WoT TD Schema - January 2019",
    "description": "JSON Schema representation of the TD serialisation format.",
    "$schema ": "http://json-schema.org/draft-06/schema#",
    "type": "object",
    "properties": {
        "id": {
            "type": "string"
        },
        "name": {
            "type": "string"
        },
        "properties": {
            "type": "object",
            "additionalProperties": {
                "$ref": "#/definitions/property_element"
            }
        },
        "actions": {
            "type": "object",
            "additionalProperties": {
                "$ref": "#/definitions/action_element"
            }
        },
        "descriptions": {
            "$ref": "#/definitions/descriptions"
        },
        "version": {
            "type": "object",
            "properties": {
                "instance": {
                    "type": "string"
                }
            },
            "required": [
                "instance"
            ]
        },
        "description": {
            "$ref": "#/definitions/description"
        },
        "links": {
            "type": "array",
            "items": {
                "$ref": "#/definitions/link_element"
            }
        },
        "forms": {
            "type": "array",
            "minItems": 1,
            "items": {
                "$ref": "#/definitions/form_element_root"
            }
        },
        "base": {
            "$ref": "#/definitions/url"
        },
        "securityDefinitions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
                "$ref": "#/definitions/securityScheme"
            }
        },
        "support": {
            "type": "string"
        },
        "created": {
            "type": "string"
        },
        "lastModified": {
            "type": "string"
        },
        "events": {
            "type": "object",
            "additionalProperties": {
                "$ref": "#/definitions/event_element"
            }
        },
        "security": {
            "type": "array",
            "minItems": 1,
            "items": {
                "type": "string"
            }
        },
        "@type": {
            "$ref": "#/definitions/type_declaration"
        },
        "@context": {
            "$ref": "#/definitions/context"
        }
    },
    "required": [
        "name",
        "id",
        "security",
        "securityDefinitions"
    ],
    "additionalProperties": true,
    "definitions": {
        "context": {
            "oneOf": [
                {
                    "type": "array",
                    "items": {
                        "anyOf": [
                            {
                                "$ref": "#/definitions/url"
                            },
                            {
                                "type": "object"
                            }
                        ]
                    },
                    "contains": {
                        "type": "string",
                        "enum": [
                            "http://www.w3.org/ns/td"
                        ]
                    }
                },
                {
                    "type": "string",
                    "enum": [
                        "http://www.w3.org/ns/td"
                    ]
                }
            ]
        },
        "type_declaration": {
            "oneOf": [
                {
                    "type": "string"
                },
                {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            ]
        },
        "property_element": {
            "type": "object",
            "properties": {
                "description": {
                    "$ref": "#/definitions/description"
                },
                "title": {
                    "$ref": "#/definitions/title"
                },
                "descriptions": {
                    "$ref": "#/definitions/descriptions"
                },
                "titles": {
                    "$ref": "#/definitions/titles"
                },
                "uriVariables": {
                    "$ref": "#/definitions/dataSchema"
                },
                "@type": {
                    "$ref": "#/definitions/type_declaration"
                },
                "forms": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                        "$ref": "#/definitions/form_element_property"
                    }
                },
                "observable": {
                    "type": "boolean"
                },
                "writeOnly": {
                    "type": "boolean"
                },
                "readOnly": {
                    "type": "boolean"
                },
                "oneOf": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/dataSchema"
                    }
                },
                "unit": {
                    "type": "string"
                },
                "enum": {
                    "type": "array",
                    "minItems": 1,
                    "uniqueItems": true
                },
                "const": {},
                "type": {
                    "type": "string",
                    "enum": [
                        "boolean",
                        "integer",
                        "number",
                        "string",
                        "object",
                        "array",
                        "null"
                    ]
                },
                "items": {
                    "$ref": "#/definitions/dataSchema"
                },
                "maxItems": {
                    "type": "integer",
                    "minimum": 0
                },
                "minItems": {
                    "type": "integer",
                    "minimum": 0
                },
                "minimum": {
                    "type": "number"
                },
                "maximum": {
                    "type": "number"
                },
                "properties": {
                    "additionalProperties": {
                        "$ref": "#/definitions/dataSchema"
                    }
                },
                "required": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            },
            "required": [
                "forms"
            ],
            "additionalProperties": true
        },
        "action_element": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string"
                },
                "descriptions": {
                    "$ref": "#/definitions/descriptions"
                },
                "title": {
                    "type": "string"
                },
                "titles": {
                    "$ref": "#/definitions/titles"
                },
                "uriVariables": {
                    "$ref": "#/definitions/dataSchema"
                },
                "@type": {
                    "$ref": "#/definitions/type_declaration"
                },
                "forms": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                        "$ref": "#/definitions/form_element_action"
                    }
                },
                "input": {
                    "$ref": "#/definitions/dataSchema"
                },
                "output": {
                    "$ref": "#/definitions/dataSchema"
                },
                "safe": {
                    "type": "boolean"
                },
                "idempotent": {
                    "type": "boolean"
                }
            },
            "required": [
                "forms"
            ],
            "additionalProperties": true
        },
        "event_element": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string"
                },
                "descriptions": {
                    "$ref": "#/definitions/descriptions"
                },
                "titles": {
                    "$ref": "#/definitions/titles"
                },
                "uriVariables": {
                    "$ref": "#/definitions/dataSchema"
                },
                "title": {
                    "type": "string"
                },
                "@type": {
                    "$ref": "#/definitions/type_declaration"
                },
                "forms": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                        "$ref": "#/definitions/form_element_event"
                    }
                },
                "subscription": {
                    "$ref": "#/definitions/dataSchema"
                },
                "data": {
                    "$ref": "#/definitions/dataSchema"
                },
                "cancellation": {
                    "$ref": "#/definitions/dataSchema"
                },
                "type": {
                    "not": {}
                },
                "enum": {
                    "not": {}
                },
                "const": {
                    "not": {}
                }
            },
            "required": [
                "forms"
            ],
            "additionalProperties": true
        },
        "form_element_property": {
            "type": "object",
            "properties": {
                "href": {
                    "$ref": "#/definitions/url"
                },
                "op": {
                    "oneOf": [
                        {
                            "type": "string",
                            "enum": [
                                "readproperty",
                                "writeproperty",
                                "observeproperty"
                            ]
                        },
                        {
                            "type": "array",
                            "items": {
                                "type": "string",
                                "enum": [
                                    "readproperty",
                                    "writeproperty",
                                    "observeproperty"
                                ]
                            }
                        }
                    ]
                },
                "contentType": {
                    "type": "string"
                },
                "security": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "scopes": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "subProtocol": {
                    "type": "string",
                    "enum": [
                        "longpoll"
                    ]
                },
                "response": {
                    "type": "object",
                    "properties": {
                        "contentType": {
                            "type": "string"
                        }
                    }
                }
            },
            "required": [
                "href"
            ],
            "additionalProperties": true
        },
        "form_element_action": {
            "type": "object",
            "properties": {
                "href": {
                    "$ref": "#/definitions/url"
                },
                "op": {
                    "oneOf": [
                        {
                            "type": "string",
                            "enum": [
                                "invokeaction"
                            ]
                        },
                        {
                            "type": "array",
                            "items": {
                                "type": "string",
                                "enum": [
                                    "invokeaction"
                                ]
                            }
                        }
                    ]
                },
                "contentType": {
                    "type": "string"
                },
                "security": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "scopes": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "subProtocol": {
                    "type": "string",
                    "enum": [
                        "longpoll"
                    ]
                },
                "response": {
                    "type": "object",
                    "properties": {
                        "contentType": {
                            "type": "string"
                        }
                    }
                }
            },
            "required": [
                "href"
            ],
            "additionalProperties": true
        },
        "form_element_event": {
            "type": "object",
            "properties": {
                "href": {
                    "$ref": "#/definitions/url"
                },
                "op": {
                    "oneOf": [
                        {
                            "type": "string",
                            "enum": [
                                "subscribeevent",
                                "unsubscribeevent"
                            ]
                        },
                        {
                            "type": "array",
                            "items": {
                                "type": "string",
                                "enum": [
                                    "subscribeevent",
                                    "unsubscribeevent"
                                ]
                            }
                        }
                    ]
                },
                "contentType": {
                    "type": "string"
                },
                "security": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "scopes": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "subProtocol": {
                    "type": "string",
                    "enum": [
                        "longpoll"
                    ]
                },
                "response": {
                    "type": "object",
                    "properties": {
                        "contentType": {
                            "type": "string"
                        }
                    }
                }
            },
            "required": [
                "href"
            ],
            "additionalProperties": true
        },
        "form_element_root": {
            "type": "object",
            "properties": {
                "href": {
                    "$ref": "#/definitions/url"
                },
                "op": {
                    "oneOf": [
                        {
                            "type": "string",
                            "enum": [
                                "readallproperties",
                                "writeallproperties",
                                "readmultipleproperties",
                                "writemultipleproperties"
                            ]
                        },
                        {
                            "type": "array",
                            "items": {
                                "type": "string",
                                "enum": [
                                    "readallproperties",
                                    "writeallproperties",
                                    "readmultipleproperties",
                                    "writemultipleproperties"
                                ]
                            }
                        }
                    ]
                },
                "contentType": {
                    "type": "string"
                },
                "security": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "scopes": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "subProtocol": {
                    "type": "string",
                    "enum": [
                        "longpoll"
                    ]
                },
                "response": {
                    "type": "object",
                    "properties": {
                        "contentType": {
                            "type": "string"
                        }
                    }
                }
            },
            "required": [
                "href"
            ],
            "additionalProperties": true
        },
        "description": {
            "type": "string"
        },
        "title": {
            "type": "string"
        },
        "descriptions": {
            "type": "object"
        },
        "titles": {
            "type": "object"
        },
        "dataSchema": {
            "type": "object",
            "properties": {
                "description": {
                    "$ref": "#/definitions/description"
                },
                "title": {
                    "$ref": "#/definitions/title"
                },
                "descriptions": {
                    "$ref": "#/definitions/descriptions"
                },
                "titles": {
                    "$ref": "#/definitions/titles"
                },
                "writeOnly": {
                    "type": "boolean"
                },
                "readOnly": {
                    "type": "boolean"
                },
                "oneOf": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/dataSchema"
                    }
                },
                "unit": {
                    "type": "string"
                },
                "enum": {
                    "type": "array",
                    "minItems": 1,
                    "uniqueItems": true
                },
                "const": {},
                "type": {
                    "type": "string",
                    "enum": [
                        "boolean",
                        "integer",
                        "number",
                        "string",
                        "object",
                        "array",
                        "null"
                    ]
                },
                "items": {
                    "$ref": "#/definitions/dataSchema"
                },
                "maxItems": {
                    "type": "integer",
                    "minimum": 0
                },
                "minItems": {
                    "type": "integer",
                    "minimum": 0
                },
                "minimum": {
                    "type": "number"
                },
                "maximum": {
                    "type": "number"
                },
                "properties": {
                    "additionalProperties": {
                        "$ref": "#/definitions/dataSchema"
                    }
                },
                "required": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            }
        },
        "link_element": {
            "type": "object",
            "properties": {
                "anchor": {
                    "$ref": "#/definitions/url"
                },
                "href": {
                    "$ref": "#/definitions/url"
                },
                "rel": {
                    "type": "string"
                },
                "type": {
                    "type": "string"
                }
            },
            "required": [
                "href"
            ],
            "additionalProperties": true
        },
        "securityScheme": {
            "oneOf": [
                {
                    "type": "object",
                    "properties": {
                        "description": {
                            "type": "string"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "nosec"
                            ]
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "description": {
                            "type": "string"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "basic"
                            ]
                        },
                        "in": {
                            "type": "string",
                            "enum": [
                                "header",
                                "query",
                                "body",
                                "cookie"
                            ]
                        },
                        "name": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "description": {
                            "type": "string"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "cert"
                            ]
                        },
                        "identity": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "description": {
                            "type": "string"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "digest"
                            ]
                        },
                        "qop": {
                            "type": "string",
                            "enum": [
                                "auth",
                                "auth-int"
                            ]
                        },
                        "in": {
                            "type": "string",
                            "enum": [
                                "header",
                                "query",
                                "body",
                                "cookie"
                            ]
                        },
                        "name": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "description": {
                            "type": "string"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "bearer"
                            ]
                        },
                        "authorization": {
                            "$ref": "#/definitions/url"
                        },
                        "alg": {
                            "type": "string",
                            "enum": [
                                "MD5",
                                "ES256",
                                "ES512-256"
                            ]
                        },
                        "format": {
                            "type": "string",
                            "enum": [
                                "jwt",
                                "jwe",
                                "jws"
                            ]
                        },
                        "in": {
                            "type": "string",
                            "enum": [
                                "header",
                                "query",
                                "body",
                                "cookie"
                            ]
                        },
                        "name": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "description": {
                            "type": "string"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "psk"
                            ]
                        },
                        "identity": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "description": {
                            "type": "string"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "public"
                            ]
                        },
                        "identity": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "description": {
                            "type": "string"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "oauth2"
                            ]
                        },
                        "authorization": {
                            "$ref": "#/definitions/url"
                        },
                        "token": {
                            "$ref": "#/definitions/url"
                        },
                        "refresh": {
                            "$ref": "#/definitions/url"
                        },
                        "scopes": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        },
                        "flow": {
                            "type": "string",
                            "enum": [
                                "implicit",
                                "password",
                                "client",
                                "code"
                            ]
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "description": {
                            "type": "string"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "apikey"
                            ]
                        },
                        "in": {
                            "type": "string",
                            "enum": [
                                "header",
                                "query",
                                "body",
                                "cookie"
                            ]
                        },
                        "name": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "description": {
                            "type": "string"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "pop"
                            ]
                        },
                        "authorization": {
                            "$ref": "#/definitions/url"
                        },
                        "format": {
                            "type": "string",
                            "enum": [
                                "jwt",
                                "jwe",
                                "jws"
                            ]
                        },
                        "alg": {
                            "type": "string",
                            "enum": [
                                "MD5",
                                "ES256",
                                "ES512-256"
                            ]
                        },
                        "in": {
                            "type": "string",
                            "enum": [
                                "header",
                                "query",
                                "body",
                                "cookie"
                            ]
                        },
                        "name": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                }
            ]
        },
        "url": {
            "type": "string",
            "format": "uri-reference"
        }
    }
}

Thing Templates

A Thing Template is a description for a class of devices or things. It describes the properties, actions, events and common metadata that are shared for an entire group of things, to enable the common handling of thousands of devices by a cloud server, which is not practical on a per-thing basis. The Thing Template uses the same core vocabulary and information model from section 5.

The Thing Template enables:

The Thing Template is a logical description of the interface and possible interaction with devices (properties, actions and events), however it does not contain device-specific information, such as a serial number, GPS location, security information or concrete protocol endpoints.

Since a Thing Template does not contain a protocol binding to specific endpoints and does not define a specific security mechanism, the forms and securityDefinitions and security keys must not be present.

The same Thing Template can be implemented by things from multiple vendors, a thing can implement multiple thing templates, define additional metadata (vendor, location, security) and define bindings to concrete protocols. To avoid conflicts between properties, actions and events from different thing templates that are combined into a common thing, all thse identifiers must be unique within a thing.

A common Thing Template for a class of devices enables writing applications across vendors and creates a more attractive market for application developers. A concrete Thing Description can implement multiple Thing Templates and thus can aggregate function blocks into a combined device.

The business models of cloud vendors are typically built on managing thousands of identical devices. All devices with the same Thing Template can be managed in the same way by cloud applications. It is easy to create multiple simulated devices, if the interface and the instance are treated separately.

Since a Thing Template is a Thing Description, where some optional parts are not present, it can be serialized in the same way and into the same formats as a thing description.

Thing Template Examples

This section defines a Thing Template for a lamp and a Thing Template for a a buzzer. The combined thing BuzzerLamp includes both thing templates.

Thing Template: Lamp

    {
        "@context": ["http://www.w3.org/ns/td"], 
        "@type" : "ThingTemplate",
        "id": "urn:dev:wot:com:example:servient:lamp:model",
        "name": "Lamp Thing Template",
        "description" : "Lamp Thing Template",
        "properties": {
            "status": {
                "description" : "current status of the lamp (on|off)",
                "type": "string",
                "readOnly": true
            }
        },
        "actions": {
            "toggle": {
                "description" : "Turn the lamp on or off"
            }
        },
        "events": {
            "overheating": {
                "description" : "Lamp reaches a critical temperature (overheating)",
                "data": {"type": "string"}
            }
        }
    }
    

Thing Template: Buzzer

    {
        "@context": ["http://www.w3.org/ns/td"], 
        "@type" : "ThingTemplate",
        "id": "urn:dev:wot:com:example:servient:buzzer:template",
        "name": "Buzzer Thing Template",
        "description" : "Thing template of a buzzer that makes noise for 10 seconds",
         "actions": {
            "buzz": {
                "description" : "buzz for 10 seconds"
            }
         }
    }
    

Combined Thing: Lamp + Buzzer

The following example illustrates how a combined thing can be defined using two different thing templates.

    {
       "@context": ["http://www.w3.org/ns/td"], 
       "@type" : [
            "Thing",
            "urn:dev:wot:com:example:servient:lamp:template",
            "urn:dev:wot:com:example:servient:buzzer:template"
        ],
        "id": "urn:dev:wot:com:example:servient:combinedBuzzerLamp1",
        "name": "My Buzzing Lamp Thing",
        "description" : "A lamp that can issue an alert",
        "security": [{"scheme": "basic"}],
        {
            "id": "urn:dev:wot:com:example:servient:lamp:template",
            "name": "Lamp Thing Template",
            "description" : "Thing Template for a lamp",
            "properties": {
                "status": {
                    "description" : "current status of the lamp (on|off)",
                    "type": "string",
                    "readOnly": true,
                    "forms": [{
                    "href": "coaps://buzzlamp.example.com/status",
                    "contentType": "application/json"
                    }]
                }
            },
            "actions": {
                "toggle": {
                    "description" : "Turn on or off the lamp",
                    "forms": [{
                        "href": "coaps://buzzlamp.example.com/toggle",
                        "contentType": "application/json"
                    }]
                }
            },
            "events": {
                "overheating": {
                    "@type" : "iot:TemperatureAlarm",
                    "description" : "Lamp reaches a critical temperature (overheating)",
                    "data": {"type": "string"},
                    "forms": [{
                        "href": "coaps://buzzlamp.example.com/oh",
                        "contentType": "application/json"
                    }]
                }
            }
        },
        {
            "id": "urn:dev:wot:com:example:servient:buzzer:template",
            "name": "Buzzer Thing Template",
            "description" : "Thing Template of a buzzer that makes noise for 10 seconds",
             "actions": {
                "buzz": {
                    "description" : "buzz for 10 seconds",
                    "forms": [{
                        "href": "coaps://buzzlamp.example.com/buzz",
                        "contentType": "application/json"
                    }]
                }
             }
        }
    }
      

Recent Specification Changes

Changes from Third Public Working Draft

Changes from Second Public Working Draft

Changes from Second Public Working Draft are described in the Third Public Working Draft

Acknowledgements

The editors would like to thank Dave Raggett, Matthias Kovatsch, Michael Koster, Kawaguchi Toru, Michael Lagally, Kazuyuki Ashimura, María Poveda, Daniel Peintner, Ben Francis for their contributions, comments, and guidance.