Each Thing is described by a WoT Thing Description (TD). The TD must be acquired to use and interact with the Thing, since it describes the semantics of a Thing as well as its WoT Interface. Usually, Things directly provide their own TD, but the TD can also be hosted externally if there is not enough space on the device or when a WoT-compatible legacy device is retrofitted with a TD.

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.

Introduction

The WoT Thing Description (TD) provides the semantic metadata of a Thing as well as a functional description of its WoT Interface. For this, it relies on the Resource Description Framework (RDF) [[!rdf11-concepts]] as an underlying data model. For now, [[!JSON-LD]] is used as the default TD serialization format. The WoT IG defined a minimal vocabulary to express the capabilities of a Thing in terms of different interaction patterns: Properties, Actions, and Events. In addition, the TD provides metadata for the different communication bindings (e.g., HTTP, CoAP, etc.), mediaTypes (e.g., "application/json", "application/exi", etc.), and security policies (authentication, authorization, etc.). gives an overview of the relevant content defined in a TD.

Concepts of the Thing Description (TD)

Quick Start: TD Samples

This section gives a brief introduction to the TD as JSON-LD samples.

In the following, we introduce three minimal TD samples to show the prospects of the W3C Thing Descriptions. Example 1 shows a simple TD that describes a temperature Thing with the name MyTemperatureThing.

            {
              "@context": ["http://w3c.github.io/wot/w3c-wot-td-context.jsonld"],
              "@type": "Thing",
              "name": "MyTemperatureThing",
              "interactions": [
                {
                  "@type": ["Property"],
                  "name": "temperature",
                  "outputData": {"valueType": { "type": "number" }},
                  "writable": false,
                  "links": [{
                    "href" : "coap://mytemp.example.com:5683/temp",
                    "mediaType": "application/json"
                    }]
                }
              ]
            }
    

Based on this content, we know there exists one Property interaction resource with the name temperature. In addition, information is provided such as that this Property is accessable over the CoAP protocol with a GET method (see CoAP protocol binding here) at coap://mytemp.example.com:5683/temp (announced within the endoind structure by the href kye), which will return a number (TD type system) inside a JSON structure (JSON as payload format is announced by the mediaType field).

In practice, a Thing provides further details about what kind of Thing it is and what the interactions mean. This additional information is the semantic context of the Thing. JSON-LD provides a means to extend a TD with an external (semantic) context, which allows to reuse existing models, thereby enhancing semantic interoperability. Through a context, the meaningless strings turn into semantically defined terms that are part of a linkable vocabulary. Example 2 shows the integration of the sensor namespace and the resulting semantic enrichment of the temperature Property with an additional entry within the @type and unit assignment.

{
"@context": ["http://w3c.github.io/wot/w3c-wot-td-context.jsonld",
       { "sensor": "http://example.org/sensors#" }
      ],
  "@type": "Thing",
  "name": "MyTemperatureThing",
  "interactions": [
    {
      "@type": ["Property",
"sensor:Temperature"
], "name": "temperature",
"sensor:unit": "sensor:Celsius",
"outputData": {"valueType": { "type": "number" }}, "writable": false, "links": [{ "href" : "coap://mytemp.example.com:5683/", "mediaType": "application/json" }] } ] }

Example 3 shows a more advanced TD reflecting an LED Thing that supports multiple protocols (CoAP and HTTP), mediaTypes (JSON and EXI), and security policies (it requires a JWT for interaction). This example also shows the definition of the endpoint information in a global manner. More precisely, a global defined base URI is valid for defined interaction resources. Indivdualiziation of the URI's resource is done by the href key within the interaction definitions.

{
  "@context": [
    "http://w3c.github.io/wot/w3c-wot-td-context.jsonld",
    { "actuator": "http://example.org/actuator#" }
  ],
  "@type": "Thing",
  "name": "MyLEDThing",
  "base": "coap://myled.example.com:5683/",
  "security": {
      "cat": "token:jwt",
      "alg": "HS256",
      "as": "https://authority-issuing.example.org"
    },
  "interactions": [
    {
      "@type": ["Property","actuator:onOffStatus"],
      "name": "status",
      "outputData": {"valueType": { "type": "boolean" }},
      "writable": true,
      "links": [{
        "href" : "pwr", 
        "mediaType": "application/exi" 
      },
      {
        "href" : "http://mytemp.example.com:8080/status",
        "mediaType": "application/json"
      }]
    },
    {
      "@type": ["Action","actuator:fadeIn"],
      "name": "fadeIn",
      "inputData": {
        "valueType": { "type": "integer" },
        "actuator:unit": "actuator:ms"
      },
      "links": [{
        "href" : "in", 
        "mediaType": "application/exi" 
      },
      {
        "href" : "http://mytemp.example.com:8080/in",
        "mediaType": "application/json"
      }]                  
    },
    {
      "@type": ["Action","actuator:fadeOut"],
      "name": "fadeOut",
      "inputData": {
        "valueType": { "type": "integer" },
        "actuator:unit": "actuator:ms"
      },
      "links": [{
        "href" : "out", 
        "mediaType": "application/exi" 
      },
      {
        "href" : "http://mytemp.example.com:8080/out",
        "mediaType": "application/json"
      }]                  
    },
    {
      "@type": ["Event","actuator:alert"],
      "name": "criticalCondition",
      "outputData": {"valueType": { "type": "string" }},
      "links": [{
              "href" : "ev",
              "mediaType": "application/exi"
            }]  
    }
  ]
}
    

Based on this TD, one is able to know that a JSON Web Token (JWT) is required to interact with the resources of the Thing. They are issued by https://authority-issuing.example.org and signed using HMAC SHA-256 (HS256). The status of the Thing can be requested using a CoAP GET on coap://myled.example.com:5683/pwr (base URI from the global scope endpoint definition plus the href) or an HTTP GET on http://mything.example.com:8080/myled/status. It can also modified using a PUT on the respective URIs, since Property is writable. The Actions can be invoked through a POST to the resources fadeIn (/in for CoAP and /myled/in for HTTP) and fadeOut (/out for CoAP and /myled/out for HTTP) with an integer value in milliseconds serialized as JSON or EXI. Please note, all this protocol binding assumptions are explained here. MyLEDThing also serves for the CoAP protocol an Event called criticalCondition, which enables clients to be informed about problems (enabled by the CoAP GET with the Observe option to coap://myled.example.com:5683/ev). This event sample also shows the local scope definition of the endpoint which overwrite global defined endpoint information. Such a mechanism allows to restrict or expand endpoint oppertunities of indivdual interaction resources.

Semantic Metadata

TD Context

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.

The association between terms and concept URIs has to be declared in preamble of the JSON document with the keyword @context. The expected value for @context can be of different kinds. A first option is to use a JSON object where keys are terms and values are concepts URIs, e.g.:

    {
      "@context": {
        "name": "https://w3c.github.io/wot/w3c-wot-td-ontology.owl#name",
        "base": "https://w3c.github.io/wot/w3c-wot-td-ontology.owl#associatedUri",
        "unit": "http://purl.oclc.org/NET/ssnx/qu/qu-rec20#unit",
        "Thing": "https://w3c.github.io/wot/w3c-wot-td-ontology.owl#Thing",
        ...
      }
    }
  
It is also possible to declare namespaces in the context instead of terms. In the example above, three of the four URIs have the same prefix: http://www.w3c.org/wot/td#. This common part could be given a short name, refered to as a namespace (as in XML). URIs could then be shortened by concatenating namespace with : and a local name (anywhere in the JSON-LD document). E.g.:
    {
      "@context": {
        "wot": "https://w3c.github.io/wot/w3c-wot-td-ontology.owl#",
        "name": "wot:name",
        "base": "wot:associatedUri",
        "unit": "http://purl.oclc.org/NET/ssnx/qu/qu-rec20#unit",
        "Thing": "wot:Thing",
        ...
      }
    }
  

For the sake of reusability, it is also possible to define an external JSON-LD context and simply give its URI as value of @context. All JSON terms that are defined in the present document have been put in an external document, available at http://w3c.github.io/wot/w3c-wot-td-context.jsonld. It is highly recommended (but not mandatory) to include this standard context in a Thing Description. A basic Thing Description would contain the following declaration:

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

A third option is to declare an array, in case a single document involves several contexts. Array elements are either objects or strings, as explained above. This option proves relevant if one wants to extend the existing TD context without modifying it. For instance:

    {
      "@context": ["http://w3c.github.io/wot/w3c-wot-td-context.jsonld",
                   {"sensor": "http://example.org/sensors#"}],
      ...
    }
  
Section provides a more concrete example on that topic.

Security

  {
    ...
    "security": {"cat":"token:jwt", "alg":"HS256", "as":"https://authority-issuing.org"},
    ...
  }
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 .

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

Thing Metadata

A TD will provide some generic metadata vocabularies that can be used, e.g., to assign a name or what kind of protocols does a servient support.

        {
          ...
          "name": "MyLED",
          "base": "coap://myled.example.com:5683/"
          ...
        }
      

There are three mandatory and one optional (shown as italic text in JSON snippet) vocabulary terms defined within metadata:

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

Interaction Patterns

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 have been defined so far: Property, Action and Event.

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

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

There are four mandatory and three optional (italic in JSON sample) terms defined for the Property pattern:

Absolute URIs in hrefs or endoint can point to an external resource that is not hosted on the Thing directly. This can be useful to link data into the context of the Thing, for which there is not enough space in the device itself. Absolute URIs could also point to a proxy or gateway that allows access to legacy systems that might belong to a Thing that does not have the capability to translate by itself (but provides other, WoT-compatible resources). This mechanism is also interesting for virtual Things that combine the services of multiple other Things (e.g., a room lighting servient that has Properties for each individual light, while these linked Properties are hosted directly on those lights).

If the property is writable (writable=true), then the Property accepts the same format(s) as input as described for its output.

The stability field provides a hint for caching and polling. This value should also be included in the cache control information of protocols, e.g., the Cache-Control header field of HTTP or Max-Age option of CoAP.

Action

The Action interaction pattern 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 modelled as Task resources, which are created when an Action invocation is received by the Thing.

        {
          ...
          "interactions": [
            {
              "@type": ["Action", "actuator:fadeIn"],
              "name": "fadeIn",
              "inputData": {
                "valueType": { "type": "integer" },
                "actuator:unit": "actuator:ms"
              },
              "links": [{
                "href" : "coap://mytemp.example.com:5683/in",
                "mediaType": "application/json"
              }]
            }
          ]
          ...
        }
      

There are one mandatory and four optional terms defined within the Action type:

The hypertext reference (href) field works similar to Properties.

Usually, invoking an Action results in a response that indicates a new (sub-)resource, where the started Task can be monitored and also controlled: Updating this Task resource may allow for modification of the process (e.g., when it is still queued and not started yet, but also during runtime if the process supports that). Deleting this Task resource may allow for cancellation of the Action execution. Once the Task completes, the (sub-)resource may be removed by the server; or it is marked as completed, but kept for traceability. It is also possible that calling an action produces a so-called action result that is not manifested in any temporary resource nor other changes to the server (e.g., a conversion process or dry run).

Event

The Event interaction pattern 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 two mandatory and two optional terms defined within the Event pattern:

        {
          ...
          "interactions": [
            {
              "@type": ["Event", "actuator:alert"],
              "name": "criticalCondition",
              "outputData": {"valueType": { "type": "string" }},
              "links": [{
                "href" : "coap://mytemp.example.com:5683/ev",
                "mediaType": "application/json"
              }]
            }
          ]
          ...
        }
      

So far, the concept of events has not been evaluated yet during the PlugFests. Thus, there has been little discussion and no common practice has emerged. The following text is a proposal to trigger discussion.

The interaction with Events works similar to Actions with the difference that no side effects are intended on the Thing. A client issues a request to the URI of an Event, which may include a payload that represents the configuration data for the Event mechanism. Upon reception, the Thing creates a (sub-)resource, which serves as a handle for the Event subscription. It can be monitored to receive notifications: an HTTP client would need to poll this resource, while a CoAP client would simply observe it. Technically, multiple clients could use the subscription resource created by another client when they are interested in the same Event configuration. The Event configuration can also be updated and ultimatively deleted to clean up internal notification hooks.

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. JSON schema [[!draft-zyp-json-schema-04]] [[!draft-fge-json-schema-validation-00]] provides a standard way to describe the structure and datatypes of data, and we use JSON schema as the notation for value types of the interaction types.

Note: In the embodiment of type system described in this section, JSON schema is used as an abstract description system for structured data. JSON schema is something that is already out there being used and well-known, therefore gives us a chance to get started quickly to experiment with type system idea for further contemplation. Through discussion, the following points have been noted as feedback for improvements.

Note that there is an idea (Proposal for the type system for Things) that was incubated independently and was put forward to the IG for consideration.

For Property and Event interaction types, each property or event can specify its value type using valueType with JSON schema definition as its content. The following is an example value type definition. In the example, temperature property and criticalCondition event are defined as number and string, respectively.

      {
        ...
        "properties": [
          {
            ...
            "name": "temperature",
            "valueType": { "type": "number" },
            ...
          }
        ]
        ...
        "events": [
          {
            ...
            "name": "criticalCondition",
            "valueType": { "type": "string" },
            ...
          }
        ]
        ...
      }
    

Similarly, for Action interaction type, each action can specify its input and/or output value type using valueType with JSON schema definition as its content. 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.

      {
        ...
        "actions": [
          {
            ...
            "name": "fadeIn",
            "inputData": {
              "valueType": { "type": "number" },
              "actuator:unit": "actuator:ms"
            },
            "outputData": {
              "valueType": { "type": "boolean" },
            },
            ...
          }
        ]
        ...
      }
    

Simple Data

With value types described by means of JSON schema, serialization of data exchanged between servients is straightforward when it is in JSON format.

Consider the following valueType definition which defines the value to be a number within the value range of [ 0 ... 255 ].

        "valueType": { 
          "type": "number",
          "minimum": 0,
          "maximum": 255,
        }
      

When the number being exchanged is 123, data serialization in JSON format will look like the following.

        { "value": 123 }
      

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

          <number>123</number>
      

At the time of this writing, some JSON parsers and serializers seem to have problems with value-only literals. Also, whether a single literal such as "hello" is itself a valid JSON instance depends on the JSON specification (RFC vs. ECMA). Therefore, wrapping the value with a top-level object seems to be prudent.

Structured Data

In the previous section, we used an example valueType definition consisting of a single number.

Since we are using JSON schema to describe valueType, it is also possible to define value types that have more than one literal value. JSON provides two distinct constructs to define a structure that can have multiple literal values. One is JSON object, and the other is JSON array.

JSON Object

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

          "valueType": {
              "type": "object",
              "properties": {
                  "id": {
                      "type": "integer"
                  },
                  "name": {
                      "type": "string"
                  }
              },
              "required": ["id"]
          }
        

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

          {
            "value": {
              "id": 12345,
              "name": "Web of Things"
            }
          }
        

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

            <object>
              <id>
                <number>12345</number>
              </id>
              <name>
                <string>Web of Things</string>
              </name>
            </object>
        

Using the TD model and JSON Schema in a single document may lead to a name conflict: properties is used both to declare Properties of the Thing and expected keys in a JSON object. Depending on the use case, if a serialization of the Thing Description in RDF is required, the valueType definition should be processed with an additional JSON-LD context that overrides the mapping for properties (see [[!JSON-LD]], Advanced Context Usage).

JSON 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 ... 255 ].

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

When the numbers being exchanged are 208, 32 and 144, data serialization in JSON format will look like the following.

          {
            "value": [
              208,
              32,
              144
            ]
          }
        

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

            <array>
              <number>208</number>
              <number>32</number>
              <number>144</number>
            </array>
        

Mapping to XML Schema

In the previous section, examples showed what those data whose valueType are described using JSON schema look like when serialized to XML in parallel to corresponding JSON serializations.

This section describes how JSON schema definitions can be mapped to XML schema definitions by using the same examples. Given JSON schema definitions, providing the mapping to XML schema allows XML tools to directly validate serialized XML data, for example.

The XML structure is based on EXI4JSON [[!exi-for-json]]. The structure works uniformly well for both schema-less and schema-informed use cases.

A complete "JSON Schema" to "XML Schema" mapping needs to be defined.

JSON Object Definition to XML Schema

Shown below is the JSON schema object definition used as the valueType in Section JSON 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",
            "properties": {
                "id": {
                    "type": "integer"
                },
                "name": {
                    "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>
        

JSON schema object does NOT define any order. Therefore, in order to capture the constraints of JSON schema object, we need to use xsd:all constructs instead of xsd:sequence.

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 should 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>
        
JSON Array Definition to XML Schema

Shown below is the JSON schema array definition used as the valueType in Section JSON Array. The array consists of exactly three number literals with each value within the value range of [ 0 ... 255 ].

          {
              "type": "array",
              "items": {
                  "type" : "number"
                  "minimum": 0,
                  "maximum": 255,
              },
              "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="255"/>
                              </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 should 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="255"/>
                                          </xs:restriction>
                                      </xs:simpleType>
                                  </xs:element>
                              </xs:sequence>
                          </xs:complexType>
                      </xs:element>
                  </xs:sequence>
              </xs:complexType>
          </xs:element>
        

TD Examples

In the following, we give three examples of a full TD. 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/",
          "interactions": [
            {
              "@id": "val",
              "@type": ["Property","Temperature"],
              "unit": "celsius",
              "reference": "threshold",
              "name": "myTemp",
              "outputData": {"valueType": { "type": "number" }},
              "writable": false,
              "links": [{
                "href" : "val",
                "mediaType": "application/json"
              }]
            }, {
              "@id": "threshold",
              "@type": ["Property","Temperature"],
              "unit": "celsius",
              "name": "myThreshold",
              "outputData": {"valueType": { "type": "number" }},
              "writable": true,
               "links": [{
                "href" : "thr",
                "mediaType": "application/json"
              }]
            },
            {
              "@type": ["Event"],
              "outputData": {"valueType": { "type": "number" }},
              "name": "myChange",
              "property": "temp",
              "links": [{
                "href" : "val/changed",
                "mediaType": "application/json"
              }]
            }, {
              "@type": ["Event"],
              "outputData": {"valueType": { "type": "number" }},
              "name": "myWarning",
              "links": [{
                "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",
          "interactions": [
            {
              "@type": ["Actions", "Toggle"],
              "name": "myMasterOnOff",
              "inputData": {
                "@type": "OnOff",
                "valueType": { "type": "boolean" }
              },
              "links": [
              {
                "href" : "coap://www.example.com:5683/master",
                "mediaType": "application/json"
              },{
                "href" : "http://www.example.com:80/master",
                "mediaType": "application/json"
              }]
            }
          ],
          "associations": [
            { "hrefs": ["coap://www.example.com:5683/0"] },
            { "hrefs": ["coap://www.example.com:5683/1"] },
            { "hrefs": ["coap://www.example.com:5683/2"] },
            { "hrefs": ["coap://www.example.com:5683/3"] },
            { "hrefs": ["coap://www.example.com:5683/4"] },
            { "hrefs": ["coap://www.example.com:5683/5"] },
            { "hrefs": ["coap://www.example.com:5683/6"] },
            { "hrefs": ["coap://www.example.com:5683/7"] }
          ]
        }
      

In this last example, we illustrate the use of associations. The Thing we modeled here acts as a master switch for eight lamps similar to that of . It 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 relation. This issue will be addressed soon. Until then, Thing associations could be useful for discovery.

Usage

Extending Thing Description with Other Semantic Models

As the TD context we have developed is intended to be minimal, it is strongly recommended to extend it for each Thing by reusing other vocabularies or ontologies and/or defining application-specific terms. In the following example, in addition to our standard context, the context of the Thing declares a namespace pointing to a shared vocabulary for domotics called DogOnt:

          {
            "@context": ["http://w3c.github.io/wot/w3c-wot-td-context.jsonld",
                         {"dogont": "http://elite.polito.it/ontologies/dogont.owl#"}],
            ...
          }
        
DogOnt defines hundreds of concepts ranging from HVAC to units of measurement.

During early experimentations with TD files, a few concepts and terms appeared to be recurrent, such as Temperature, Toggle or unit. To ease experimentation with the modeling of Things, a context that gathers such common terms has been defined at http://w3c.github.io/wot/w3c-wot-common-context.jsonld. Its content simply defines aliases for classes and properties of well-known ontologies that are relevant for our activity: DogOnt, Quantity Kinds & Units, LinkedGeoData and Schema.org. This file will likely be frequently updated and is not intended to become a reference. It should always be used along with the standard TD context, as follows:

          {
            "@context": ["http://w3c.github.io/wot/w3c-wot-td-context.jsonld",
                         "http://w3c.github.io/wot/w3c-wot-common-context.jsonld"],
            ...
          }
        

@TODO more details on contextual semantics (e.g., domain independent and dependant semantic models, ontologies etc.).

Discovery

This section describes in general how a Thing (i.e., its TD) can be discovered. In particular, the current practices at the PlugFests should become clear. Technology-specific mechanisms such as BLE Beacons or UPnP multicast requests should go into the corresponding sub-sections of .

Discovering a Thing means acquiring a link to its TD, which then contains all the information to interact with it and understand its data. The URI of the link may point to the Thing (technically the servient) itself, as Things often host their TD directly, or to any other location on the Web. There are several approaches to aquire such links. Some work independent from the Protocol Binding, others rely on features of a specific protocol.

Manual Discovery

The link to the TD is provided by the developer at programming time, the operator through device management, or the user through a UI.

Repository

The Thing (or a commissioning tool) registers the TD with a well-known repository, which also provides a look-up mechanism (potentially supporting filtering).

The figure shows the basic concept of the usage of a repository: 1) A servient register its TD to a known TD repository. 2) Another servient does a lookup/search/querying (e.g., via SPARQL) at the TD repository. 3) The repository answers with one ore more relevant TDs. Also a subset of TD’s content can be in the result set (e.g., only relevant properties, actions, and/or events are included). 4) Based on the repository’s result set, a connection can be initiated.

Local Discovery

The Thing is able to broadcast a discovery request locally (e.g., a CoAP multicast request for /.well-known/core) or to receive announcements from its proximity (e.g., BLE Beacons). The response to a discovery request can include the TD directly or just a link. For announcements, it is more common to only provide a link, since broadcasting TDs can be expensive.

Security

@TODO Add howto about security metadata and how to use it