Web of Things (WoT) Thing Description

6.5.1.1 Simple Types

For Within Property schema , inputSchema and Event outputSchema interaction types, each property or event can specify its value fields, simple type assignments can be done by using the outputData type field within respective interaction type definition. In that specifies one of the following example, temperature property and criticalCondition event are defined as number and string , respectively. Example 10 datatypes borrowed from [ { ... : [ ... { : [<span class= "hljs-string">"Property"], : <span class= "hljs-string">"temperature", : { <span class= "hljs-string">"type": <span class= "hljs-string">"number" }, ... } ... { : [<span class= "hljs-string">"Event"], : <span class= "hljs-string">"criticalCondition", : { <span class= "hljs-string">"type": <span class= "hljs-string">"string" }, ... } ... ] ... } JSON-SCHEMA-VALIDATION Similarly, for Action interaction type, each action can specify its input and/or output value type using inputData and outputData field, respectively. The following ]. Shown below is an example value type definition for an action. In the example, fadeIn action is defined to have inputData of an interaction snippet that carries a simple type definition number and outputData of type within boolean schema .

            "hljs-string">"schema": { "type": 
"number"

}

Within inputData and outputData fields, JSON-LD representation for primitive data type system allows definition is a JSON object of which the field is defined below.

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.

6.5.1 6.5.1.2 Simple Data Restrictions

In order to make more precise data type defintions the TD also allows the usage of restrication terms borrowed from [ JSON-SCHEMA-VALIDATION ]. Consider the following inputData schema definition which defines the value to be an integer within the value range of [ 0 ... 255 ].

            "schema": { 
  "type": "integer",
  "minimum": 0,
  "maximum": "hljs-number">255
}

The following table only display a small subset of the restriction terms defined in JSON Schema. Please check [ JSON-SCHEMA-VALIDATION ] for the full set of restrictions.

6.5.1.3 Semantic Annotation

Unlike in JSON Schema, the TD with JSON-LD serializiation allows a semantic annotation of data members of the types by using the @type key. The example below comes with a semantic annotation within inputSchema to privide its semantic context DimmerData that is defined in the http://iotschema.org/ namespace.

{  "@context": [    
"hljs-string">"https://w3c.github.io/wot/w3c-wot-td-context.jsonld", 
    {"iot": "http://iotschema.org/"}
  ],
  ...
  "inputSchema": {     "type": 
"hljs-string">"integer",
    "@type": [
"hljs-string">"iot:DimmerData" ],
    "minimum": 
"hljs-number">0,
    "maximum": 255,
  },
  ...

}

JSON-LD representation for semantic annotation of simple type within schema , inputSchema and outputSchema fields is defined below.

6.5.1.4 Runtime Data Serializiation

Unless otherwise specified in the form field (also see [ WOT-PROTOCOL-BINDING ]) the provided schema reflects the payload structure of the runtime data of the Property , Action , and Event .

Let's consider the simple data type defintion as shown in Example 11. 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.

"hljs-tag"><
"hljs-name">integer>184</
integer

>

6.5.2.1 Object

In order to avoid duplicate key definitions with different meanings in the context documents, object definitions take a form that is slightly different from that of [ JSON-SCHEMA-VALIDATION ]. The following highlights the differences.

• TD uses a JSON array with a name field instead of JSON Schema's properties of a JSON object
• Each object in a field array must contain the key name (corresponding to the field name of the specified JSON object), and schema , whose value must be a data schema as specified in the present section (recursive definition)

The following example shows a Thing Description object definiton using JSON-LD serializiation, in comparison with an equivalent JSON Schema object definition.

{    "type": 
"hljs-string">"object",
    "field": [{        "name": 
"hljs-string">"id",
        "schema": {            "type": 
"hljs-string">"integer"
        }
    }],
    "required": [
"hljs-string">"id"]
}

{    "type": 
"hljs-string">"object",
    "properties": {        "id": {
"hljs-attr">"type": "integer"}
    },
    "required": [
"hljs-string">"id"]
}

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

            "inputSchema": {
    "type": "object",
    : [

    "field": [
        {
            "name": "hljs-string">"id",
            : {
              : <span class=
"hljs-string">"integer"

"hljs-string">"brightness",
            "schema": {                
"hljs-string">"type": "integer",
                
"hljs-string">"@type": ["iot:DimmerData"],
                
"hljs-string">"minimum": 0,
                
"hljs-string">"maximum": 255

            }
        },
        {
            "name": "name",
            : {

            "schema": {
              "type": "string"
            }
        }
    ],
    "required": ["hljs-string">"id"]

"hljs-string">"brightness"]

}

JSON-LD representation for object data type definition is a JSON object with terms as defined below.

6.5.2.2 Array

Arrays follow again the same convention as defined in [ JSON-SCHEMA-VALIDATION ]. The following is an example value type 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 ].

            "inputSchema": {    "type": 
"hljs-string">"array",
    "items": {         "type" : 
"hljs-string">"number",
         "minimum": 
"hljs-number">0,
         "maximum": 
"hljs-number">2047
    },
    "minItems" : 
"hljs-number">3,
    "maxItems" : 
"hljs-number">3
}

JSON-LD representation for array type definition is a JSON object with terms as defined below.

6.5.2.3 Runtime Data Serializiation

In the case of an object-based schema decleration the expected instance is straightforward and similar handling to JSON Schema and JSON instances. Let's consider Example 18: When the id brightness number and the name string values being exchanged are 1314520 200 and "Web of Things", data serialization in JSON format will look like the following.

{
  "brightness": "hljs-number">200,

  "name": "Web of Things"
}

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

"hljs-tag"><object>

  <id>
    <"hljs-name">integer1314520<span class=

"hljs-name">integer>200
"hljs-tag"></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 field definition of the object .

The following is an example valueType definition that defines In the value to be case of an array that consists of exactly three number literals with each value within decleration there is the range of [ 0 ... 2047 ]. same bahavior from JSON Schema and JSON instances. Let's consider Example 18 : { : <span class= "hljs-string">"array", : { : <span class= "hljs-string">"number", : <span class= "hljs-number">0, : <span class= "hljs-number">2047 }, : <span class= "hljs-number">3, : <span class= "hljs-number">3 } 19: 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.

"hljs-tag"><array>

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

>

6.5.3.1 Object Definition to XML Schema

Shown below is the type system object definition given for the inputData inputSchema 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",
    : [

    "field": [
        {
            "name": "id",
            : {

            "schema": {
              "type": "integer"
            }
        },
        {
            "name": "name",
            : {

            "schema": {
              "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.

"hljs-tag"><
"hljs-name">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 .

"hljs-tag"><
"hljs-name">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

>

6.5.3.2 Array Definition to XML Schema

Shown below is the type system array definition given for the inputData inputSchema 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.

"hljs-tag"><
"hljs-name">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 .

"hljs-tag"><
"hljs-name">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

>