The WoT Profile Specification defines a Profiling Mechanism and a WoT Core Profile, which enables out of the box interoperability among things and devices. Out of the box interoperability implies, that devices can be integrated into various application scenarios without deep level adaptations. Typically only minor configuration operations are necessary (such as entering a network key, or IP address) to use the device in a certain scenario. These actions can be done by anyone without specific training.

The WoT Core Profile defines a set of constraints and rules, which compliant thing descriptions have to adopt to guarantee interoperability.

These rules are prescriptive, to ensure that compliant implementations satisfy the semantic guarantees implied by them. We call this set of rules a Profile.

The WoT Profile Specification as defined in this document serves two purposes:

Devices that constrain their use of the Thing Description to the WoT Core Profile can interoperate with each other out-of-the-box.

Note that the core profile is not exclusive. Device implementers are free to adopt other features of the thing description that go beyond the constraints of the core profile, however the interoperability guarantees of the core profile hold only for the WoT Core Profile subset.

The name WoT Core Profile is still under discussion in the group and is used as a working title. It is subject to change after the profile specification has reached a certain level of maturity.

Motivation for a Profile

The W3C WoT Thing Architecture [[wot-architecture]] and WoT Thing Description [[wot-thing-description]] define a powerful description mechanism and a format to describe myriads of very different devices, which may be connected over various protocols. The format is very flexible and open and puts very few normative requirements on devices that implement it.

However, this flexibility de-facto prevents interoperability, since, without additional rules, it allows implementers to make many choices that do not provide guarantees of common behavior between implementations.

Introduction

The W3C WoT Architecture [[wot-architecture]] and the WoT Thing Description [[wot-thing-description]] have been developed as a versatile format, that allows describing the interactions between multiple devices and protocols.

This flexibility permits an easy integration of new device types and protocols, however it risks interoperability, since there are no guarantees that two devices which are formally spec-compliant, will be able to communicate.

To increase adoption of the WoT specifications, interoperability between on premise devices, edge devices and the cloud is essential. Even if every manufacturer is implementing the current Thing Description specification in full flexibility, there is no interoperability guarantee; many choices are still left to the implementations and there are very few normative requirements that a device has to fulfill.

Deployment Scenarios

A Thing Description can be used in two fundamentally different deployment scenarios:

For green field deployments, where the implementations are being carried out and corresponding thing descriptions are being created, it is easier to achieve full interoperability by using a small, extensible Core Profile.

In the brown field area, due to the nature of existing deployments and protocols, a broad spectrum of variations and potentially high complexity of thing descriptions inhibits interoperability and will most likely lead to additional profiles of the WoT Thing Description and domain-specific thing consumer implementations.

The WoT Core Profile can be used by green field deployments and gives guidance to new implementers of the WoT specifications. It has already proved in brown-field scenarios in the PlugFests, where existing devices, that already existed as products, prototypes or demonstrators, were described with Thing Descriptions that are constrained to the Core Profile.

Why a Core Profile?

During the recent WoT PlugFests there were many de-facto agreements on the use of a small constrained subset of interaction patterns and protocol choices. These de-facto agreements select a common subset of the WoT Thing Description, based on proven interoperability among manufacturers.

The aim of this specification is to formalize these agreements by defining a WoT Core Profile based on the choices that were made by the implementers of PlugFest devices.

The WoT Core Profile contains additional normative requirements that MUST be satisfied by devices to be compliant to the profile.

WoT-Core-Profile-Picture
WoT Core Profile - A Subset of Affordances

Adoption of the WoT Core Profile will significantly limit the implementation burden of device and cloud implementors.

The WoT Core Profile was defined with the following main goals:

It makes choices on the required metadata fields as well as the supported interactions and protocol endpoints. It introduces some constraints on data schemas for properties and actions which are required for resource constrained devices in real-world deployments. The format does not forbid the use of additional elements of the WoT Thing Description for vendor specific extensions, however this will impact interoperability.

Out-of-the-box interoperability

Devices, which implement the Core Profile, are out-of-the-box interoperable with other Core Profile compliant devices. Furthermore, the Core Profile simplifies device validation and compliance testing since a corresponding conformance test suite can be defined.

It is also a goal of the WoT Core Profile to ensure that compliant files can be understood by humans - therefore descriptions, dates, and author fields are either mandatory or highly recommended.

Structure of this document

to be added.

A device or consumer implementation complies with this specification if it follows the normative statements in the present document.

A JSON Schema [[?JSON-SCHEMA]] to validate the compliance of a Thing Description with the core profile is provided in Appendix .

Terminology

This specification uses the same terminology as the WoT Architecture and Thing Description specifications.

For convenience of the reader, we use the terms keyword and field for the linguistic notion vocabulary term as defined in the Thing Description Specification.

We use the terms device and thing in an interchangeable manner.

Additional Definitions:

Profile
A set of prescriptive rules, to ensure that compliant implementations satisfy the semantic guarantees that are implied by them.
WoT Core Profile
The subset of the Thing Description defined by the present document.
Core Profile
Synonym for WoT Core Profile.
Core Data Model
A Data Model that conforms to the subset of the Thing Description specification as defined in section .
Thing Description
Synonym for WoT Thing Description.
WoT Thing Description
The Web of Things Thing Description as defined in [[wot-thing-description]].

Profiling Mechanism

This section describes a generic mechanism to define a profile of the WoT Thing Description in a unambiguous way.

The W3C WoT Thing Description specification defines a formal language, i.e. a set of vocabulary terms (keywords), a set of classes that are built from these keywords, and a set of additional rules, that define constraints on permitted values and keyword presence (mandatory / optional) dependent on the context where the keyword is used. In addition the WoT Thing Description specification defines relationships and corresponding cardinalities between these classes.

The WoT Thing Description specification already has some constraints, but there is a wide variety of variations that are left to the interpretation or the discretion of an implementer. The rationale for the Core Profile is not to forbid complex things, rather to enable statements like:

Methodology

A profile is a set of constraints and rules, which provide additional semantic guarantees that are applied to the WoT Thing Description specification. These constraints define a subset of valid WoT Thing Descriptions by defining additional rules on various aspects of the WoT Thing Description specification.

Constraints on Rationale Example
vocabulary of Thing Description classes guaranteed set of metadata fields Make specific vocabulary terms mandatory, remove others
class relationships unambiguous structure limited cardinality, e.g. only one form per operation per interaction affordance.
values of vocabulary terms simplified processing Limit the length of characters per string. Always use arrays, where the spec permits a string or an array of strings.
data schemas simplified processing No arbitrary nested objects or arrays of arrays
security reduced implementation effort Only a restricted set of security mechanisms
protocol binding guaranteed protocol semantics limited protocol(s) and protocol features, Example: predefined mapping of http verbs (GET/PUT) to operation verbs, similar constraints for other protocols.

These constraints and rules fall into two categories:

These two categories are orthogonal to each other, i.e. a data model that conforms to a profile can be mapped to different protocols. The protocol binding for each protocol may contain additional (protocol-specific) constraints.

A profile is not exclusive, i.e. a thing may conform to multiple profiles. Profiles can build on top of each other or overlap, extended profiles can be built on top of the core profile.

This specification does not put any requirements on the scope and contents of other profiles.

WoT Profiles
WoT Core Profile - Other Profiles

In the present document, we define a Core Profile by defining a Core Data Model and a set of Protocol Binding Rules for selected protocols.

WoT Core Profile

This section defines the Core Profile by defining a Core Data Model and a set of Protocol Binding Rules.

WoT Core Data Model

The core data model incorporates the data model defined by chapter 5 of the Thing Description specification. The normative rules defined by that data model are the baseline for the definition of the core data model and are normative for the core data model. A core profile compliant implementation MUST additionally satisfy the requirements of this chapter.

General

The following rules are applicable to multiple classes of the WoT Thing Description Specification, as they provide clearer semantics, improved readability and simplified processing on resource constrained devices.

Mandatory fields

One of the primary benefits of the WoT Thing Description over a typical IoT format is the additional documentation for a human reader.

Therefore, the fields title and description are MANDATORY for Things, Property Affordances, Action Affordances, Event Affordances and Data Schemas.

It is possible to have empty values for these fields, if, for specific purposes it is not desired to provide documentation, however this is NOT RECOMMENDED and the conscious decision is obvious from the TD.

Length and Value Limits

The length of id , description and descriptions values is limited to 512 characters.

The length of title and titles values is limited to 64 characters.

Where a type permits using an array of string or a string , an array of string MUST be used.

TODO: decide if multiple types and contexts are required.

In this case the following section could be added:

The only exception to this rule are @context and @type annotations, where both string or array of string MAY be used.

Where a type permits using an array of DataSchema or a DataSchema , an array of DataSchema MUST be used.

All elements of an enum MUST be either string or number . Different types in a single enum are NOT PERMITTED.

Thing

The Core Data Model applies the following constraints and rules to the Thing class of section 5.3.1.1 of the WoT Thing Description specification.

Mandatory fields

To provide minimum interoperability, the following metadata fields of a Thing MUST be contained in a compliant Thing Description:

keyword type remarks
title string human readable documentation
id urn_type a globally unique urn of the thing
description string human readable documentation
created date human readable documentation
modified date human readable documentation
support urn_type human readable documentation
security array of string simplified handling
version VersionInfo clear versioning, easy to compare different TDs
Recommended practice

It is RECOMMENDED to use the value "" for strings, where the value cannot be determined.

If a Thing Description is used solely within a company, the email address of the developer SHOULD be used in the support field, if the Thing Description is provided externally, a support email address SHOULD be used.

It will be evaluated whether the profile also recommends some new TD terms that may be introduced in TD 1.1. Currently the following terms are discussed: serialNumber, hardwareRevision, softwareRevision, loc_latitude, loc_longitude loc_altitude, loc_height, and loc_depth. If these, or some of them, are defined in the TD 1.1 model, they may be recommended here in one of the next draft updates.

Data Schema

Data Schemas are used for the values of Properties, Action input and output parameters and Event message payloads. The value of a Data Schema can be a simple type (boolean, integer, number, string) or an instance of a structured type (array and object).

The Core Data Model applies the following constraints and rules to the DataSchema class of section 5.3.2.1 of the WoT Thing Description Specification.

This section defines a subset of the class DataSchema that can be processed on resource-constrained devices.

Data Schema Constraints

The Core Data Model restricts the use of arrays and objects to the top level of Data Schemas, i.e. only a one-level hierarchy is permitted. The members of a top level object or array MUST NOT be array or object types.

This may appear as a severe limitation, however it is motivated by integrating with multiple cloud services. Many enterprise services and applications are based on (relational) databases, where individual property values are stored. Of course databases can also store objects (e.g. encoded as a JSON string), however this will prevent processing by other enterprise applications.

If a property conceptually has a deeper structure, such as grid of lamps with RGB colors, the structure can be represented in the keyword of the property, i.e. lamp1_color_r, lamp1_color_g and lamp1_color_b. A similar mapping can be done for arrays and hierarchical objects. This constraint leads to simpler Thing Descriptions that can be handled by very limited devices.

The following fields MUST be contained in a DataSchema:

keyword type constraints
description human readable description
type string one of boolean, integer, number, string, array or object

The values object , array MAY only be used at the top level of a Data Schema. The type value MUST NOT be null .

Property Affordance

The Core Data Model applies the following constraints and rules to the PropertyAffordance class of section 5.3.1.3 of the WoT Thing Description Specification.

Mandatory fields

The following property fields MUST be contained in the properties element of a Profile compliant TD:

keyword type constraints
title string unique name among all properties
description string human readable description
type string one of boolean , string , number , integer , object or array . The type value null MUST NOT be used.

Additional Constraints

The Thing Description permits arbitrary object depths for properties. Parsing of a deeply nested structure is not possible on resource constrained devices. Therefore each property MUST NOT exceed a maximum depth of 5 levels of nested array or object elements. It is RECOMMENDED to keep the nesting of these elements below 4.

The following additional constraints MUST be applied to the Property Affordances of a Thing Description conforming to the Core Profile:

keyword type constraint
const anyType MUST NOT be used
enum array of simple type Values of enums MAY only be simple types. Handling of any type is too complex to implement on resource constrained devices
forms array of Forms The Array of Form of each property MUST contain only a single endpoint for each operation readproperty , writeproperty , observeproperty , unobserveproperty.
format string If the field format is used, only formats defined in section 7.3.1-7.3.6 of [[JSON-SCHEMA]] MAY be used.
oneOf string The DataSchema field oneOf does not make sense for properties and MUST NOT be used.
uriVariables Map of DataSchema uriVariables MUST NOT be used.

Recommended Practice

It is highly RECOMMENDED to always specify a unit , if a value has a metric. Authors of Thing Descriptions should be aware, that units that are common in their geographic region are not globally applicable and may lead to misinterpretation with drastic consequences.

The field unit could be used for non-decimal numeric types as well, e.g. a string value with binary or hex data ( 0xCAFEBABE , 0b01000010 ), where the unit is hex or bin , to indicate how the value should be interpreted. It is strongly RECOMMENDED to use the values hex , oct or bin in this case to achieve interoperability.

Action Affordances

The Core Data Model applies the following constraints and rules to the ActionAffordance class of section 5.3.1.4 of the WoT Thing Description Specification.

Mandatory fields

The following fields MUST be contained in an action element of an Core Profile compliant TD:

keyword type constraints
title string unique name among all actions
input array of DataSchema all elements of the subclasses objectSchema and dataSchema MUST only contain simple types.
output array of DataSchema all elements of the subclasses objectSchema and dataSchema MUST only contain simple types.

Additional Constraints

The elements of the DataSchema subclasses ArraySchema and ObjectSchema for the fields input and output are restricted to simple types in a Thing Description conforming to the Core Data Model. Without this limitation a higher implementation burden would be put on resource constrained devices (arbitrary cascaded arrays and multi-level objects) which cannot be satisfied by all consuming devices.

The following additional constraints MUST be applied to the Interaction Affordances of a Thing Description conforming to the Core Data Model:

keyword type constraint
forms array of Forms The Array of Form of each action MUST contain only a single endpoint.
format string If the field format is used, only formats defined in section 7.3.1-7.3.6 of [[JSON-SCHEMA]] MAY be used.
oneOf string The DataSchema field oneOf does not make sense for properties and MUST NOT be used.
uriVariables Map of DataSchema uriVariables MUST NOT be used.

TODO:

- no optional parameters

- timeout

Recommended Practice

Event Affordance

The Core Data Model applies the following constraints and rules to the EventAffordance class of section 5.3.1.5 of the WoT Thing Description Specification.

A Thing may provide more than one event mechanism to enable a variety of consumers.

TODO:

The events section needs to be signifcantly extended and define addtional constraints to ensure OOTBI. LongPoll, WebSockets and WebHooks can be considered as initial candidates for supported protocols for the event mechanism to identify appropriate data model constraints.

The individual protocol constraints need to be defined in a respective protocol binding chapter after they have been identified/evaluated in plugfests.

Mandatory fields

The following fields MUST be present in an event element of a Core TD:

keyword type constraints
title string unique name among all events
description string human readable description
data set of DataSchema instances in a JSON object only the DataSchema subclasses booleanSchema, IntegerSchema, NumberSchema, StringSchema are permitted

Additional Constraints

The following additional constraints MUST be applied to the Event Affordances of a WoT Thing Description conforming to the profile:

keyword type constraint
forms array of Forms The Array of Form of each event MUST contain only a single endpoint.
uriVariables Map of DataSchema uriVariables MUST NOT be used.

Forms

A Thing may provide more than one event mechanism to enable a variety of consumers.

Mandatory fields

The following fields MUST be present in a form element of a Core TD:

keyword type constraints
title string unique name among all events
description string human readable description
data set of DataSchema instances in a JSON object only the DataSchema subclasses booleanSchema, IntegerSchema, NumberSchema, StringSchema are permitted

Additional Constraints

The following additional constraints MUST be applied to the Form elements of a WoT Thing Description conforming to the Core profile:

keyword type constraint
security string or Array of string security at form level MUST NOT be used.
scopes string or Array of string scopes MUST NOT be used.
TODO: Consider selecting a defined set from [[RFC8288]].

The "type" relationship as defined in chapter 6 of [[RFC6903]] is reserved for indicating an instance relationship between a thing and a thing template. The Core Data Model does not put additional constraints or requirements on links. The interpretation of a link is out of scope.

Security

The Core Data Model defines a subset of the security schemes that MAY be implemented on resource constrained devices. A security scheme MUST be defined at the thing level. The security scheme is applied to the thing as a whole, a thing may adopt multiple security schemes.

The set of security schemes supported in the Core Data Model is based on the PlugFest results. To ensure interoperability, a TD consumer, which compliant with the Core Data Model MUST support all of the following security schemes:

  • no security
  • Basic Auth
  • Digest
  • Bearer Token
  • Oauth2

Recommended Practice

When using the "no security" or "Basic Auth" security schemes it is strongly recommended to use transport layer encryption.

Protocol Binding

This section is work in progress and will undergo significant changes past FPWD to incorporate experiences of implementations in plug-fests and products.

This section describes how the Core Data Model is bound to different protocols. In addition to a set of mapping rules, it defines additional behavior, e.g. timeouts, error behavior, action semantics, etc.

Common core data model

The HTTP protocol binding is not meant to be exclusive, the common core data model can be bound to other protocols as well. The common core datamodel ensures interoperability across different protocols.
Bindings for additional protocols can be defined in a future version of this specification, or, already included in the current version.

HTTP Protocol Binding

All communication is using JSON payloads over HTTP(s). The content type header MUST be set to "application/json".

Properties

The HTTP verbs GET and PUT are mapped on reading and writing a property - all other protocol verbs return an error "405 Method Not Allowed".

Note: Since HTTP does not provide a pub/sub mechanism, the observe interaction is not supported directly. The event mechanism can be used instead to send notifications on property changes.

Multiple properties can be set/get by accessing the Properties endpoint.

Actions

Actions can be synchronous and asynchronous. The current TD specification does not distinguish these two cases and does not describe a detailed mechanism.

The HTTP verb POST is mapped to invoking an action on the actions endpoint - all other protocol verbs return an error "405 Method Not Allowed".

Events

The candidate sub-protocols for events are WebHooks, WebSockets, SSE and Long polling. SSE and LongPolling are suggested as the preferred candidates for a thing that provides event affordances.

External TD representations

The default representation is JSON. Semantic annotations based on JSON-LD MAY be present but are not required to perform all interactions with the thing instance.

Canonical TD representation

A canonical representation serves multiple purposes. It is simplifying the parsing process, enables to identify equivalent TDs by simple string comparisons. Furthermore it allows the use of a simple signing mechanism, such as Linked Data Proofs or JSON Web Signatures [[RFC7515]] and enables identity checks on encrypted TDs.

The canonical JSON representation format of a TD adopts the JSON Canonicalization Scheme (JCS) defined by 6292.

Open Issues

JSON Schema of the Core Profile

A Thing Description can be syntactically validated with the JSON Schema [[?JSON-SCHEMA]] for compliance with the core profile.

Todo: Define a JSON-SCHEMA.