Thing

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

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 has a (unique) name. See Section Representation Format for more details about JSON-LD 1.1 identifiers.

The class InteractionPattern has the following subclasses:

• Event
• Property
• Action

Property

Properties expose internal state of a Thing that can be directly retrieved (get) and optionally modified (set). In addition, Things can also choose to make Properties observable by pushing the new state (not an event) after a change; this must follow eventual consistency (also see CAP Theorem).

Property instances may also be instances of the class DataSchema and therefore can contain, among others, the type term.

Action

Actions offer functions of the Thing. These functions may manipulate the interal state of a Thing in a way that is not possible through setting Properties. Examples are changing internal state that is not exposed as a Property, changing multiple Properties, changing Properties over time or with a process that should not be disclosed. Actions may also 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 input given.

Event

The Event Interaction Pattern describes event sources that asynchronously push messages. Here not state, but state transitions (events) are communicated (e.g., "clicked"). Events may be triggered by internal state changes that are not exposed as Properties. Events usually follow strong consistency, where messages need to be queued to ensure eventual delivery of all events that have occurred.

Instances of the Event class contains the term definitions of the class InteractionPattern and DataSchema.

Form

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

Link

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

DataSchema

The class DataSchema has the following subclasses:

• ArraySchema
• BooleanSchema
• IntegerSchema
• NumberSchema
• ObjectSchema
• StringSchema

ArraySchema

A JSON array specification ("type": "array").

ObjectSchema

A JSON object specification ("type": "object").

BooleanSchema

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

NumberSchema

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

StringSchema

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

IntegerSchema

A JSON integer value specification, that is, numbers without a fractional part ("type": "integer").

SecurityScheme

The class SecurityScheme has the following subclasses:

• CertSecurityScheme
• PoPSecurityScheme
• APIKeySecurityScheme
• BasicSecurityScheme
• BearerSecurityScheme
• DigestSecurityScheme
• NoSecurityScheme
• OAuth2SecurityScheme
• PSKSecurityScheme
• PublicSecurityScheme

NoSecurityScheme

A security configuration corresponding to ("scheme": "nosec"), indicating there is no authentication or other mechanism required to access the resource.

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.

CertSecurityScheme

Certificate-base asymmetric key security configuration ("scheme": "cert").

DigestSecurityScheme

Digest authentication security configuration ("scheme": "digest"). This scheme is similar to basic authentication but with added features to avoid man-in-the-middle attacks.

BearerSecurityScheme

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

PSKSecurityScheme

Pre-shared key authentication security configuration ("scheme": "psk").

PublicSecurityScheme

Raw public key asymmetric key security configuration ("scheme": "public").

OAuth2SecurityScheme

OAuth2 authentication security configuration ("scheme": "oauth2"). For the implicit flow the authorizationUrl and scopes are required. For the password and client flows both tokenUrl and scopes are required. For the code flow authorizationUrl, tokenUrl, and scopes are required.

APIKeySecurityScheme

API key authentication security configuration ("scheme": "apikey"). This is for the case where the access token is opaque and is not using a standard token format.

PoPSecurityScheme

Proof-of-possession token authentication security configuration ("scheme": "pop").

Thing as a whole

The root object of a Thing Description instance MAY include the @context key from JSON-LD 1.1 with the value URI of the Thing description context file http://www.w3.org/ns/td.

{  
    "@context": "http://www.w3.org/ns/td",
    ...
}

http://www.w3.org/ns/td uses content negotiation to return the context file. Thus, it must be fetched with an Accept header set to application/ld+json.

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": ["http://www.w3.org/ns/td",
                {"iot": "http://iotschema.org/"}],
    ...
}

Each mandatory and optional field name as defined in the class Thing MUST be serialized as a JSON key in the root object of the Thing Description instance.

The type of the fields properties, actions, and events MUST be a JSON object.

The type of the fields links and security MUST be a JSON array.

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

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

Alternatively, the same example can be written instead to explicitly include the (semantic) keys used by JSON-LD 1.1 (@context and @type):

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

properties

Properties (and sub-properties) offered by a Thing MUST be collected in the JSON-object based properties field with (unique) Property names as JSON keys.

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

The type of the fields forms, required, and enum, and potentially security, MUST be serialized as a JSON array.

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

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

Similar to 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 a JSON-LD 1.1 processor, each property MUST contain the vocabulary terms observable and writable due to the open-world assumption of Linked Data. This assumption means that if a Linked Data model of a Thing Description instance were to omit these vocabulary terms, then the interpreter would not be able to 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 the class Property is given as follows:

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

actions

Actions offered by a Thing MUST be collected in the JSON-object based actions field with (unique) Action names as JSON keys.

The type of the fields input and output MUST be serialized as a JSON object.

The keys of input and output rely on the the class DataSchema.

The type of the field forms, and potentially security, MUST be serialized as a JSON array.

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

    ...
    "actions": {
        "fade" {
            "label": "Fade in/out",
            "description": "Smooth fade in and out animation.",
            "input": {
                "type": "object",
                "properties": {
                    "from": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                    },
                    "to": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                    },
                    "duration": {"type": "number"}
                },
                "required": ["to","duration"],
            },
            "output": {"type": "string"},
            "forms": [...]
        }
        ...
    }
    ...

Definitions within the actions field MAY have additional semantic annotations based on JSON-LD 1.1 keywords.

events

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

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

The type of the fields forms, required, and enum, and potentially security, MUST be serialized as a JSON array.

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

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

Definitions within the events field MAY have additional semantic anotations based on JSON-LD 1.1 keywords.

forms

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

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

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

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

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

links

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

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

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

security

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

The following TD snippet shows a simple security configuration specifying basic username/password authentication in the header. The value of in given is actually the default value of header.

   ...
   "security": [{
       "scheme": "basic",
       "in": "header"
   }]
   ...

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

    ...
    "security": [
        {
           "scheme": "digest",
           "proxyUrl": "https://portal.example.com/"
        },
        {
           "scheme": "bearer",
           "format": "jwt",
           "alg": "ES256",
           "authorizationUrl": "https://servient.example.com:8443/"
        }
    ]
    ...

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 security is marked as non-mandatory. However, this is only true locally (at a specific level), and only if the security is configured at a higher or 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 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 nosec security scheme is provided for the case that no security is needed. The minimal security configuration for a Thing is configuration of the nosec security scheme at the top level, as in the following example:

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

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 nosec scheme for the security configuration in the overheating event to indicate no authentication is required. For the status property and the toggle action, however, basic authentication is required as defined at the top level of the Thing.

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

Security definitions can also can be given for different elements at the 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 security field combines them in an "AND" fashion, since in that case they would all need to be satisfied to allow access to the resource.

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

JSON Processing

The minimum requirement to read the content of a Thing Description instance is a (simple) JSON parser.

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

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

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

JSON-LD 1.1 Processing

To interpret the semantic meaning of a Thing Description in terms of RDF triples, a 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 @context key from JSON-LD 1.1 as defined in Section .
• Before starting JSON-LD 1.1 processing of a Thing Description instance, all external vocabulary terms used in the Thing Description MUST provide their context URIs as prefix or within the @context field.
• Before starting JSON-LD 1.1 processing of a Thing Description instance, all mandatory vocabulary terms as defined in Section that are missing from the instance MUST be inserted explicitly with their default value.

Section shows an example of how the input and output of such preprocessing would appear.