This is the first draft based on the new simplified TD approach based on JSON-LD 1.1. Some definitions are not finished yet and are still in progress. A stable Thing Description deliverable version based on JSON-LD 1.0 can be found here.

This document describes a formal model and 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 entity that provides interactions to and participates in the Web of Things. Thing Descriptions provide a narrow-waist 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 JSON-LD. JSON-LD provides both a powerful foundation to represent knowledge about Things and simplicity, since it allows processing as a JSON document. In addition to physical entities, Things can also represent virtual entities. A Thing Description instance can be hosted by the Thing itself or hosted externally due to Thing's 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](https://github.com/w3c/wot-thing-description) and take part in the discussions.

Please contribute to this draft using the GitHub Issue feature of the WoT Thing Description repository. For feedback on security and privacy considerations, please use the WoT Security and Privacy Issues, as they are cross-cutting over all our documents.

Introduction

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

Properties can be used for controlling (or retrieving) parameters, such as a setting an operation state (or getting the current value). Actions model invocation of physical processes, but can also be used to abstract RPC-like calls of existing platforms. Events cover the push model where state change notifications, discrete events, and streams of values are sent asynchronously to the receiver. In general, the TD provides metadata for the different communication bindings (e.g., HTTP, CoAP, MQTT, etc.), mediaTypes (e.g., "application/json", "application/xml", "application/cbor", "application/exi" etc.), and security policies (authentication, authorization, etc.). The serialization of the TD instances is based on JSON and includes at least the TD core vocabularies as JSON keys as defined in this specification document.

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

{
    "id": "urn:dev:wot:com:example:servient:lamp",
    "name": "MyLampThing",
    "properties": {
        "status" : {
            "type": "string",
            "forms": [{"href": "coaps://mylamp.example.com:5683/status"}]
        }
    },
    "actions": {
        "toggle" : {
            "forms": [{"href": "coaps://mylamp.example.com:5683/toggle"}]
        }
    },
    "events":{
        "overheating":{
            "type": "string",
            "forms": [{"href": "coaps://mylamp.example.com:5683/oh"}]
        }
    }
}
 

Based on this content, we know there exists one Property interaction resource with the name status. In addition, information is provided such as that this Property is accessible via the CoAP protocol with a GET method (default assumption as descripted in the W3C WoT protocol template deliverable [[!WOT-PROTOCOL-BINDING]]) at coaps://mylamp.example.com:5683/status (announced within the form structure by the href key), which will return a string status value within a JSON structure (as default assumption).

In a similar manner an Action is specified to toggle the switch status using the POST method that is applied to the coaps://mylamp.example.com:5683/toggle resource (see CoAP protocol binding description in the W3C WoT protocol template deliverable [[!WOT-PROTOCOL-BINDING]]).

The WoT's Event model enables a mechanism for events to be notified by a Thing. Here, a subscription of a possible overheating event of the lamp can be applied by using CoAP OBSERVE at coaps://mylamp.example.com:5683/oh. (see CoAP protocol binding description in the W3C WoT protocol template deliverable [[!WOT-PROTOCOL-BINDING]]).

The TD in Example 1 reflects some default assumptions that are not explicitly described. E.g., this includes that the media type of the exchange format of the interactions is based on JSON (=mediaType), the property status is not writable and observable. Thus, the TD specification defines vocabularies (writable, observable, mediaType) that have default values. If these vocabularies are not implicit in a Thing Description instance, the Thing Description processor follows the default assumption for interpretation as defined here in this specification.

The TD can be also processed as a RDF-based model. In that case, the Thing Description instance can be simple transformed into a valid JSON-LD style. In terms of JSON-LD 1.1 serialization and semantic's open-world assumption the mentioned vocabularies with default values will be always implicit present in the instances. Example 2 shows the TD in JSON-LD 1.1 serializiation that contains the same information as in Example 1.

{
    "@context": "https://w3c.github.io/wot/w3c-wot-td-context.jsonld",
    "id": "urn:dev:wot:com:example:servient:lamp",
    "name": "MyLampThing",
    "properties": {
        "status": {
         "writable": false,
         "observable": false,
         "type": "string",
         "forms": [{
             "href": "coaps://mylamp.example.com:5683/status",
             "mediaType": "application/json"
         }]
    }},
    "actions": {
     "toggle": {
        "forms": [{
            "href": "coaps://mylamp.example.com:5683/toggle",
            "mediaType": "application/json"
        }]}},
    "events": {
        "overheating": {
            "type": "string",
            "forms": [{
                "href": "coaps://mylamp.example.com:5683/oh",
                "mediaType": "application/json"
            }]
        }}
}
 

Provide detail description about the semantic usage in the example. Please also check the samples provided in Section 6.7.

Terminology

The 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 vocabularies as defined in this document is http://www.w3.org/ns/td#. The Thing Description ontology is available at https://www.w3.org/ns/td/td.ttl and the conext file is available at https://www.w3.org/ns/td/w3c-wot-td-context.jsonld.

Conformance

As well as 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 5. Vocabulary Definition and Section 6. Thing Description Serializations regarding Thing description serializiation.

We need to be more precise here: How to validate a TD? E.g., structure validation and/or RDF validation? Comments are welcome.

Information Model

Overview

The Thing Description information model is a core set of definitions for terms defined in [[!WOT-ARCHITECTURE]]. These definitions take the form of a vocabulary embedded in the Resource Description Framework (RDF). An overview of this vocabulary with its class context and class relation is given by the following three figures: TD core model, TD data schema model, and TD security model.

TD core model figure
TD core model
TD data schema model figure
TD data schema model
TD security model figure
TD security model

A detailed description of the vocabularies 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 NameDescriptionMandatoryDefault valueType
securitySet of security configurations that must all be satisfied for access to resources at or below the annotated level.no.SecurityScheme
idUnique identifier of the Thing (e.g., URI, custom URN, etc.).yes.string
nameName of the Thing.yes.string
descriptionProvides additional (human) readable information.no.string
supportProvides information about TD maintainer (e.g., author, link or telephone number to get support, etc).no.string
baseDefine 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]]. This field is optional.no.anyURI
propertiesKeeps all Property-based interaction patterns of the Thing.no.Property
actionsKeeps all Action-based interaction patterns of the Thing.no.Action
eventsKeeps all Event-based interaction patterns of the Thing.no.Event
linksProvides Web links to arbitrary resources that relate to the specified Thing Description.no.Link

Property

Properties expose internal state of a Thing that can be directly accessed (get) and optionally manipulated (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 NameDescriptionMandatoryDefault valueType
propertiesData schema nested definitions.no.DataSchema
observableIndicates whether a remote servient can subscribe to ("observe") the Property, to receive change notifications or periodic updates (true/false).nofalseboolean
writableBoolean value that indicates whether a property is writable (=true) or not (=false).nofalseboolean
formsIndicates one or more endpoints from which an interaction pattern is accessible.no.Form
labelProvides a label (e.g., display a text for UI representation) of the interaction pattern.no.string
securitySet of security configurations that must all be satisfied for access to resources at or below the annotated level.no.SecurityScheme
scopesArray of authorization scope identifiers.no.string

Action

Actions offer functions of the Thing. These functions may manipulate the interal state of a Thing in a way that is not possible through setting Properties. Examples are changing internal state that is not exposed as Property, changing multiple Properties, changing Properties over time or with a process that shall not be disclosed. Actions may also be pure functions, that is, they do not use any internal state at all, e.g., for processing input data and returning the result directly.

Field NameDescriptionMandatoryDefault valueType
descriptionProvides additional (human) readable information.no.string
formsIndicates one or more endpoints from which an interaction pattern is accessible.no.Form
inputLink to the n-ary class that allows the declaration of the accepted data type of an action.no.DataSchema
outputLink to the n-ary class that allows the declaration of the data type returned by an action.no.DataSchema
labelProvides a label (e.g., display a text for UI representation) of the interaction pattern.no.string
securitySet of security configurations that must all be satisfied for access to resources at or below the annotated level.no.SecurityScheme
scopesArray of authorization scope identifiers.no.string

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 occured events.

The Event class has the same fields as the class Property.

Form

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

Field NameDescriptionMandatoryDefault valueType
hrefURI of the endpoint where an interaction pattern is provided.yes.anyURI
mediaTypeAssign underlying media type of the interaction pattern based on IANA (https://www.iana.org/assignments/media-types/media-types.xhtml).noapplication/jsonstring
relIndicates 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 value of the "rel" attribute of the form indicates which form is which and allows the client to select the correct form for the oeration required.no.string
securitySet of security configurations that must all be satisfied for access to resources at or below the annotated level.no.SecurityScheme
scopesArray of authorization scope identifiers.no.string

Link

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

Field NameDescriptionMandatoryDefault valueType
hrefURI of the endpoint where an interaction pattern is provided.yes.anyURI
mediaTypeAssign underlying media type of the interaction pattern based on IANA (https://www.iana.org/assignments/media-types/media-types.xhtml).noapplication/jsonstring
relIndicates 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 value of the "rel" attribute of the form indicates which form is which and allows the client to select the correct form for the oeration required.no.string
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).no.anyURI

Data Schema Vocabulary Definition

DataSchema

Any JSON value specification.

Field NameDescriptionMandatoryDefault valueType
descriptionProvides additional (human) readable information.no.string
typeAssignment of JSON-based data types that are compatible with JSON Schema (one of boolean, integer, number, string, object, array, or null).no.string
constProvides a constant value.no.anyType
enumRestricted set of values provided as array.yes.string

The class DataSchema has the following subclasses:

ArraySchema

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

Field NameDescriptionMandatoryDefault valueType
itemsUsed to define characteristics of an array.yes.DataSchema
minItemsDefines the minimum number of items that have to be in the array.no.unsignedInt
maxItemsDefines the maximum number of items that have to be in the array.no.unsignedInt

ObjectSchema

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

Field NameDescriptionMandatoryDefault valueType
propertiesData schema nested definitions.yes.DataSchema
requiredDefines which members of the object type are required/mandatory.no.string

BooleanSchema

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

NumberSchema

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

Field NameDescriptionMandatoryDefault valueType
minimumSpecifies a minimum numeric value. Only applicable for associated number or integer types.no.double
maximumSpecifies a maximum numeric value. Only applicable for associated number or integer types.no.double

The class NumberSchema has the following subclasses:

StringSchema

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

IntegerSchema

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

Field NameDescriptionMandatoryDefault valueType
minimumSpecifies a minimum numeric value. Only applicable for associated number or integer types.no.integer
maximumSpecifies a maximum numeric value. Only applicable for associated number or integer types.no.integer

Security Vocabulary Definition

The set of security metadata supported by the core TD vocabulary is still under discussion. For the core vocabulary the focus is on well-established security mechanisms, such as those built into protocols supported by WoT or already in wide use with those protocols. Note that the vocabulary extension mechanism of the WoT Thing Description allows for additional security schemes if needed. The current set of security schemes is partly based on OpenAPI 3.0.1. The security schemes, vocabulary and syntax given in this specification share many similarities with OpenAPI; however, it is not fully compatible. Also, as OpenAPI targets only web services built around HTTP it does not cover the full set of use cases required for the IoT. Therefore, we are currently discussing metadata supporting additional security mechanisms for IoT-centered protocols such as CoAP and MQTT. For more information about what security schemes are under discussion (and to file issues if you have a request) please visit the WoT Security TF repository.

SecurityScheme

An optional security configuration defines metadata for a security mechanism to allow access to one or more resources. More than one security configuration may be specified in which case they all need to be satisfied for access to be permitted. Security configurations can be given at the level of a Thing, an Interaction pattern, or a Form. In this case security configurations given at lower levels override security configurations given at higher levels. Additional security schemes can be used beyond those defined here if an appropriate external vocabulary is included in the context. See also Security and Privacy Considerations.

Field NameDescriptionMandatoryDefault valueType
schemeIdentification of security mechanism being configured (one of basic, digest, bearer, pop, oauth2, or apikey).yes.string
descriptionProvides additional (human) readable information.no.string
proxyUrlURI of the proxy server this security configuration provides access to. If not given, the corresponding security configuration is for the endpoint.no.anyURI

The class SecurityScheme has the following subclasses:

BasicSecurityScheme

Basic authentication security configuration ("scheme": "basic"). Unencrypted username and password. Should be used with some other security mechanism providing confidentiality, for example, TLS.

Field NameDescriptionMandatoryDefault valueType
inSpecifies location of security authentication information (one of header, query, body, or cookie).noheaderstring
pnameName for query, header, or cookie parameters.no.string

DigestSecurityScheme

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

Field NameDescriptionMandatoryDefault valueType
inSpecifies location of security authentication information (one of header, query, body, or cookie).noheaderstring
qopQuality of protection (one of auth or auth-int).noauthstring
pnameName 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 OAuth. If the oauth2 scheme is specified it is not generally necessary to specify this scheme as well as it is implied.

Field NameDescriptionMandatoryDefault valueType
authorizationUrlURI of the authorization server.no.anyURI
algEncoding, encryption, or digest algorithm (one of MD5, ES256, or ES512-256).noES256string
formatSpecifies format of security authentication information (one of jwt, jwe, or jws).nojwtstring
inSpecifies location of security authentication information (one of header, query, body, or cookie).noheaderstring
pnameName for query, header, or cookie parameters.no.string

PopSecurityScheme

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

Field NameDescriptionMandatoryDefault valueType
authorizationUrlURI of the authorization server.no.anyURI
algEncoding, encryption, or digest algorithm (one of MD5, ES256, or ES512-256).noES256string
formatSpecifies format of security authentication information (one of jwt, jwe, or jws).nojwtstring
inSpecifies location of security authentication information (one of header, query, body, or cookie).noheaderstring
pnameName for query, header, or cookie parameters.no.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 NameDescriptionMandatoryDefault valueType
inSpecifies location of security authentication information (one of header, query, body, or cookie).noquerystring
pnameName for query, header, or cookie parameters.no.string

OAuth2SecurityScheme

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

Field NameDescriptionMandatoryDefault valueType
tokenUrlURI of the token server.no.anyURI
authorizationUrlURI of the authorization server.no.anyURI
refreshUrlURI of the refresh server.no.anyURI
scopesArray of authorization scope identifiers.no.string
flowAuthorization flow (one of implicit, password, client, or code).noimplicitstring

Thing Description Serialization

This is the first draft that uses JSON-LD 1.1 as a serialization format of the Thing Description. The working assumption is based on the Community Draft of JSON-LD 1.1. There is the plan to setup a JSON-LD Working Group with the following JSON-LD Working Group Charter. It is planned that this section always conforms to the latest working assumptions of JSON-LD 1.1.

Thing Description instances are modeled and structured based on the Thing Description Information Model. This section proposes a TD serialization based on JSON-LD 1.1.

Representation Format

This section introduces the JSON-based serialization of the Thing Description that also follows the syntax of JSON-LD 1.1 to streamline the semantic evaluation of TDs.

Mainly, all vocabularies as defined in Vocabulary Definitions will have a JSON key representation.

In addition, Thing Description instances MAY contain JSON-LD 1.1 keys such as @context and @type.

The defined types of the vocabulary as defined in Vocabulary Definitions will be transformed to JSON-based types. The following rules are used for vocabularies based on simple type definitions:

All vocabularies in Vocabulary Definitions Section associated with complex-/class-based types are defined separately for structured JSON type transformation in the following subsections.

Thing as a whole

In the first line of the Thing Description instance MAY include the @context key from JSON-LD 1.1 with the value URI of the Thing description context file https://w3c.github.io/wot/w3c-wot-td-context.jsonld.

    {
      "@context": "https://w3c.github.io/wot/w3c-wot-td-context.jsonld",
      ...
    }
  

In the case the Thing Description instance is processed and interpret by a JSON-LD 1.1 processor this @context with its value MUST be present (also see Section JSON-LD 1.1 Processing).

In case a single Thing Description instance involves several contexts, additional namespaces with prefixes MUST be extended 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": ["https://w3c.github.io/wot/w3c-wot-td-context.jsonld",
                   {"sensor": "http://iotschema.org/"}],
      ...
    }
  

Each mandatory and required vocabulary, as defined in the class Thing, MUST be serialized as a JSON key at the top level of the Thing Description instance.

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

The type of the field links MUST be serialized as a JSON array.

An example of a TD snippet based on the defined fields of the Thing information model without the optional field @context is given below:

        {
          "name": "MyThing",
          "id": "urn:dev:wot:com:example:servient:myThing",
          "base": "https://servient.example.com/",
          "description": "Additional (human) readable information of the Thing.",
          "support": "https://servient.example.com/contact",
          "properties": {...},
          "actions": {...},
          "events": {...},
          "security": {...},
          "links": [...]
        }
   

In addition, the same example can also include the (semantic) keys of JSON-LD 1.1 (@context and @type):

        {
          "@context": "https://w3c.github.io/wot/w3c-wot-td-context.jsonld",
          "@type": "Thing",
          "name": "MyThing",
          "id": "urn:dev:wot:com:example:servient:myThing",
          "base": "https://servient.example.com/",
          "description": "Additional (human) readable information of the Thing.",
          "support": "https://servient.example.com/contact",
          "properties": {...},
          "actions": {...},
          "events": {...},
          "security": {...},
          "links": [...]
        }
   

properties

Properties (and sub-properties) offered by a Thing MUST be collected in the properties field of (unique) Property names as JSON keys. Each mandatory and required vocabulary, as defined in the class Property, MUST be serialized as a JSON key within a Property field.

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

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

An example of a TD snippet based on the defined fields is given below:

        {
          ...
          "properties": {
          	"on": {
          		"label": "On/Off",
          		"type": "boolean"
          	},
          	"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": [...]
          	}
          }
          ...
        }
   

Similar to the Thing level properties MAY have additional semantic anotations based on JSON-LD 1.1 keys.

In the case the Thing Description instance is processed and interpret by a JSON-LD 1.1 processor, each property MUST contain the vocabularies observable and writable due to the linked data's open-world assumption. That means, when a Thing Description instance is omitting these vocabularies, then the interpreter cannot make any assumptions about its actual value.

An example of a TD snippet including semantic annotations and the default values of observable and writable based on class Property definition:

        {
          ...
          "properties": {
          	"on": {
          		"@type": "iot:SwitchToggle",
          		"label": "On/Off",
          		"writable": false,
          		"observable": false,
          		"type": "boolean",
          		"forms": [...]
          	},
          	"status": {
          		"writable": false,
          		"observable": false,
          		"type": "object",
          		"properties": {
          			"brightness": {
          				"@type": "iot:CurrentLevel",
          				"type": "number",
          				"minimum": 0.0,
          				"maximum": 100.0
          			},
          			"rgb": {
          				"@type": "iot:rgbData",
          				"type": "array",
          				"items" : {
          					"type" : "number",
          					"minimum": 0,
          					"maximum": 255
          				},
          				"minItems": 3,
          				"maxItems": 3
          			}
          		},
          		"required": ["brightness","rgb"],
          		"forms": [...]
          	}
          }
          ...
        }
   

actions

Actions offered by a Thing are collected in the actions field of (unique) Action names as JSON keys. Each required vocabulary, as defined in the class Action, MUST serialized as a JSON key within a Action field.

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

The members keys of input and output rely on the the class Property. The forms field MUST NOT be serialized as a JSON object.

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

An example of a TD snippet based on the defined fields is given below:

        {
          ...
          "actions": {
            "fade" {
              "label": "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": [...]
            }
          ]
          ...
        }
      

Definitions within the actions level MAY have also additional semantic anotations based on JSON-LD 1.1 keys.

events

Events (and sub-events) offered by a Thing are collected in the events field of (unique) Event names as JSON keys. Each required vocabulary, as defined in the class Event, MUST transformed as a JSON key within a Event field.

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

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

An example of a TD snippet based on the defined fields is given below:

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

Definitions within the events level MAY have also additional semantic anotations based on JSON-LD 1.1 keys.

forms

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

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

In the case the Thing Description instance is processed and interpret by a JSON-LD 1.1 processor, each forms MUST contain the vocabulary mediaType due to the linked data's open-world assumption. That means, when a Thing Description instance is omitting this vocabulary, then the interpreter cannot make any assumptions about its actual value.

An example of a TD snippet based on the defined fields is given below:

        ...
        "forms": [
          {
            "href" : "http://mytemp.example.com:5683/temp",
            "mediaType": "application/json",
            "http:methodName": "POST",
            "rel": "writeProperty",
            "security": "basicConfig"
          }
        ]
        ...
      

security

This is the first draft containing the new security vocabularies. The definition is not yet completed and is still in progress.

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

The following TD snippet example shows a simple security configuration specifying basic authentication in the header. The value of in given is actually the default value.

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

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 is implied.

...
"security": [
  {
    "scheme": "digest",
    "proxyUrl": "https://portal.example.com/"
  },
  {
    "scheme": "bearer",
    "format": "jwt",
    "alg": "ES256",
    "authorizationUrl": "https://servient.example.com:8443/"
  }
]
      

Security definitions can be given at more than one level. In this case, definitions at the lower levels override the definitions at the higher level. In the following example, all interactions require basic authentication except for the overheating event, in which security has been overridden. Note especially the use of an empty array 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.

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

Security definitions can also can be given 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. It 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.

"properties": {
  "status": {
    ...
    "forms": [
      {
        "href": "https://mylamp.example.com/status",
        "mediaType": "application/json",
        "security": [{"scheme": "basic"}]
      },
      {
        "href": "https://mylamp.example.com/status",
        "mediaType": "application/json",
        "security": [{"scheme": "digest"}]
      },
      {
        "href": "coaps://mylamp.example.com:5683/status",
        "mediaType": "application/json",
        "security": [{"scheme": "apikey"}]
      }
    ]
  }
}
      

Media Type

The JSON-based serialization of the TD is identified by the Media Type application/td+json.

This media type has not registered with IANA yet.

Implementation Note

JSON Processing

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

To validate the semantic meaning and follow references to external context vocabularies (e.g., iot.schema.org), JSON-LD or RDF-based tools and libraries are highly recommended that are explained in the next sub-section.

JSON-LD 1.1 Processing

To interprete the semantic meaning with respect to RDF triples, a Thing Description instance requires a valid JSON-LD 1.1 representation based on this Thing Description specification before passing it to a JSON-LD 1.1 interpreter.

The following pre-processing steps of a Thing Description instance MUST be excecuted before starting JSON-LD 1.1 based processing:

  • There MUST be a @context key from JSON-LD 1.1 as defined in Section Thing as a whole.
  • External used vocabularies in the Thing Descriptions MUST provide their context URIs as prefix or within the @context.
  • All vocabularies that have a default value as defined Vocabulary Definition MUST be present at least with their default value.

The MyLampThing Example shows how such a pre-processing step may look like.

Example Thing Description Instances

MyLampThing

{
    "id": "urn:dev:wot:com:example:servient:lamp",
    "name": "MyLampThing",
    "description" : "MyLampThing uses JSON-LD 1.1 serialization",
    "properties": {
        "status": {
             "description" : "Shows the current status of the lamp",
             "type": "string",
             "forms": [{
                 "href": "coaps://mylamp.example.com:5683/status"
             }]
        }
    },
    "actions": {
     "toggle": {
        "description" : "Turn on or off the lamp.",
        "forms": [{
            "href": "coaps://mylamp.example.com:5683/toggle"
        }]}},
    "events": {
        "overheating": {
            "description" : "Lamp reaches a critical temperature (overheating).",
            "type": "string",
            "forms": [{
                "href": "coaps://mylamp.example.com:5683/oh"
            }]
        }}
}
   
{
    "@context": ["https://w3c.github.io/wot/w3c-wot-td-context.jsonld", 
    		{"iot": "http://iotschema.org/"}],
    "@type" : "Thing",
    "id": "urn:dev:wot:com:example:servient:lamp",
    "name": "MyLampThing",
    "description" : "MyLampThing uses JSON-LD 1.1 serialization",
    "properties": {
        "status": {
             "@type" : "iot:SwitchStatus",
             "description" : "Shows the current status of the lamp",
             "writable": false,
             "observable": false,
             "type": "string",
             "forms": [{
                 "href": "coaps://mylamp.example.com:5683/status",
                 "mediaType": "application/json"
             }]
        }
    },
    "actions": {
     "toggle": {
        "@type" : "iot:SwitchStatus",
        "description" : "Turn on or off the lamp.",
        "forms": [{
            "href": "coaps://mylamp.example.com:5683/toggle",
            "mediaType": "application/json"
        }]}},
    "events": {
        "overheating": {
            "@type" : "iot:TemperatureAlarm",
            "description" : "Lamp reaches a critical temperature (overheating).",
            "type": "string",
            "forms": [{
                "href": "coaps://mylamp.example.com:5683/oh",
                "mediaType": "application/json"
            }]
        }}
}
   

Security and Privacy Considerations

Please see the WoT Security and Privacy repository for work in progress regarding threat models, assets, risks, recommended mitigations, and best practices for security and privacy for systems using the Web of Things. Once complete, security and privacy considerations relevant to Thing Descriptions will be summarized in this section.

Recent Specification Changes

Changes from First Public Working Draft

Acknowledgements

This document contains a significant contribution from Web of Things members: ...