Web of Things (WoT) Thing Description

5.2.1 Thing

Describes a physical and/or virtual Thing (may represent one or more physical and / or and/or virtual Things) in the Web of Thing Things 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 the 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.

Each instance of a Property , Action , and Event class MUST have an identifier that is unique within the context of a Thing Description document. See Section Representation Format for more details about JSON-LD 1.1 identifiers.

The class InteractionPattern has the following subclasses:

• Action Event
• Event Property
• Property Action

5.2.3 Property

Property provides readable and/or writeable data Properties expose internal state of a Thing 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 directly retrieved (get) and optionally modified (set). In addition, Things can also inherited all vocabulary from choose to make Properties observable by pushing the InteractionPattern class. new state (not an event) after a change; this must follow eventual consistency (also see CAP Theorem).

5.2.4 Action

The Action interaction pattern triggers changes or processes on Actions offer functions of the Thing. These functions may manipulate the internal state of a Thing that take in a certain time to complete (i.e., actions cannot be applied instantaneously like property writes). way that is not possible through setting Properties. Examples include an LED fade in, moving are changing internal state that is not exposed as a robot, brewing Property, changing multiple Properties, changing Properties over time or with a cup of coffee, etc. Usually, ongoing process that should not be disclosed. Actions are modelled as Task resources, which are created when an Action invocation is received by the Thing. Please note, this class may also inherited all vocabulary from be pure functions, that is, they may not use any internal state at all, and may simply process input data and return a result that directly depends only on the InteractionPattern class. input given.

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. Field Name Description Expected value type schema link to the n-ary class that allows the declaration of the data type and unit of measure provided by a property or an event. DataSchema 5.2.6 DataSchema

This class embeds the terms The Event Interaction Pattern describes event sources that asynchronously push messages. Here not state, but state transitions (events) are defined communicated (e.g., "clicked"). Events may be triggered by JSON Schema ( https://tools.ietf.org/html/draft-handrews-json-schema-validation-00#section-6 ) and map them in a Linked Data form to allow, e.g., the representation of pairs (data type, semantic meaning such as unit of measure) internal state changes that are expected not exposed as input data or output data Properties. Events usually follow strong consistency, where messages need to be queued to ensure eventual delivery of a given interaction pattern. all events that have occurred.

Instances of the TD deliverable Event class contains the full list term definitions of schema terms will be defined here. For now, please check the data schema defintions that are provided in Section 6.5 class InteractionPattern and examples provided in WoT Binding Template DataSchema .

5.2.7 5.2.6 Form

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

5.2.8 5.2.7 Link

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

6.1 5.3.1 Thing as a Whole The JSON-LD representation for a Thing Description is a JSON object of which fields are defined below. DataSchema

Each field in Thing The class (see 5.2.1 Thing ) is represented by the namesake JSON field described in DataSchema has the above table. following subclasses:

• @context ArraySchema 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
• BooleanSchema https://www.w3.org/ns/td/w3c-wot-td-context.jsonld . Each Thing Description instance in JSON-LD MUST have this context information enmbedded within an JSON array structure. Thus, a basic Thing Description would contain the following declaration: Example 3
• { : [<span class= "hljs-string">"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 IntegerSchema array structure. This option proves relevant if one wants to extend the existing Thing Description context without modifying it. For instance: Example 4 { : [<span class= "hljs-string">"https://www.w3.org/ns/td/w3c-wot-td-context.jsonld", {<span class= "hljs-string">"sensor": <span class= "hljs-string">"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 . NumberSchema Editor's note 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:
• Example 5 { : [<span class= "hljs-string">"https://www.w3.org/ns/td/w3c-wot-td-context.jsonld"], : [<span class= "hljs-string">"Thing"], : <span class= "hljs-string">"MyThing", : <span class= "hljs-string">"coap://mything.example.com:5683/", : [ ... } ObjectSchema Note: For examples of full Thing Description, see
• 6.7 Examples StringSchema

6.2.1 5.3.2 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 ArraySchema interaction definition. Example 6 { ... : [ { : [<span class= "hljs-string">"Property"], : <span class= "hljs-string">"temperature", :{ <span class= "hljs-string">"type": <span class= "hljs-string">"number" }, : <span class= "hljs-literal">false, : <span class= "hljs-literal">true, : [{ : <span class= "hljs-string">"coap://mytemp.example.com:5683/temp", : <span class= "hljs-string">"application/json" }] }, ... }

The JSON-LD representation for a Property interaction definition is a A JSON object of which the fields are defined below. array specification ("type": "array").

6.2.2 5.3.3 Action The Action ObjectSchema 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. Example 7 { ... : [ { : [<span class= "hljs-string">"Action"], : <span class= "hljs-string">"fadeIn", <span class= "hljs-string">"inputSchema" }, : [{ : <span class= "hljs-string">"coap://mytemp.example.com:5683/in", <span class= "hljs-string">"mediaType" }] } ] ... }

JSON-LD representation for an Action interaction definition is a A JSON object of which the fields are defined below. specification ("type": "object").

5.3.4 Type System BooleanSchema

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

5.3.5 NumberSchema

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

5.2.4 Action 5.3.6 StringSchema ) is represented by the namesake

A JSON field described in the above table. string value specification ("type": "string").

6.2.3 5.3.7 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 three mandatory terms and one optional term defined within the Event IntegerSchema pattern: Example 8 { ... : [ { : [<span class= "hljs-string">"Event"], : <span class= "hljs-string">"criticalCondition", : { <span class= "hljs-string">"type": <span class= "hljs-string">"string" }, : [{ : <span class= "hljs-string">"coap://mytemp.example.com:5683/ev", <span class= "hljs-string">"mediaType" }] } ] ... }

The JSON-LD representation for an Event interaction definition is a A JSON object of which the fields are defined below. integer value specification, that is, numbers without a fractional part ("type": "integer").

5.4.1 SecurityScheme

The form field is used to pointing a URI to an instance of the interaction and descriptions of the protocol settings and options expected to be used between the client and server for the interaction. The different opportunities of class SecurityScheme has the protocol settings (such as for HTTP, CoAP, MQTT, etc) is described in [ following subclasses:

• WOT-PROTOCOL-BINDING ]. CertSecurityScheme 6.4 Security Shown below is an example of a security resource definition. Example 10
• { ... : [{ : <span class= "hljs-string">"token:jwt", :<span class= "hljs-string">"HS256", :<span class= "hljs-string">"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 APIKeySecurityScheme ). Editor's note Consider the need for a context definition for the above example.
• 6.5 Type System All three interaction types, Property , Action , and Event , include data schema definitions. Instances of the Property BasicSecurityScheme and
• Event BearerSecurityScheme interaction types each must define only one schema (i.e.
• schema DigestSecurityScheme field), which describes the data they expose, while instances of the
• Action NoSecurityScheme interaction type can define different schemas for inputs (i.e.
• inputSchema OAuth2SecurityScheme ) and outputs (i.e.
• outputSchema PSKSecurityScheme ). In the case of a
• Property PoPSecurityScheme that allows for an update operation, the input data and the output data are defined by a single schema (
• schema PublicSecurityScheme field). 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 [ JSON-SCHEMA-CORE ] [

5.4.2 NoSecurityScheme JSON-SCHEMA-VALIDATION ], it is intended

A security configuration corresponding to be encoding-neutral and integrates into the Linked Data vocabularies ("scheme": "nosec"), indicating there is no authentication or other mechanism required 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 access the type system with a way to associate data elements with citations and semantic concepts defined elsewhere. resource.

6.5.1.1 5.4.3 Simple Types Within schema , inputSchema BasicSecurityScheme

Basic authentication security configuration ("scheme": "basic"), using an unencrypted username and password. This scheme should be used with some other security mechanism providing confidentiality, for example, TLS.

5.4.4 } CertSecurityScheme

JSON-LD representation for primitive data type definition is a JSON object of which the field is defined below. Certificate-base asymmetric key security configuration ("scheme": "cert").

6.5.1.2 5.4.5 Restrictions DigestSecurityScheme

In order Digest authentication security configuration ("scheme": "digest"). This scheme is similar to make more precise data type defintions the TD also allows the usage basic authentication but with added features to avoid man-in-the-middle attacks.

5.4.6 BearerSecurityScheme

Bearer token authentication security configuration ("scheme": "bearer"). This scheme is intended for the full set situations where bearer tokens are used independently of restrictions. OAuth2. If the oauth2 scheme is specified it is not generally necessary to specify this scheme as well as it is implied.

6.5.1.3 5.4.7 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 PSKSecurityScheme to privide its semantic context DimmerData that is defined in the http://iotschema.org/ namespace. Example 13 { : [ <span class= "hljs-string">"https://w3c.github.io/wot/w3c-wot-td-context.jsonld", {: <span class= "hljs-string">"http://iotschema.org/"} ], ... : { : <span class= "hljs-string">"integer", : [<span class= "hljs-string">"iot:DimmerData" ], : <span class= "hljs-number">0, : <span class= "hljs-number">255, }, ... }

JSON-LD representation for semantic annotation of simple type within schema , inputSchema and outputSchema fields is defined below. Pre-shared key authentication security configuration ("scheme": "psk").

6.5.1.4 5.4.8 Runtime Data Serializiation Unless otherwise specified in the form PublicSecurityScheme 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 Raw public key asymmetric key security configuration ("scheme": "public").

<span class= "hljs-tag"><<span class= "hljs-name">integer184<span class= "hljs-tag"></<span class= "hljs-name"> integer > 5.4.9 OAuth2SecurityScheme 6.5.2 Structured Data Definition

With OAuth2 authentication security configuration ("scheme": "oauth2"). For 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 implicit flow the object , authorizationUrl and scopes are required. For the other one is the array . Both object password and array client flows both tokenUrl and scopes are assigned as required. For the code flow authorizationUrl, tokenUrl, and scopes are required.

5.4.10 brightness APIKeySecurityScheme is required to be present. Example 18 : { : <span class= "hljs-string">"object", : [ { : <span class= "hljs-string">"brightness", : { <span class= "hljs-string">"type": <span class= "hljs-string">"integer", <span class= "hljs-string">"@type": [<span class= "hljs-string">"iot:DimmerData"], <span class= "hljs-string">"minimum", <span class= "hljs-string">"maximum": <span class= "hljs-number">255 } }, { : <span class= "hljs-string">"name", : { : <span class= "hljs-string">"string" } } ], : [<span class= "hljs-string">"brightness"] }

JSON-LD representation API key authentication security configuration ("scheme": "apikey"). This is for object data type definition the case where the access token is opaque and is not using a JSON object with terms as defined below. standard token format.

6.5.2.2 5.4.11 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 PoPSecurityScheme that consists of exactly three number literals with each value within the range of [ 0 ... 2047 ]. Example 19 : { : <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 }

JSON-LD representation for array type definition is a JSON object with terms as defined below. Proof-of-possession token authentication security configuration ("scheme": "pop").

Example 20 6.1.1 Thing as a whole { : <span class= "hljs-number">200, : <span class= "hljs-string">"Web of Things" }

The above data will look root object of a Thing Description instance MAY include the following when @context key from JSON-LD 1.1 with the data is exchanged in XML. value URI of the Thing description context file http://www.w3.org/ns/td .

{      "@context": 
"hljs-string">"http://www.w3.org/ns/td",
    ...
}

When a Thing Description instance is processed and interpreted by a JSON-LD 1.1 processor the @context field MUST be present > (see also Section JSON-LD 1.1 Processing ).

When a single Thing Description instance involves several contexts, additional namespaces with prefixes MUST be appended 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": ["hljs-string">"http://www.w3.org/ns/td",
                {"iot": "http://iotschema.org/"}],
    ...
}

In both JSON Each mandatory and XML serialization, values can appear in any order regardless of the order used optional field name as defined in the class field Thing definition of MUST be serialized as a JSON key in the root object . of the Thing Description instance.

In the case The type of an array decleration there is the same bahavior from JSON Schema fields properties , actions , and events MUST be a JSON instances. Let's consider Example 19: When object.

The type of the numbers being exchanged are 520, 184 fields links , scopes , and 1314, data serialization in security MUST be a JSON format will look like array.

A TD snippet based on the following. defined fields of the class Thing without the optional field @context is given below:

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

The above data will look Alternatively, the following when same example can be written instead to explicitly include the data is exchanged in XML. (semantic) keys used by JSON-LD 1.1 ( @context and @type ):

{
    "@context": "hljs-string">"http://www.w3.org/ns/td",
    "@type": 
"hljs-string">"Thing",
    "id": 
"hljs-string">"urn:dev:wot:com:example:servient:myThing",
    "name": 
"hljs-string">"MyThing",
    "description": 
"hljs-string">"Additional (human) readable information of the Thing.",
    "support": 
"hljs-string">"https://servient.example.com/contact",
    "security": [...],    "base": 
"hljs-string">"https://servient.example.com/",
    "properties": {...},    "actions": {...},    "events": {...},    "links": [...]
}

6.5.3 6.1.2 Mapping to XML Schema properties

In Properties (and sub-properties) offered by a Thing MUST be collected in the previous section, examples showed what data whose value type is described using JSON-object based properties field with (unique) Property names as JSON keys.

The type system look like when of the fields properties and items MUST be serialized to XML in parallel to corresponding as a JSON serializations. object.

This section describes how The type definitions described using of the type system can fields forms , required , and enum , scopes , and security , MUST be mapped serialized as a JSON array.

A TD snippet based on the defined fields is given below:

{
    ...
    "properties": {        "on": {            "label": 
"hljs-string">"On/Off",
            "type": 
"hljs-string">"boolean",
            "forms": [...]
        },
        "status": {            "type": 
"hljs-string">"object",
            "properties": {                "brightness": {                    
"hljs-string">"type": "number",
                    
"hljs-string">"minimum": 0.0,
                    
"hljs-string">"maximum": 100.0
                 },
                 "rgb": {                    
"hljs-string">"type": "array",
                    "items" : {                        
"hljs-string">"type" : "number",
                        
"hljs-string">"minimum": 0,
                        
"hljs-string">"maximum": 255
                    },
                    
"hljs-string">"minItems": 3,
                    
"hljs-string">"maxItems": 3
                }
            },
            
"hljs-string">"required": ["brightness", "rgb"],
            "forms": [...]
        }
    }
    ...
}

Similar to XML schema definitions the case at the Thing level, properties MAY have additional semantic annotations based on JSON-LD 1.1 keywords.

When a Thing Description instance is processed and interpreted by using a JSON-LD 1.1 processor, each property MUST contain the same examples. Given these type definitions, providing vocabulary terms observable and writable due to the mapping open-world assumption of Linked Data. This assumption means that if a Linked Data model of a Thing Description instance were to XML schema allows XML tools omit these vocabulary terms, then the interpreter would not be able to directly validate serialized XML data, for example. The XML structure for which this mapping is designed is make any assumptions about their actual value.

A snippet of a JSON-LD 1.1 processable TD serialization including semantic annotations and the default values of observable and writable based on EXI4JSON [ the class exi-for-json Property ]. is given as follows:

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

6.1.3 Object Definition to XML Schema actions

Shown below is Actions offered by a Thing MUST be collected in the type system JSON-object based object actions definition given for field with (unique) Action names as JSON keys.

The type of two named literals the fields id input (of type and integer output MUST be serialized as a JSON object.

The keys of input ) and name output (of type rely on the the class string DataSchema ) where .

The type of the fields id forms , scopes , and security is required to MUST be present. serialized as a JSON array.

A TD snippet based on the defined fields is given below:

...
"actions": {
    "fade" {
        "label": "hljs-string">"Fade in/out",
        
"hljs-string">"description": "Smooth fade in and out animation.",
        "input": {            "type": "object",
    : [
        {
            : <span class=
"hljs-string">"id",
            : {
              : <span class=
"hljs-string">"integer"
            }

            "properties": {
                "from": {
                    "hljs-string">"type": "integer",
                    
"hljs-string">"minimum": 0,
                    
"hljs-string">"maximum": 100
                },
                "to": {                    
"hljs-string">"type": "integer",
                    
"hljs-string">"minimum": 0,
                    
"hljs-string">"maximum": 100
                },
                
"hljs-string">"duration": {"type": "number"}
            },
            
"hljs-string">"required": ["to","duration"],

        },
        {
            : <span class=
"hljs-string">"name",
            : {
              : <span class=
"hljs-string">"string"
            }
        }
    ],
    : [<span class=
"hljs-string">"id"]

        "output": {"hljs-string">"type": "string"},
        "forms": [...]
    }
    ...

}
...

When Definitions within the object actions is anonymous (i.e. it is field MAY have additional semantic annotations based on JSON-LD 1.1 keywords.

6.1.4 events

Events offered by a Thing MUST be collected in the root, or participates JSON-object based events field with (unique) Event names as JSON keys.

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

The type of the above fields object forms , required , and enum , scopes , and security definition transforms to MUST be serialized as a JSON array.

A TD snippet based on the following XML Schema element definition. defined fields is given below:

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

Otherwise (i.e. Definitions within the object events is a member of another field MAY have additional semantic annotations based on JSON-LD 1.1 keywords.

6.1.5 object forms definition, thus has a name),

Each mandatory and optional vocabulary term as defined in the class object Form definition transforms to the following XML schema element definition. Note , MUST be serialized as a JSON key.

If required, forms MAY be supplemented with protocol-specific vocabulary terms identified with a prefix. See also [ $name WOT-PROTOCOL-BINDING ].

When a Thing Description instance is processed and interpreted by a JSON-LD 1.1 processor, each forms represents (array) entry MUST contain a mediaType due to the name open-world assumption of the object , and needs Linked Data. This assumption means that if a Linked Data model of a Thing Description instance were to be replaced by omit these vocabulary terms, then the interpreter would not be able to make any assumptions about their actual name of value.

A TD snippet based on the object . defined fields is given below:

...
"forms": [{
    "href" : "hljs-string">"http://mytemp.example.com:5683/temp",
    "mediaType": 
"hljs-string">"application/json",
    
"hljs-string">"http:methodName": "POST",
    "rel": 
"hljs-string">"writeProperty",
    "security": [{
"hljs-string">"scheme":"basic", "in":"header"}]
}]
...

6.5.3.2 6.1.6 Array Definition to XML Schema links

Shown below is Each mandatory and optional vocabulary term as defined in the type system class array Link definition , MUST be serialized as a JSON key.

A TD snippet based on the defined fields is given for below:

..."links": [{    "href": 
"hljs-string">"https://servient.example.com/things/lampController",
    "rel": 
"hljs-string">"controlledBy",
    "mediaType": 
"hljs-string">"application/td+json"
}]
...

6.1.7 security

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

The following TD snippet shows a simple security configuration specifying basic username/password authentication in Section Array . the header. The value of array in consists given is actually the default value of exactly three number literals header .

..."security": [{    "scheme": 
"hljs-string">"basic",
    "in": 
"hljs-string">"header"
}]
...

Here is a more complex example: a TD snippet showing digest authentication on a proxy combined with each value within bearer token authentication on an endpoint. Here the default value range of [ 0 ... 2047 ]. in in the digest scheme, header , is implied.

...
"security": [
    {
       "scheme": 
"hljs-string">"digest",
       "proxyUrl": 
"hljs-string">"https://portal.example.com/"

    },
     : <span class=
"hljs-number">3,
     : <span class=
"hljs-number">3
}

    {
       "scheme": 
"hljs-string">"bearer",
       "format": 
"hljs-string">"jwt",
       "alg": 
"hljs-string">"ES256",
       
"hljs-string">"authorizationUrl": "https://servient.example.com:8443/"
    }
]
...

When Security definitions can be given at more than one level. In this case, definitions at the lower levels override (completely replace) the definitions at the higher level.

Security configuration is mandatory. Every form in a Thing MUST have a security configuration either provided in the form itself, at the interaction level directly above it (if security is not configured in the form), or at the Thing level (if security is not configured in either the form or at the interaction level). In the vocabulary defined above, note that array security is anonymous (i.e. it marked as non-mandatory. However, this is only true locally (at a specific level), and only if the root, security is configured at a higher or participates lower level. In other words, a security configuration must be provided at some level for each form.

Security configuration is considered binding. The security configuration metadata provided in another a Thing Description MUST accurately reflect the security requirements of the Thing. Some protocols can ask for authentication dynamically. If a protocol asks for a form of security credentials not declared in the Thing Description then the Thing Description is to be considered invalid.

The array nosec definition), security scheme is provided for the case that no security is needed. The minimal security configuration for a Thing is configuration of the above array nosec definition transforms to security scheme at the top level, as in the following XML Schema element definition. example:

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

Otherwise (i.e. To give a more complex example, suppose we have a Thing where all interactions require basic authentication except for one interaction for which no authentication is required. In the following, the array nosec is a member of an scheme for the security configuration in the object overheating definition, thus has a name), event to indicate no authentication is required. For the array status definition transforms to property and the following XML schema element definition. Note toggle action, however, basic authentication is required as defined at the top level of the Thing.

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

Security definitions can also can be given for different elements at the name same level. This may be required for devices that support multiple protocols, for example CoAP and HTTP, with support for different security mechanisms. This is also useful when alternative authentication mechanisms are allowed. Here is a TD snippet demonstrating three possible ways to access a resource: via HTTPS with basic authentication, via HTTPS via digest authentication, or via CoAPS with an API key. In other words, the use of multiple security configurations at the same level provides a way to combine security mechanisms an in "OR" fashion. In contrast, putting multiple security configurations in the same array , and needs security field combines them in an "AND" fashion, since in that case they would all need to be replaced by satisfied to allow access to the actual name resource.

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

6.3.1 JSON Processing

To parse The minimum requirement to read the content of a valid Thing Description instance is a simple JSON-based parser and tools can (simple) JSON parser.

If the key terms writable and/or observable are not present within a properties definition, the default value defined in 5. Information Model MUST be used to retrieve assumed.

If the content. mediaType key term is not present within a forms definition, the default value as defined in 5. Information Model MUST be assumed.

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

6.7 6.3.2 Examples JSON-LD 1.1 Processing

In To interpret the following, we give examples semantic meaning 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 Description in an automated manner. At last, association between Things is shown by defining terms of RDF triples, a master switch controlling other LED lamps. Thing Description instance first requires a valid JSON-LD 1.1 representation based on this Thing Description specification. Then this representation can be passed to a JSON-LD 1.1 processor.

The following pre-processing steps of a Thing Description instance must be executed before starting JSON-LD 1.1 processing:

• Before starting JSON-LD 1.1 processing of a Thing Description instance, there MUST be a myTempSensor defines two Properties: myTemp @context and myThreshold . Both are key from JSON-LD 1.1 as defined in Section 6.1.1 Thing as temperatures. A client that is able to parse a TD only needs to know the predicate reference to understand that the threshold acts as whole .
• Before starting JSON-LD 1.1 processing of a reference value for myTemp while the latter is Thing Description instance, all external vocabulary terms used in the actual value measured by Thing Description MUST provide their context URIs as prefix or within the temperature sensor. Here, reference @context points to field. http://schema.org/valueReference
• . Moreover, one of the Events Before starting JSON-LD 1.1 processing of the a Thing is linked to the measured value (with the predicate property ). It means Description instance, all mandatory vocabulary terms as defined in Section 5. Information Model 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 missing from the instance MUST be inserted explicitly with their default value.

Section 1. Introduction shows an external agent example of how the input and output of such preprocessing would not have sufficient information to interpret it. appear.