This is the first draft of a simplified TD approach where RDF and JSON-LD considerations are assumed to be externalized in a separate Group Note [[WOT-ONTOLOGY]].
Some definitions are not finished yet and are still in progress.

Check JSON-Schema. Raise issues (ex. types of properties safe and idempotent should be boolean )

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.

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 (e.g., "http", "coap", "mqtt", etc.), content types (e.g., "application/json", "application/xml", "application/cbor", "application/exi" etc.), 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 keys 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.

{
    "id": "urn:dev:wot:com:example:servient:lamp",
    "name": "MyLampThing",
    "securityDefinitions": {
        "basic_sc": {"scheme": "basic"}
    },
    "security": ["basic_sc"],
    "properties": {
        "status" : {
            "type": "string",
            "forms": [{"href": "https://mylamp.example.com/status"}]
        }
    },
    "actions": {
        "toggle" : {
            "forms": [{"href": "https://mylamp.example.com/toggle"}]
        }
    },
    "events":{
        "overheating":{
            "data": {"type": "string"},
            "forms": [{
                "href": "https://mylamp.example.com/oh",
                "subprotocol": "longpoll"
            }]
        }
    },
    "annotation": {
      "@context": {
        "@base": "http://example.org/data/",
        "vendor": "http://vendor.org/product/"
      }
      "@type": "vendor:color-light",
      "isAbstractionOf": "appartment/134#light-1"
    }
}

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 key), 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.

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-interaction or per-form, with lower-level configurations overriding higher-level ones, 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 (readOnly, 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.

For more examples, including the use of other protocols besides HTTP, see Section .

The TD can also include additional semantic annotations, and be processed as an RDF-based model [[?rdf11-primer]]. The WoT Ontology Group Note [[?WOT-ONTOLOGY]] specifies related ontologies (defining concepts for Thing Descriptions, Security, Data Schemas), transformation algorithms from TD to RDF, and guidelines on how to use terms from external ontologies to annotate Thing Description instances: the W3C Semantic Sensor Networks ontology [[?vocab-ssn]], and iot.schema.org [[?iot.schema.org]].

Information Model

Overview

The W3C Thing Description provides a set of vocabulary for describing physical and virtual Things. All vocabulary restrictions noted in these tables MUST be followed, including mandatory items and default values.

In general, the Thing Description vocabulary set is grouped in three modules: the core Thing Description vocabulary reflecting WoT's paradigm of Properties, Actions, and Events (also see [[!WOT-ARCHITECTURE]]); the data schema vocabulary reflecting a subset of the terms defined in JSON Schema [[?JSON-SCHEMA-VALIDATION]] in a linked data representation; and the security vocabulary used to define security mechanism configuration requirements.

An overview of this vocabulary with its class context and class relation is given by the following three figures: the TD core model, the TD data schema model, and the TD security model. Please note that the figures reflect the vocabulary terms and structure as they would be used in a Thing Description instance (see Section ).

TD data schema model figure — TD data schema model

TD security model figure — TD security model

In the figures above, and in the tables to follow, items which have default values are indicated as being optional.

A detailed description of the vocabulary of the TD core model and TD data schema model is given in the next sub-section.

Core Vocabulary Definition

`Thing`

Describes a physical and/or virtual Thing (may represent one or more physical and/or virtual Things) in the Web of Things context.

Field Name	Description	Mandatory	Default value	Type
`id`	unique identifier of the Thing (URI, e.g. custom URN)	yes	.	`anyURI`
`security`	Set of security definition names, chosen from those defined in securityDefinitions. These must all be satisfied for access to resources at or below the current level, if not overridden at a lower level.	yes	.	array of `string`
`name`	Name of the Thing.	yes	.	`string`
`description`	Provides additional (human-readable) information.	no	.	`string`
`support`	Provides information about the TD maintainer (e.g., author, link or telephone number to get support, etc).	no	.	`string`
`created`	Provides information when the TD instance was created.	no	.	`string`
`lastModified`	Provides information when the TD instance was last modified.	no	.	`string`
`base`	Define the base URI that is valid for all defined local interaction resources. All other URIs in the TD must then be resolved using the algorithm defined in [[!RFC3986]].	no	.	`anyURI`
`properties`	All Property-based interaction patterns of the Thing.	no	.	`Property`
`actions`	All Action-based interaction patterns of the Thing.	no	.	`Action`
`events`	All Event-based interaction patterns of the Thing.	no	.	`Event`
`links`	Provides Web links to arbitrary resources that relate to the specified Thing Description.	no	.	array of `Link`
`securityDefinitions`	Set of named security configurations (definitions only). Not actually applied unless names are used in a security section.	no	.	`SecurityScheme`
`version`	Provides version information.	no	.	`Versioning`
`annotation`	Additional semantic annotations about the thing, preferably reusing common external vocabularies and interpretable as RDF as specified in Section X of [[WOT-ONTOLOGY]].	no	.	`Object`

`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.

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

Field Name	Description	Mandatory	Default value	Type
`forms`	Indicates one or more endpoints from which an interaction pattern is accessible.	yes	.	array of `Form`
`title`	Provides a human-readable title (e.g., display a text for UI representation) of the interaction pattern.	no	.	`string`
`uriVariables`	Define URI template variables as collection based on DataSchema declarations.	no	.	`DataSchema`
`description`	Provides additional (human-readable) information.	no	.	`string`
`security`	Set of security definition names, chosen from those defined in securityDefinitions. These must all be satisfied for access to resources at or below the current level, if not overridden at a lower level.	no	.	array of `string`
`scopes`	Set of authorization scope identifiers, provided as an array. These are provided in tokens returned by an authorization server and associated with forms in order to identify what resources a client may access and how.	no	.	array of `string`
`annotation`	Additional semantic annotations about the interaction pattern, preferably reusing common external vocabularies and interpretable as RDF as specified in Section X of [[WOT-ONTOLOGY]].	no	.	`Object`

The class InteractionPattern has the following subclasses:

Action
Event
Property

`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).

Field Name	Description	Mandatory	Default value	Type
`observable`	Indicates whether a remote servient can subscribe to ("observe") the Property, to receive change notifications or periodic updates (true/false).	no	false	`boolean`

Property instances are also instances of the class DataSchema. Therefore, it can contain the type, unit, readOnly and writeOnly fields, 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.

Field Name	Description	Mandatory	Default value	Type
`input`	Used to define the input data schema of the action.	no	.	`DataSchema`
`output`	Used to define the output data schema of the action.	no	.	`DataSchema`
`safe`	Signals if the action is safe (=true) or not. Used to signal if there is no internal state (cf. resource state) is changed when invoking an Action. In that case responses can be cached as example.	yes	false	`DataSchema`
`idempotent`	Signals if the action is idempotent (=true) or not. Informs if the action can be called repeatedly with the same outcome. .	yes	false	`DataSchema`

`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.

Field Name	Description	Mandatory	Default value	Type
`data`	Defines the data schema of the Event instance messages pushed by the Thing.	no	.	`DataSchema`
`subscription`	Defines data that needs to be passed upon subscription, e.g., filters or message format for setting up Webhooks.	no	.	`DataSchema`
`cancellation`	Defines any data that needs to be passed to cancel a subscription, e.g., a specific message to remove a Webhook.	no	.	`DataSchema`

`Form`

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

Field Name	Description	Mandatory	Default value	Type
`href`	URI of the endpoint where an interaction pattern is provided.	yes	.	`anyURI`
`contentType`	Assign a content type based on a media type [[!MEDIATYPES]] (e.g., 'application/json) and (optional) parameters (e.g., 'charset=utf-8').	yes	application/json	`string`
`op`	Indicates the expected result of performing the operation described by the form. For example, the Property interaction allows get and set operations. The protocol binding may contain a form for the get operation and a different form for the set operation. The op attribute indicates which form is which and allows the client to select the correct form for the operation required. The value of the `op` attribute of the form must be one of readproperty, writeproperty, observeproperty, invokeaction, subscribeevent, or unsubscribeevent.	no	.	`string` (one of `"readproperty"`, `"writeproperty"`, `"observeproperty"`, `"invokeaction"`, `"subscribeevent"`, or `"unsubscribeevent"`)
`subprotocol`	Indicates the exact mechanism by which an interaction will be accomplished for a given protocol when there are multiple options. For example, for HTTP and Events, it indicates which of several available mechanisms should be used for asynchronous notifications.	no	.	`string` (one of `"longpoll"`)
`security`	Set of security definition names, chosen from those defined in securityDefinitions. These must all be satisfied for access to resources at or below the current level, if not overridden at a lower level.	no	.	array of `string`
`scopes`	Set of authorization scope identifiers, provided as an array. These are provided in tokens returned by an authorization server and associated with forms in order to identify what resources a client may access and how.	no	.	array of `string`
`annotation`	Additional semantic annotations about the form, preferably reusing common external vocabularies and interpretable as RDF as specified in Section X of [[WOT-ONTOLOGY]].	no	.	`Object`

`Link`

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

Field Name	Description	Mandatory	Default value	Type
`href`	URI of the endpoint where an interaction pattern is provided.	yes	.	`anyURI`
`type`	Provides a hint indicating what the media type [[!MEDIATYPES]] of the result of dereferencing the link should be.	no	.	`string`
`rel`	Indicates the relation to an other Thing.	no	.	`string`
`anchor`	By default, the context of a link is the URL of the representation it is associated with, and is serialised as a URI. When present, the anchor parameter overrides this with another URI, such as a fragment of this resource, or a third resource (i.e., when the anchor value is an absolute URI).	no	.	`anyURI`
`annotation`	Additional semantic annotations about the link, preferably reusing common external vocabularies and interpretable as RDF as specified in Section X of [[WOT-ONTOLOGY]].	no	.	`Object`

`Versioning`

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.

Field Name	Description	Mandatory	Default value	Type
`instance`	Provides a version identicator of this TD instance.	yes	.	`string`

Data Schema Vocabulary Definition

`DataSchema`

Field Name	Description	Mandatory	Default value	Type
`description`	Provides additional (human-readable) information.	no	.	`string`
`title`	Provides a human-readable title (e.g., display a text for UI representation) of the interaction pattern.	no	.	`string`
`type`	Assignment of JSON-based data types compatible with JSON Schema (one of boolean, integer, number, string, object, array, or null).	no	.	`string` (one of `"boolean"`, `"integer"`, `"number"`, `"string"`, `"object"`, `"array"`, or `"null"`)
`const`	Provides a constant value.	no	.	a value of any type that is consistent with the type given to the above `type` field definition if any
`unit`	Provides unit information that is used, e.g., in international science, engineering, and business.	no	.	`string`
`enum`	Restricted set of values provided as an array.	no	.	array of values of any type with each consistent with the type given to the above `type` field definition if any
`readOnly`	Boolean value that indicates whether a property interaction / value is read only (=true) or not (=false).	yes	false	`boolean`
`writeOnly`	Boolean value that indicates whether a property interaction / value is write only (=true) or not (=false).	yes	false	`boolean`
`dataSchemaAnnotation`	Additional semantic annotations about the data schema, preferably reusing common external vocabularies and interpretable as RDF as specified in Section X of [[WOT-ONTOLOGY]].	no	.	`Object`

The class DataSchema has the following subclasses:

ArraySchema
BooleanSchema
IntegerSchema
NumberSchema
ObjectSchema
StringSchema

`ArraySchema`

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

Field Name	Description	Mandatory	Default value	Type
`items`	Used to define the characteristics of an array.	no	.	`DataSchema`
`minItems`	Defines the minimum number of items that have to be in the array.	no	.	`unsignedInt`
`maxItems`	Defines the maximum number of items that have to be in the array.	no	.	`unsignedInt`

`ObjectSchema`

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

Field Name	Description	Mandatory	Default value	Type
`properties`	Data schema nested definitions.	no	.	`DataSchema`
`required`	Defines which members of the object type are mandatory.	no	.	array of `string`

`BooleanSchema`

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

`NumberSchema`

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

Field Name	Description	Mandatory	Default value	Type
`minimum`	Specifies a minimum numeric value. Only applicable for associated number or integer types.	no	.	`double`
`maximum`	Specifies a maximum numeric value. Only applicable for associated number or integer types.	no	.	`double`

`StringSchema`

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

`IntegerSchema`

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

Field Name	Description	Mandatory	Default value	Type
`minimum`	Specifies a minimum numeric value. Only applicable for associated number or integer types.	no	.	`integer`
`maximum`	Specifies a maximum numeric value. Only applicable for associated number or integer types.	no	.	`integer`

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 and 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`

Field Name	Description	Mandatory	Default value	Type
`scheme`	Identification of security mechanism being configured.	yes	.	`string` (one of `"nosec"`, `"basic"`, `"cert"`, `"digest"`, `"bearer"`, `"pop"`, `"psk"`, `"public"`, `"oauth2"`, or `"apikey"`)
`description`	Provides additional (human-readable) information.	no	.	`string`
`proxy`	URI of the proxy server this security configuration provides access to. If not given, the corresponding security configuration is for the endpoint.	no	.	`anyURI`
`annotation`	Additional semantic annotations about the security scheme, preferably reusing common external vocabularies and interpretable as RDF as specified in Section X of [[WOT-ONTOLOGY]].	no	.	`Object`

The class SecurityScheme has the following subclasses:

APIKeySecurityScheme
BasicSecurityScheme
BearerSecurityScheme
CertSecurityScheme
DigestSecurityScheme
NoSecurityScheme
OAuth2SecurityScheme
PSKSecurityScheme
PoPSecurityScheme
PublicSecurityScheme

`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.

Field Name	Description	Mandatory	Default value	Type
`in`	Specifies the location of security authentication information (one of header, query, body, or cookie).	no	header	`string`
`name`	Name for query, header, or cookie parameters.	no	.	`string`

`CertSecurityScheme`

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

Field Name	Description	Mandatory	Default value	Type
`identity`	Pre-shared key identity.	no	.	`string`

`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.

Field Name	Description	Mandatory	Default value	Type
`qop`	Quality of protection (one of auth or auth-int).	no	auth	`string`
`in`	Specifies the location of security authentication information (one of header, query, body, or cookie).	no	header	`string`
`name`	Name for query, header, or cookie parameters.	no	.	`string`

`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.

Field Name	Description	Mandatory	Default value	Type
`authorization`	URI of the authorization server.	no	.	`anyURI`
`alg`	Encoding, encryption, or digest algorithm (one of MD5, ES256, or ES512-256).	no	ES256	`string`
`format`	Specifies format of security authentication information (one of jwt, jwe, or jws).	no	jwt	`string`
`in`	Specifies the location of security authentication information (one of header, query, body, or cookie).	no	header	`string`
`name`	Name for query, header, or cookie parameters.	no	.	`string`

`PSKSecurityScheme`

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

Field Name	Description	Mandatory	Default value	Type
`identity`	Pre-shared key identity.	no	.	`string`

`PublicSecurityScheme`

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

Field Name	Description	Mandatory	Default value	Type
`identity`	Pre-shared key identity.	no	.	`string`

`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.

Field Name	Description	Mandatory	Default value	Type
`authorization`	URI of the authorization server.	no	.	`anyURI`
`token`	URI of the token server.	no	.	`anyURI`
`refresh`	URI of the refresh server.	no	.	`anyURI`
`scopes`	Set of authorization scope identifiers, provided as an array. These are provided in tokens returned by an authorization server and associated with forms in order to identify what resources a client may access and how.	no	.	array of `string`
`flow`	Authorization flow (one of implicit, password, client, or code).	no	implicit	`string`

`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.

Field Name	Description	Mandatory	Default value	Type
`in`	Specifies the location of security authentication information (one of header, query, body, or cookie).	no	query	`string`
`name`	Name for query, header, or cookie parameters.	no	.	`string`

`PoPSecurityScheme`

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

Field Name	Description	Mandatory	Default value	Type
`authorization`	URI of the authorization server.	no	.	`anyURI`
`alg`	Encoding, encryption, or digest algorithm (one of MD5, ES256, or ES512-256).	no	ES256	`string`
`format`	Specifies format of security authentication information (one of jwt, jwe, or jws).	no	jwt	`string`
`in`	Specifies the location of security authentication information (one of header, query, body, or cookie).	no	header	`string`
`name`	Name for query, header, or cookie parameters.	no	.	`string`

Thing Description Serialization

This is the first draft of a simplified TD approach where RDF and JSON-LD considerations are assumed to be externalized in a separate Group Note [[?WOT-ONTOLOGY]].

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

Representation Format

In order to enable this convergence, all vocabulary terms defined in Section will have a JSON key 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:

Vocabulary terms that use simple types string and anyURI MUST be serialized as JSON string.
Vocabulary terms that use simple type unsignedInt MUST be serialized as JSON integer.
Vocabulary terms that use simple type double MUST be serialized as JSON number.

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

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

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

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

A TD snippet based on the defined fields of the class Thing is given below:

{
    "id": "urn:dev:wot:com:example:servient:myThing",
    "name": "MyThing",
    "description": "Additional (human) readable information of the Thing.",
    "support": "https://servient.example.com/contact",
    "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": [...]
}

`properties`

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

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 key within a Property object.

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

The type of the fields forms, required, and enum, scopes, and security, MUST be serialized as a JSON array.

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

{
    ...
    "properties": {
        "on": {
            "title": "On/Off",
            "type": "boolean",
            "forms": [...]
        },
        "status": {
            "type": "object",
            "properties": {
                "brightness": {
                    "type": "number",
                    "minimum": 0.0,
                    "maximum": 100.0
                 },
                 "rgb": {
                    "type": "array",
                    "items" : {
                        "type" : "number",
                        "minimum": 0,
                        "maximum": 255
                    },
                    "minItems": 3,
                    "maxItems": 3
                }
            },
            "required": ["brightness", "rgb"],
            "forms": [...]
        }
    }
    ...
}

`actions`

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

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

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

The keys of input and output rely on the the class DataSchema.

The type of the fields forms, scopes, and security MUST be serialized as a JSON array.

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

    ...
    "actions": {
        "fade" : {
            "title": "Fade in/out",
            "description": "Smooth fade in and out animation.",
            "input": {
                "type": "object",
                "properties": {
                    "from": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                    },
                    "to": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                    },
                    "duration": {"type": "number"}
                },
                "required": ["to","duration"],
            },
            "output": {"type": "string"},
            "forms": [...]
        }
        ...
    }
    ...

`events`

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

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 key within an Event object.

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

The keys of subscription, data, and cancellation rely on the the class DataSchema.

The type of the fields forms, required, and enum, scopes, and security MUST be serialized as a JSON array.

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

    ...
    "events": {
        "overheated": {
            "data" : {"type": "object"},
            "properties": {
                "temperature": { "type": "number" }
            },
            "forms": [...]
        }
        ...
    }
    ...

`forms`

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

If required, forms MAY be supplemented with protocol-specific vocabulary terms identified with a prefix. See also [[!WOT-PROTOCOL-BINDING]].

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

{
  ...
  "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. It 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 field with the associated (unique) variables names as JSON keys.

The keys of uriVariables rely on the the class DataSchema.

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

        ...
        "actions": {
            "LeftDown": {
              "uriVariables": {
                "p" : { "type": "integer", "minimum": 0, "maximum": 16, "@type": "example:SomeKindOfAngle" },
                "d" : { "type": "integer", "minimum": 0, "maximum": 1, "@type": "example:Direction" },
                }
              },
              "form": [{
                "http:method": "GET",
                "href" : "http://192.168.1.25/left{?p,d}"
              }]
            }
        ...

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

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

`links`

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

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

    ...
    "links": [{
        "href": "https://servient.example.com/things/lampController",
        "rel": "controlledBy",
        "type": "application/td+json"
    }]
    ...

`security`

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

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": {
           "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 interaction and form levels. In this case, definitions at the lower levels override (completely replace) the definitions at the higher level.

Security configuration must accurately reflect the requirements of the Thing. If a Thing requires a specific access mechanism for a resource, that mechanism MUST be specified in the Thing Description's security scheme configuration for that resource. If a Thing does not require a specific access mechanism for a resource, that mechanism MUST NOT be specified in the Thing Description's security scheme configuration for that resource. Some protocols can ask for authentication dynamically. If a protocol asks for a form of security credentials not declared in the Thing Description then the Thing Description is to be considered invalid.

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": "Additional (human) readable information of the Thing.",
    "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 elements at the same level. This may be required for devices that support multiple protocols, for example CoAP 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 field 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"},
        "apikey_sc": {"scheme": "apikey"}
    },
    "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 Versioning, MUST be serialized as a JSON key.

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

A TD snippet based on the defined fields 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 xyz context is given below:

        ...
        "version": {"instance":"1.2.1", "xyz:firmware": "0.9.1", "xyz:hardware": "1.0"}
        ...

Media Type

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

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

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

Implementation Notes

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

If the key terms readOnly and/or observable are not present within a properties definition, the default value defined in MUST be assumed.

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

Introduction

Terminology

Conformance

Information Model

Overview

Core Vocabulary Definition

Thing

InteractionPattern

Property

Action

Event

Form

Link

Versioning

Data Schema Vocabulary Definition

DataSchema

ArraySchema

ObjectSchema

BooleanSchema

NumberSchema

StringSchema

IntegerSchema

Security Vocabulary Definition

SecurityScheme

NoSecurityScheme

BasicSecurityScheme

CertSecurityScheme

DigestSecurityScheme

BearerSecurityScheme

PSKSecurityScheme

PublicSecurityScheme

OAuth2SecurityScheme

APIKeySecurityScheme

PoPSecurityScheme

Thing Description Serialization

Representation Format

Thing as a whole

properties

actions

events

forms

links

security

version

Media Type

Implementation Notes

Example Thing Description Instances

MyLampThing Example

Security and Privacy Considerations

Immutable Identifiers Privacy Risk

Fingerprinting Privacy Risk

TD Interception and Tampering Security Risk

Context Interception and Tampering Security Risk

Inferencing of Personally Identifiable Information Privacy Risk

JSON Schema for TD Instance Validation

Recent Specification Changes

Changes from Third Public Working Draft

Changes from Second Public Working Draft

Acknowledgements

`Thing`

`InteractionPattern`

`Property`

`Action`

`Event`

`Form`

`Link`

`Versioning`

`DataSchema`

`ArraySchema`

`ObjectSchema`

`BooleanSchema`

`NumberSchema`

`StringSchema`

`IntegerSchema`

`SecurityScheme`

`NoSecurityScheme`

`BasicSecurityScheme`

`CertSecurityScheme`

`DigestSecurityScheme`

`BearerSecurityScheme`

`PSKSecurityScheme`

`PublicSecurityScheme`

`OAuth2SecurityScheme`

`APIKeySecurityScheme`

`PoPSecurityScheme`

`properties`

`actions`

`events`

`forms`

`links`

`security`

`version`