W3C Universal Internet of Things Analysis: Description of things

WoT standards developed by the W3C Web of Things (WoT) Working Group and their latest status:

This series will start with the WoT standard itself, WoT Architecture (WoT Architecture), WoT Thing Description (WoT Thing Description), and WoT Scripting API (WoT Scripting) are currently in CR stage (W3C standard stage see figure below) Programming API) for a quick parse.

As shown in the figure below, the standard entering CR stage means that the content has been relatively stable, WD stage means greater uncertainty, and Working Group Note (Working Group Note) is very variable. So the “architecture” and “object description” in the CR phase are worth taking the time to understand (it has a good chance of becoming an official recommended standard REC), while the PROGRAMMING API in the WD phase recently (28 October 2019) underwent a major content overhaul that almost completely scrapped the previous version. Close to steady state, but programming apis are always something developers love, so this series will cover them.

W3C Process Document, www.w3.org/2019/Proces…

1. Brief introduction of object description

WoT Thing Description, TD for short, is a core component of WoT. As the name implies, a description of an object (TD) is a description of an object in the serialized (textual) form of a JSON document.

For simplicity, think of TD as an entry point to a descriptor and its capabilities (like a website’s index.html). An example of TD consists of four parts: metadata about the object itself, interactive recognition capabilities that represent how the object is used, data interaction patterns that are easy for machines to understand, and links to other objects or resources related to the object.

The WoT interaction model defines three types of interaction recognition: properties, actions, and events. Properties, represented by the PropertyAffordance class in TD, can be used to detect and control parameters such as taking the value of the current property or setting the state of an operation. Actions, represented in TD as the ActionAffordance class, model physical (and therefore time-consuming) processes and can also be used to abstract RPC-like calls to an existing platform. Events (represented as the EventAffordance class in TD), used to push the communication model, asynchronously sending notifications, discrete events, or streams of values to the recipient. For details, see the WoT architecture.

TD provides metadata bound to different protocols identified by URI patterns (e.g., HTTP, COAP, etc.), content types based on media types (e.g., Application/JSON, Application/CBOR), and security mechanisms (for authentication, authorization, secrecy, etc.). The TD implementation’s serialization is jSON-based, where the names (attributes/fields) in JSON refer to terms from a predefined vocabulary, also defined in the WoT Object Description standard. In addition, TD’s JSON serialization follows the JSON-LD 1.1 syntax, making it easy to extend and semantic rich processing.

An example of TD is shown below, describing an object named MyLampThing.

{
    "@context": "https://www.w3.org/2019/wot/td/v1",
    "id": "urn:dev:ops:32473-WoTLamp-1234",
    "title": "MyLampThing",
    "securityDefinitions": {
        "basic_sc": {"scheme": "basic", "in":"header"}
    },
    "security": ["basic_sc"],
    "properties": {
        "status" : {
            "type": "string",
            "forms": [{"href": "https://mylamp.example.com/status"}]
        }
    },
    "actions": {
        "toggle" : {
            "forms": [{"href": "https://mylamp.example.com/toggle"}]
        }
    },
    "events":{
        "overheating":{
            "data": {"type": "string"},
            "forms": [{
                "href": "https://mylamp.example.com/oh",
                "subprotocol": "longpoll"
            }]
        }
    }
}

Copy the code

Yes, this is a standard JSON document.

Looking at the TD example, we know that there is an attribute recognition feature called Status. And there are additional information that can pass (security) in the form of the GET method of the HTTP protocol to access URI mylamp.example.com/status (href in forms the structure members declared in) to access this property, the return value is a string. Using the GET method is not explicitly stated, but this document defines an assumed default value.

Similarly, the TD also specifies an action to identify functions, used to POST method request resources mylamp.example.com/toggle to switch to open… . The POST method here is a default assumption for calling the action.

There is also an event recognition capability that indicates that an object has a mechanism for sending asynchronous messages. Here, by polling mylamp.example.com/oh using HTTP’s long polling subprotocol, you can get events where the lamp might overheat.

This example also specifies a basic security pattern that requires a user name and password for access. Note that the name of the security schema is first given in securityDefinitions and then activated by specifying it in the Security TAB. Combined with the HTTP protocol, this example demonstrates the application of HTTP Basic Authentication. At least one top-level security mode is mandatory and is the default condition for accessing every resource.

Object description supports adding context-specific definitions in some namespaces. ** This mechanism can be used to integrate additional semantics into the content of object description instances, as long as the specification information (such as logical rules) for a particular application domain can be found in a given namespace.

The following example extends the previous TD by adding a second definition to the @context item, declaring that the namespace of the Saref vocabulary is referred to with the saref prefix. The SAREF vocabulary contains terms that describe lighting and other household automation equipment so that terms can be embedded in TD as semantic labels in the @Type attribute. In this example, the object is tagged with saref:LightSwitch, the status attribute is tagged with Saref :GetCommand, the toggle action is tagged with saref:ToggleCommand, The Cluster-event identification function was labeled SAREf :NotifyComman.

{
    "@context": [
        "https://www.w3.org/2019/wot/td/v1",
        { "saref": "https://w3id.org/saref#" }
    ],
    "id": "urn:dev:ops:32473-WoTLamp-1234",
    "title": "MyLampThing",
    "@type": "saref:LightSwitch",
    "securityDefinitions": {"basic_sc": {
        "scheme": "basic",
        "in": "header"
    }},
    "security": ["basic_sc"],
    "properties": {
        "status": {
            "@type": "saref:OnOffState",
            "type": "string",
            "forms": [{
                "href": "https://mylamp.example.com/status"
            }]
        }
    },
    "actions": {
        "toggle": {
            "@type": "saref:ToggleCommand",
            "forms": [{
                "href": "https://mylamp.example.com/toggle"
            }]
        }
    },
    "events": {
        "overheating": {
            "data": {"type": "string"},
            "forms": [{
                "href": "https://mylamp.example.com/oh"
            }]
        }
    }
}

Copy the code

2. The namespace

As mentioned earlier, an intuitive representation of an object description or TD is a JSON-LD document, and the names (attributes) in this JSON document come from several predefined vocabularies. The relationships between terms in all of these vocabularies are defined by the information model of the object description specification. Currently, the version of object description information model is defined by the following IRI:

www.w3.org/2019/wot/td…

Several other vocabularies used in the object description information model are as follows:

3. The information model

The TD information model is built on the following independent vocabularies:

• The core TD vocabulary, an interaction model that reflects interaction recognizable functions such as properties, actions, and events;
• Data model vocabulary, including some of the terms defined by JSON Schema;
• WoT security vocabulary, identifying security mechanisms and configuration requirements
• Hypermedia control vocabulary, the main specification for REST-style communication using Web links and forms.

These vocabularies are essentially a set of terms that can be used to build data structures, which can be understood as objects in the traditional object-oriented sense. An object is an instance of a class that has properties. In the context of WoT, objects refer to objects and their interactive recognizability.

The following UML diagram shows an overview of the TD information model, where tables represent classes. Starting with the Thing class, the curves with arrows show the relationships between the classes. For ease of reading, we have divided the map into four sections, each corresponding to a basic vocabulary.

Figure 1 TD core vocabulary

Figure 2. JSON schema vocabulary

Figure 3. WoT security vocabulary

Figure 4. Hypermedia control vocabulary

3.1 Predefined Content

In order to make TD information models suitable for both simple rule processing of tree documents (i.e. raw JSON processing) and rich semantic Web tools (such as JSON-LD processing), the object description specification makes a series of formal definitions for constructing TD information models.

All definitions below use “set”. Intuitively, a set is a set of elements, and the elements themselves can be a set. Any complex data structure can be defined as a set. In particular, an object is a recursively defined data structure like the following:

• A term, which may or may not belong to a vocabulary, is an object.
• A set of name-value pairs in which name is a term and value is another object, also an object.

Although the above definition does not prevent objects from containing pairs of values with the same name, object description specifications generally do not consider double names. Objects whose element names are numeric are called arrays. Similarly, objects whose element names are terms (not part of any vocabulary) are called maps. All names in name-value pairs contained in a map are assumed to be unique within the mapping scope.

Alternatively, an object can be an instance of a class. Classes (represented by a glossary term) are predefined using a set of glossary terms called signatures. Classes with an empty signature are called simple types.

The signing of a class enables the construction of two functions to further define the class: an assignment function and a type function. The assignment function of a class takes the vocabulary term that makes up the class signature as an argument and returns true or false. Simply put, the return value of the assignment function indicates whether the element in the signature is required or optional for class instantiation. The type function of a class likewise takes as an argument the vocabulary term that forms the class signature and returns another class representing the type of that term. These two functions are partial, meaning their scope is limited to the class signature.

On the basis of these two functions, you can define an Instance Relation between an object and a class. This relationship represents the constraints that must be satisfied. In other words, an object can be said to be an instance of a class if the following two conditions are met.

• Returns the assignment function for each classtrueObjects contain a name-value pair named by the glossary term;
• For each class that is used as a name in an object name-value pair, the value of the pair is an instance of the class returned by the type function of the class that takes the vocabulary term as an argument.

According to the above definition, an object is an instance of all simple types, regardless of their structure. To this end, we also define an instance relationship for simple types: if the object is a term that conforms to a given lexical form (such as true, false for Boolean, 1, 2, 3 for unsignedInt, etc.), then it is called an instance of the corresponding simple type.

In addition, qualified/parameterized classes can be derived based on generic mappings and array structures. To say that an object is a mapping of a class, or an instance of a mapping qualified by a class, then all name-value pairs contained in the object as a mapping must be instances of that class. The same goes for arrays.

Finally, if all instances of a class are also instances of another class, the former class is called a subclass of the latter.

With the above definition, the TD information model can be understood as a set of class definitions, consisting of a class name (glossary terms), a signature (glossary terms), an assignment function, and a type function. These class definitions are given in multiple tables in Section 5.3, “Class Definitions.” The required or Optional values in the Assignment column of each table indicate that the assignment function returns true or false for the corresponding glossary term.

By convention, simple types are represented by names beginning with lowercase letters. The TD information model refers to the following simple types defined in XML Schema: String, anyURI, dateTime, INTEGER, unsignedInt, Double, and Boolean. Their definitions, such as the specification of their lexical form, are beyond the scope of the TD information model.

In addition, the TD information model defines a global function that corresponds to glossary terms. This function takes a class name and another vocabulary term as arguments and returns an object. If the object returned is not NULL, it represents the default value used when assigning the vocabulary term to instances of that class. This function can relax the assignment constraint mentioned earlier: ** An object is an instance of a class if it contains all required assignments and the unassigned ones have default values. ** All default values are given in the table in “3.3 Default Definitions”. In each table of “3.2 Class Definitions”, the value of the “Assign” column is “default” if the combination of the corresponding class and glossary terms in the TD information model has default values.

The formalization introduced here does not consider the possible relationship between objects as abstract data structures and objects in the physical world such as objects. However, the object description specification also allows for the possibility that TD information models will need to reinterpret all of their vocabulary when integrated as RDF resources into larger models of the physical world (ontologies). Appendix D.2 of the specification, “Object description exists”, provides a solution to this.

3.2 Example: Thing

As mentioned earlier, the TD information model defines four vocabularies: the core vocabulary, the data schema vocabulary, the security vocabulary, and the hypermedia control vocabulary.

For the sake of simplicity, this article uses Thing in the core vocabulary as an example to introduce glossary terms related to Thing.

A Thing is an abstraction of an object or virtual entity whose metadata and interfaces are described by WoT object descriptions. A virtual entity is a combination of one or more things.

For other vocabularies and terms, please refer to the WoT object description specification for yourself.

4. Further reading

For details on the WoT working Group set up by the W3C to develop the WoT standard, see this article.

• W3C Universal Internet of Things Parsing: Architecture
• “Introduction to W3C Universal Iot Standard”
• Zhihu user “yao to jung’s” for an answer: www.zhihu.com/question/26…

5. A link to the

• WoT Architecture:www.w3.org/TR/wot-arch…
• WoT Thing Description: www.w3.org/TR/wot-thin…
• WoT Scripting API: www.w3.org/TR/wot-scri…
• WoT Binding Templates:www.w3.org/TR/wot-bind…
• WoT Security and Privacy Considerations: www.w3.org/TR/wot-secu…
• WoT Interest Group: www.w3.org/2019/07/wot…
• WoT working group: www.w3.org/2016/12/wot…