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, and 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 default serialisation of the TD is JSON-LD.

Example 1 shows a simple TD instance that describes a lamp Thing with the name MyLampThing.

  {
    "@context": ["http://w3c.github.io/wot/w3c-wot-td-context.jsonld"],
    "@type": ["Thing"],
    "name": "MyLampThing",
    "interaction": [
        {
            "@type": ["Property"],
            "name": "status",
            "outputData": {"type": "string"},
            "writable": false,
            "link": [{
                "href": "coaps://mylamp.example.com:5683/status",
                "mediaType": "application/json"
            }]
        },
        {
            "@type": ["Action"],
            "name": "toggle",
            "link": [{
                "href": "coaps://mylamp.example.com:5683/toggle",
                "mediaType": "application/json"
            }]
        },
        {
            "@type": ["Event"],
            "name": "overheating",
            "outputData": {"type": "string"},
            "link": [{
                "href": "coaps://mylamp.example.com:5683/oh",
                "mediaType": "application/json"
            }]
        }
    ]
  }
 

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 accessable over the CoAP protocol with a GET method (see CoAP protocol binding description in the W3C WoT protocol template deliverable [XXX]) at coaps://mylamp.example.com:5683/status (announced within the endoind (SP?) structure by the href key), which will return a string status value within a JSON structure (JSON as payload format is announced by the mediaType field).

Further explanation of the example.

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 TD is http://www.w3.org/ns/td#. TD itself defines a minimal set of classes and properties of its own. A full set of namespaces and prefixes used in this document is shown in the table below.

PrefixNamespace
tdhttp://www.w3.org/ns/td#
rdfhttp://www.w3.org/1999/02/22-rdf-syntax-ns#
rdfshttp://www.w3.org/2000/01/rdf-schema#
xsdhttp://www.w3.org/2001/XMLSchema#

ToDo: complete table

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.

In case of JSON-LD serializiation, a Thing Description instance in JSON-LD format complies with this specification if it follows the normative statements in Section 6. Serialization

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

Vocabulary Definition

Overview

The Thing Description relys on a small set of vocabulary. An overview of this vocabulary with its class context and class relation is given by the following figure.

TD core model figure
TD core model

A detailed description of the vocabulary is given in the next sub-section.

Classes

There is an information missing from the tables in subsequent sub-sections as to which vocabulary is optional or manditory. Since the information is already available in the ontology files, tools need to be updated to extract and utilize this information to generate the content of these tables.

Thing

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

Field NameDescriptionExpected value type
interactionLink from a Thing to the interaction patterns it providesInteractionPattern
securityLinks a given Thing to the security information that indicates the access metadata information for securely transmitting information via all the resources of the Thing.Security
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.anyURI
nameName of the Thing or interaction pattern (must be a valid keyword to be used in the scripting API)string

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

Field NameDescriptionExpected value type
linkIndicates the endpoints from which an interaction pattern is accessibleLink
nameName of the Thing or interaction pattern (must be a valid keyword to be used in the scripting API)string

The class InteractionPattern has the following subclasses:

Property

Property provides readable and/or writeable data that can be static (e.g., supported mode, rated output voltage, etc.) or dynamic (e.g., current fill level of water, minimum recorded temperature, etc.). Please note, this class also inherited all vocabulary from the InteractionPattern class.

Field NameDescriptionExpected value type
outputDatalink to the n-ary class that allows the declaration of the data type and unit of measure provided by an interaction pattern.DataSchema
writableBoolean value that indicates whether a property is writable (=true) or not (=false)boolean

Action

The Action interaction pattern triggers changes or processes on a Thing that take a certain time to complete (i.e., actions cannot be applied instantaneously like property writes). Examples include an LED fade in, moving a robot, brewing a cup of coffee, etc. Usually, ongoing Actions are modelled as Task resources, which are created when an Action invocation is received by the Thing. Please note, this class also inherited all vocabulary from the InteractionPattern class.

Field NameDescriptionExpected value type
outputDatalink to the n-ary class that allows the declaration of the data type and unit of measure provided by an interaction pattern.DataSchema
inputDatalink to the n-ary class that allows the declaration of the data type and unit of measure expected by an interaction pattern.DataSchema

Event

The Event interaction pattern enables a mechanism for events to be notified by a Thing on a certain condition (e.g., the fill level of the water tank reached a given threshold). Please note, this class also inherited all vocabulary from the InteractionPattern class.

Field NameDescriptionExpected value type
outputDatalink to the n-ary class that allows the declaration of the data type and unit of measure provided by an interaction pattern.DataSchema

DataSchema

This class embeds JSON Schema declaration in a Linked Data form to allow, e.g., the representation of pairs (data type, semantic meaning such as unit of measure) that are expected as input data or output data of a given interaction pattern.

Link

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

Field NameDescriptionExpected value type
hrefURI of the endpoint where an interaction pattern is providedanyURI
mediaTypeAssign underlying media type of the interaction pattern based on IANA (https://www.iana.org/assignments/media-types/media-types.xhtml)string

Security

The (optional) security field can be used to provide access metadata (self-contained) information of the Thing for securely transmitting information via all its resources. Also see Section Security Consideration. Definition taken from http://w3c.github.io/wot/current-practices/wot-practices#security

JSON-LD Serialization

Thing Description instances are modeled on the classes defined in , and they are serialized in JSON-LD by default, using the vocabulary defined there when they are served at run-time. JSON-LD is a serialization format that adds a semantic layer on top of the JSON specification: the terms that appear in a JSON document should be associated with uniquely identified concepts from shared vocabularies. This principle is part of a set of practices to publish data on the Web called Linked Data, where concepts are usually identified with URIs and originate from RDF vocabularies.

Thing as a Whole

The JSON-LD representation for a Thing Description is a JSON object of which fields are defined below.

Field Name JSON Construct Mandatory Description
@context array of strings yes The array MUST contain a string "https://w3c.github.io/wot/w3c-wot-td-context.jsonld". Also see below.
@type array of strings no Gives annotations to the Thing
name string yes Name of the Thing
base string no Base URI for use in a Thing Description
interaction array of objects no See
security array of objects no See

Each field in Thing class (see ) is represented by the namesake JSON field described in the above table.

The @context key is used to define Thing Description's context. All JSON key terms that are defined in the present document (also see Vocabulary Definition Section ) have been put in an external context document, available at https://www.w3.org/ns/td/w3c-wot-td-context.jsonld. Each Thing Description instance in JSON-LD MUST this context information enmbedded within an JSON array structure. Thus, a basic Thing Description would contain the following declaration:

    {
      "@context": ["https://www.w3.org/ns/td/w3c-wot-td-context.jsonld"],
      ...
    }
  

In case a single Thing Description instance involves several contexts, additional namespaces with prefixes can 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://www.w3.org/ns/td/w3c-wot-td-context.jsonld",
                   {"sensor": "http://example.org/sensors#"}],
      ...
    }
  

Note: Besides these pre-defined terms in the Thing Description context, additional characteristics can be added to Thing level such as product ID, firmware version, location, etc. These terms should then appear in the context of the Thing .

This note should be moved to the td-context-extension definition once we have a section for that. In there it should be also explained that a context is not necessary if you are working outside of the RDF model and if you handle a TD just as a simple JSON document.

A sample TD snippet that relies on the defined fields above is given below:

        {
          "@context": ["https://www.w3.org/ns/td/w3c-wot-td-context.jsonld"],
          "@type": ["Thing"],
          "name": "MyThing",
          "base": "coap://mything.example.com:5683/",
          "interaction": [
           ...
        }
   

Note:For examples of full Thing Description, see

Interaction Resources

An interaction in the context of the Web of Things is an exchange of data between a Web client and a Thing. This data can be either given as input by the client, returned as output by the Thing, or both. Three interaction patterns are defined: Property, Action, and Event.

Property

The Property interaction definitions (also see Property vocabulary definition section) provides metadata for readable and/or writeable data that can be static (e.g., supported mode, rated output voltage, etc.) or dynamic (e.g., current fill level of water, minimum recorded temperature, etc.). Shown below is an example of a Property interaction definition.

        {
          ...
          "interaction": [
            {
              "@type": ["Property"],
              "name": "temperature",
              "outputData":{ "type": "number" },
              "writable": false,
              "link": [{
                "href" : "coap://mytemp.example.com:5683/temp",
                "mediaType": "application/json"
              }]
            },
          ...
        }
      

The JSON-LD representation for a Property interaction definition is a JSON object of which the fields are defined below.

Field Name JSON Construct Mandatory Description
@type array of strings yes The array MUST start with a string "Property"
name string yes Name of the Property
outputData object yes See
writable boolean no a property is writable (=true) or not (=false)
link array of objects no See

Each field in Property class (see ) is represented by the namesake JSON field described in the above table.

Action

The Action interaction pattern (also see Action vocabulary definition section) targets changes or processes on a Thing that take a certain time to complete (i.e., actions cannot be applied instantaneously like property writes). Examples include an LED fade in, moving a robot, brewing a cup of coffee, etc. Usually, ongoing Actions are modeled as Task resources, which are created when an Action invocation is received by the Thing.

        {
          ...
          "interaction": [
            {
              "@type": ["Action"],
              "name": "fadeIn",
              "inputData": { "type": "integer" },
              "link": [{
              	"href" : "coap://mytemp.example.com:5683/in",
              	"mediaType": "application/json"
              }]
            }
          ]
          ...
        }
      

JSON-LD representation for an Action interaction definition is a JSON object of which the fields are defined below.

Field Name JSON Construct Mandatory Description
@type array of strings yes The array MUST start with a string "Action"
name string yes Name of the Action
outputData object no See
inputData object no See
link array of objects no See

Each field in Action class (see ) is represented by the namesake JSON field described in the above table.

Event

The Event interaction pattern (also see Event vocabulary definition section) enables a mechanism to be notified by a Thing on a certain condition. While some protocols such as CoAP can provide such a mechanism natively, others do not. Furthermore, Events might need a specific configuration that requires data sent and stored on the Thing in a standard way. There are are four mandatory terms defined within the Event pattern:


        {
          ...
          "interaction": [
            {
              "@type": ["Event"],
              "name": "criticalCondition",
              "outputData":  { "type": "string" },
              "link": [{
              	"href" : "coap://mytemp.example.com:5683/ev",
              	"mediaType": "application/json"
              }]
            }
          ]
          ...
        }
      

The JSON-LD representation for an Event interaction definition is a JSON object of which the fields are defined below.

Field Name JSON Construct Mandatory Description
@type array of strings yes The array MUST start with a string "Event"
name string yes Name of the Event
outputData object yes See
link array of objects no See

Each field in Event class (see ) is represented by the namesake JSON field described in the above table.

This section describes JSON-LD serialization for the instances of the class. Shown below is an example of a link definition.

        "link": [
          {
            "href" : "coap://mytemp.example.com:5683/temp",
            "mediaType": "application/json"
          }
        ]
      

JSON-LD representation for a link definition is a JSON array with name "link". Each item in the array is a JSON object that consists of two JSON fields as summarized below.

Field Name JSON Construct Mandatory Description
href string yes URI. If a relative URI is given then this URI is relative to base URI.
mediaType string yes Media type based on IANA

Each field in Link class (see ) is represented by the namesake JSON field described in the above table.

Security

Shown below is an example of a security resource definition.

  {
    ...
    "security": {
      "cat": "token:jwt", 
      "alg":"HS256", 
      "as":"https://authority-issuing.org"
    },
    ...
  }

In the above example, a JSON Web Token (JWT) type is assigned (cat), along with a corresponding hashing algorithm "HS256" (alg) and the issuing authority of the security token (as).

Consider the need for a context definition for the above example.

Type System

All of the three interaction types Property, Action, and Event can specify the type of the value acceptable as an input or expected as an output of the interaction. In this section, we define an abstract type system notation based on JSON-LD for describing the structure and datatypes for values of interaction types. While type system is designed to be compatible with JSON schema [[draft-zyp-json-schema-04]] [[draft-fge-json-schema-validation-00]], it is intended to be encoding-neutral and integrates into the Linked Data vocabularies to allow semantic annotations. It can not only be directly translated into JSON schema, but also can be handily translated into XML Schema. Use of JSON-LD equips the type system with a way to associate data elements with citations and semantic concepts defined elsewhere.

For Property and Event interaction types, each property or event can specify its value type using outputData field within respective interaction type definition. In the following example, temperature property and criticalCondition event are defined as number and string, respectively.

      {
        ...
        "interaction": [
          ...
          {
            "@type": ["Property"],
            "name": "temperature",
            "outputData": { "type": "number" },
            ...
          }
          ...
          {
            "@type": ["Event"],
            "name": "criticalCondition",
            "outputData": { "type": "string" },
            ...
          }
          ...
        ]
        ...
      }
    

Similarly, for Action interaction type, each action can specify its input and/or output value type using inputData and outputData field, respectively. The following is an example value type definition for an action. In the example, fadeIn action is defined to have inputData of type number and outputData of type boolean.

      {
        ...
        "interaction": [
          ...
          {
            "@type": ["Action"],
            "name": "fadeIn",
            "inputData": {
              "type": "number",
              "actuator:unit": "actuator:ms"
            },
            "outputData": {
              "type": "boolean"
            },
            ...
          }
          ...
        ]
        ...
      }
    

Within inputData and outputData fields, type system allows the following definitions in the type field:

These type constructs are in parallel to those that are available in JSON schema. Therefore, serialization of data exchanged between servients is straightforward when it is in JSON format.

Simple Data

Consider the following inputData definition which defines the value to be an integer within the value range of [ 0 ... 255 ].

        "inputData": { 
          "type": "integer",
          "minimum": 0,
          "maximum": 255,
        }
      

When the integer being exchanged is 184, data serialization in JSON format will look like the following:

        184
      

The snippet in the above example is a valid JSON document according to the syntax defined in [[!RFC7159]], which allows sending simple types in the root of the document. There is no need for wrapping a single value into an object.

The same data (i.e. a number equal to 184) will look like the following when the data is exchanged in XML.

      		<integer>184</integer>
      

Structured Data

In the previous section, we used an example inputData definition consisting of a single integer.

With the type system, it is also possible to define value types that have more than one literal value. The type system provides two distinct constructs to define a structure that can have multiple literal values. One is the object, and the other is the array.

Object

The following is an example inputData definition that defines the value to be an object consisting of two named literals id (of type integer) and name (of type string) where id is required to be present.

          "inputData": {
              "type": "object",
              "fields": [
                  {
                      "name": "id",
                      "value": {
                        "type": "integer"
                      }
                  },
                  {
                      "name": "name",
                      "value": {
                        "type": "string"
                      }
                  }
              ],
              "required": ["id"]
          }
        

When the id number and the name string values being exchanged are 1314520 and "Web of Things", data serialization in JSON format will look like the following.

          {
            "id": 1314520,
            "name": "Web of Things"
          }
        

The above data will look the following when the data is exchanged in XML.

            <object>
              <id>
                <integer>1314520</integer>
              </id>
              <name>
                <string>Web of Things</string>
              </name>
            </object>
        

In both JSON and XML serialization, values can appear in any order regardless of the order used in the fields definition of the object.

Array

The following is an example valueType definition that defines the value to be an array that consists of exactly three number literals with each value within the range of [ 0 ... 2047 ].

          "inputData": {
              "type": "array",
              "items": {
                  "type" : "number",
                  "minimum": 0,
                  "maximum": 2047
              },
              "minItems" : 3,
              "maxItems" : 3
          }
        

When the numbers being exchanged are 520, 184 and 1314, data serialization in JSON format will look like the following.

          [
            520,
            184,
            1314
          ]
        

The above data will look the following when the data is exchanged in XML.

            <array>
              <number>520</number>
              <number>184</number>
              <number>1314</number>
            </array>
        

Mapping to XML Schema

In the previous section, examples showed what data whose value type is described using the type system look like when serialized to XML in parallel to corresponding JSON serializations.

This section describes how type definitions described using the type system can be mapped to XML schema definitions by using the same examples. Given these type definitions, providing the mapping to XML schema allows XML tools to directly validate serialized XML data, for example. The XML structure for which this mapping is designed is based on EXI4JSON [[exi-for-json]].

Object Definition to XML Schema

Shown below is the type system object definition given for the inputData in Section Object. The object consists of two named literals id (of type integer) and name (of type string) where id is required to be present.

        {
            "type": "object",
            "fields": [
                {
                    "name": "id",
                    "value": {
                      "type": "integer"
                    }
                },
                {
                    "name": "name",
                    "value": {
                      "type": "string"
                    }
                }
            ],
            "required": ["id"]
        }
      

When the object is anonymous (i.e. it is the root, or participates in an array definition), the above object definition transforms to the following XML Schema element definition.

        <xs:element name="object" xmlns:xs="http://www.w3.org/2001/XMLSchema">
            <xs:complexType>
                <xs:all>
                    <xs:element name="id">
                        <xs:complexType>
                          <xs:sequence>
                            <xs:element name="integer" type="xs:integer" />
                          </xs:sequence>
                        </xs:complexType>
                    </xs:element>
                    <xs:element name="name" minOccurs="0">
                        <xs:complexType>
                          <xs:sequence>
                            <xs:element name="string" type="xs:string" />
                          </xs:sequence>
                        </xs:complexType>
                    </xs:element>
                </xs:all>
            </xs:complexType>
        </xs:element>
        

Otherwise (i.e. the object is a member of another object definition, thus has a name), the object definition transforms to the following XML schema element definition. Note $name represents the name of the object, and needs to be replaced by the actual name of the object.

          <xs:element name="$name" xmlns:xs="http://www.w3.org/2001/XMLSchema">
              <xs:complexType>
                  <xs:sequence>
                      <xs:element name="object">
                          <xs:complexType>
                              <xs:all>
                                  <xs:element name="id">
                                      <xs:complexType>
                                        <xs:sequence>
                                          <xs:element name="integer" type="xs:integer" />
                                        </xs:sequence>
                                      </xs:complexType>
                                  </xs:element>
                                  <xs:element name="name" minOccurs="0">
                                      <xs:complexType>
                                        <xs:sequence>
                                          <xs:element name="string" type="xs:string" />
                                        </xs:sequence>
                                      </xs:complexType>
                                  </xs:element>
                              </xs:all>
                          </xs:complexType>
                      </xs:element>
                  </xs:sequence>
              </xs:complexType>
          </xs:element>
        
Array Definition to XML Schema

Shown below is the type system array definition given for the inputData in Section Array. The array consists of exactly three number literals with each value within the value range of [ 0 ... 2047 ].

          {
              "type": "array",
              "items": {
                  "type" : "number",
                  "minimum": 0,
                  "maximum": 2047
              },
              "minItems" : 3,
              "maxItems" : 3
          }
        

When the array is anonymous (i.e. it is the root, or participates in another array definition), the above array definition transforms to the following XML Schema element definition.

          <xs:element name="array" xmlns:xs="http://www.w3.org/2001/XMLSchema">
              <xs:complexType>
                  <xs:sequence>
                      <xs:element name="double" minOccurs="3" maxOccurs="3">
                          <xs:simpleType name="minInclusive">
                              <xs:restriction base="xs:double">
                                  <xs:minInclusive value="0"/>
                                  <xs:maxInclusive value="2047"/>
                              </xs:restriction>
                          </xs:simpleType>
                      </xs:element>
                  </xs:sequence>
              </xs:complexType>
          </xs:element>
        

Otherwise (i.e. the array is a member of an object definition, thus has a name), the array definition transforms to the following XML schema element definition. Note $name represents the name of the array, and needs to be replaced by the actual name of the array.

          <xs:element name="$name" xmlns:xs="http://www.w3.org/2001/XMLSchema">
              <xs:complexType>
                  <xs:sequence>
                      <xs:element name="array">
                          <xs:complexType>
                              <xs:sequence>
                                  <xs:element name="double" minOccurs="3" maxOccurs="3" >
                                      <xs:simpleType name="minInclusive">
                                          <xs:restriction base="xs:double">
                                              <xs:minInclusive value="0"/>
                                              <xs:maxInclusive value="2047"/>
                                          </xs:restriction>
                                      </xs:simpleType>
                                  </xs:element>
                              </xs:sequence>
                          </xs:complexType>
                      </xs:element>
                  </xs:sequence>
              </xs:complexType>
          </xs:element>
        

Parsing

To parse a valid Thing Description a simple JSON-based parser and tools can be used to retrieve the content. To validate and follow references to external context vocabulary, JSON-LD or RDF-based parsing tools and libraries are highly recommended.

Examples

In the following, we give examples of full TDs. The first one, a temperature sensor, shows how to define relations between Thing Properties. As a second example, we modeled an actuator (LED lamp) where Actions have all been characterized semantically, so that machines could unambiguously interpret them in an automated manner. At last, association between Things is shown by defining a master switch controlling other LED lamps.

Temperature Sensor

        {
          "@context": ["https://w3c.github.io/wot/w3c-wot-td-context.jsonld",
                       "https://w3c.github.io/wot/w3c-wot-common-context.jsonld"],
          "@type": ["Sensor"],
          "name": "myTempSensor",
          "base" : "coap:///www.example.com:5683/temp/",
          "interaction": [
            {
              "@id": "val",
              "@type": ["Property","Temperature"],
              "unit": "celsius",
              "reference": "threshold",
              "name": "myTemp",
              "outputData": { "type": "number" },
              "writable": false,
              "link": [{
              	"href" : "val",
              	"mediaType": "application/json"
              }]
            }, 
            {
              "@id": "threshold",
              "@type": ["Property","Temperature"],
              "unit": "celsius",
              "name": "myThreshold",
              "outputData": { "type": "number" },
              "writable": true,
             	"link": [{
              	"href" : "thr",
              	"mediaType": "application/json"
              }]
            },
            {
              "@type": ["Event"],
              "outputData": { "type": "number" },
              "name": "myChange",
              "property": "temp",
              "link": [{
              	"href" : "val/changed",
              	"mediaType": "application/json"
              }]
            }, 
            {
              "@type": ["Event"],
              "outputData":  { "type": "number" },
              "name": "myWarning",
              "link": [{
              	"href" : "val/high",
              	"mediaType": "application/json"
              }]
            }
          ]
        }
      

The Thing myTempSensor defines two Properties: myTemp and myThreshold. Both are defined as temperatures, with the same unit (celsius). A client that is able to parse a TD only needs to know the predicate reference to understand that the threshold acts as a reference value for myTemp while the latter is the actual value measured by the temperature sensor. Here, reference points to http://schema.org/valueReference.

Moreover, one of the Events of the Thing is linked to the measured value (with the predicate property). It means in that context that an event should be triggered each time myTemp changes. The other Event does not define further semantics. It could be used either in a closed system (where clients are aware of its meaning) or by a human but an external agent would not have sufficient information to interpret it.

LED Master Switch

        {
          "@context": ["https://w3c.github.io/wot/w3c-wot-td-context.jsonld",
                       "https://w3c.github.io/wot/w3c-wot-common-context.jsonld"],
          "@type": ["Lamp"],
          "name": "myMasterLED",
          "interaction": [
            {
              "@type": ["Action", "Toggle"],
              "name": "myMasterOnOff",
              "inputData": {
                "@type": "OnOff",
                "type": "boolean"
              },
              "link": [
                {
                  "href" : "coap://www.example.com:5683/master",
                  "mediaType": "application/json"
                },
                {
                  "href" : "http://www.example.com:80/master",
                  "mediaType": "application/json"
                }
              ]
            }
          ]
        }
      

In this last example, it would be good to illustrate the use of associations. The Thing we modeled here acts as a master switch for eight lamps similar to that of . This means switching on and off myMasterOnOff will propagate to all associated Things by toggling their Action that is also of type Toggle. No precise semantics for associations have been defined yet and there might exist many other kinds of dependency between Things than simply parent/child relations. This issue will be addressed soon. Until then, Thing associations could be useful for discovery.

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.

Acknowledgements

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