5.2.1 Thing

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

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

The class InteractionPattern has the following subclasses:

• Action
• Event
• Property

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

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

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

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

5.2.7 Link

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

5.2.8 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

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

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

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

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

6.2.3 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"
      }]
    }
  ]
  ...
}

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

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

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

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

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

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

[
  520,
  184,
  1314
]

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

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

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

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

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

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

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

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

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

6.7.2 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"
        }
      ]
    }
  ]
}