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:

It defines a generic Profiling Mechanism which provides a mechanism to describe a profile in an unambiguous way. This mechanism can be used to define additional profiles.
In addition, it defines a WoT Core Profile of the Thing Description, which consists of a core data model and protocol binding rules. The WoT Core Profile formalizes the results of several PlugFests that were conducted by the WoT Interest Group and of tests that were conducted as part of the development.
This document incudes a binding of the core data model to HTTP(S) and selected notification sub-protocols. The core data model can be bound to other protocols - it is expected that bindings to other protocols (e.g. MQTT, CoAP) will be defined in the near future.

A TD that is compliant to the core profile MUST adhere to both the constraints on the data model and the protocol binding.

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.

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.

Date format

All date and time values MUST use the canonical dateTime representation format defined in section 3.2.7 of [xmlschema-2].

As described by this section the following constraints must be observed:

All dateTime values MUST use UTC as the time zone and use the 'Z' identifier.

A time value of 24:00 is NOT PERMITTED, the value 00:00 MUST be used instead.

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.

Links

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 defines a protocol binding which describes how a Consumer communicates with a Web Thing [[wot-architecture]] using JSON [[JSON]] payloads over the HTTP [[HTTP11]] protocol.

A Consumer or Web Thing conforming to the WoT Core Profile MUST implement this protocol binding.

Properties

`readproperty`

The URL of a Property resource to be used when reading the value of a property MUST be obtained from a Thing Description by locating a Form inside the corresponding PropertyAffordance for which:

After defaults have been applied, its op member contains the value readproperty
After being resolved against a base URL where applicable, the URI scheme [[RFC3986]] of the value of its href member is http or https

The resolved value of the href member MUST then be used as the URL of the Property resource.

In order to read the value of a property, a Consumer MUST send an HTTP request to a Web Thing with:

Method set to GET
URL set to the URL of the Property resource
Accept header set to application/json

          GET /things/lamp/properties/on HTTP/1.1
          Host: mythingserver.com
          Accept: application/json

If a Web Thing receives an HTTP request following the format above and the Consumer has permission to read the corresponding property, then upon successfully reading the value of the property it MUST send an HTTP response with:

Status code set to 200
Content-Type header set to application/json
A body with the value of the property serialized in JSON

          HTTP/1.1 200 OK
          Content-Type: application/json
          false

`writeproperty`

The URL of a Property resource to be used when writing the value of a property MUST be obtained from a Thing Description by locating a Form inside the corresponding PropertyAffordance for which:

After defaults have been applied, its op member contains the value writeproperty
After being resolved against a base URL where applicable, the URI scheme [[RFC3986]] of the value of its href member is http or https

The resolved value of the href member MUST then be used as the URL of the Property resource.

In order to write the value of a property, a Consumer MUST send an HTTP request to a Web Thing with:

Method set to PUT
URL set to the URL of the Property resource
Accept header set to application/json
Content-Type header set to application/json
A body with a requested new value for the property serialized in JSON

          PUT /things/lamp/properties/on HTTP/1.1
          Host: mythingserver.com
          Content-Type: application/json
          Accept: application/json
          true

If a Web Thing receives an HTTP request following the format above and the Consumer has permission to write the corresponding property, then upon successfully writing the value of the property it MUST send an HTTP response with:

Status code set to 204

          HTTP/1.1 204 No Content

`readallproperties`

The URL of a Properties resource to be used when reading the value of all properties at once MUST be obtained from a Thing Description by locating a Form inside the top level forms member for which:

Its op member contains the value readallproperties
After being resolved against a base URL where applicable, the URI scheme [[RFC3986]] of the value of its href member is http or https

The resolved value of the href member MUST then be used as the URL of the Properties resource.

In order to read the value of all properties, a Consumer MUST send an HTTP request to a Web Thing with:

Method set to GET
URL set to the URL of the Properties resource
Accept header set to application/json

          GET /things/lamp/properties HTTP/1.1
          Host: mythingserver.com
          Accept: application/json

If a Web Thing receives an HTTP request following the format above, then upon successfully reading the values of all the readable properties to which the Consumer has permission to access, it MUST send an HTTP response with:

Status code set to 200
Content-Type header set to application/json
A body with the values of all readable properties serialized in JSON, as an object keyed by property name

          HTTP/1.1 200 OK
          Content-Type: application/json
          {
            "on": false,
            "level": 100
          }

`writemultipleproperties`

The URL of a Properties resource to be used when writing the value of multiple properties at once MUST be obtained from a Thing Description by locating a Form inside the top level forms member for which:

Its op member contains the value writemultipleproperties
After being resolved against a base URL where applicable, the URI scheme [[RFC3986]] of the value of its href member is http or https

The resolved value of the href member MUST then be used as the URL of the Properties resource.

In order to write the value of multiple properties at once, a Consumer MUST send an HTTP request to a Web Thing with:

Method set to PUT
URL set to the URL of the Properties resource
Content-Type header set to application/json
Accept header set to application/json
A body with requested new values for the writable properties serialized in JSON, as an object keyed by property name

          PUT /things/lamp/properties HTTP/1.1
          Host: mythingserver.com
          Content-Type: application/json
          Accept: application/json
          {
            "on": true,
            "level": 50
          }

If a Web Thing receives an HTTP request following the format above, then upon successfully writing the values of the requested writable properties it MUST send an HTTP response with:

Status code set to 204

          HTTP/1.1 204 No Content

Other operations under consideration include observeproperty, unobserveproperty, observeallproperties and unobserveallproperties.

These operations would require consesus on a default observe mechanism for HTTP (e.g. Server Sent Events or WebSockets).

readmultipleproperties is currently excluded due to the complexities of the request payload format and because it doesn't add much functionality over readproperty and readallproperties. writeallproperties is currently excluded because it is just a special case of writemultipleproperties.

Actions

`invokeaction`

The URL of an Action resource to be used when invoking an action MUST be obtained from a Thing Description by locating a Form inside the corresponding ActionAffordance for which:

After defaults have been applied, the value of its op member is invokeaction
After being resolved against a base URL where applicable, the URI scheme [[RFC3986]] of the value of its href member is http or https

The resolved value of the href member MUST then be used as the URL of the Action resource.

In order to invoke an action on a Web Thing, a Consumer MUST send an HTTP request to the Web Thing with:

Method set to POST
URL set to the URL of the Action resource
Accept header set to application/json
Content-Type header set to application/json
A body with an input to the action, if any, serialized in JSON

          POST /things/lamp/actions/fade HTTP/1.1
          Host: mythingserver.com
          Content-Type: application/json
          Accept: application/json
          {
            "level": 100,
            "duration": 5
          }

If a Web Thing receives an HTTP request following the format above then it MUST respond with one of three response formats:

Synchronous Action Response
Asynchronous Action Response
Error Response

For long-running actions which are not expected to finish executing within the timeout period of an HTTP request (e.g. 30 to 120 seconds), it is RECOMMENDED that a Web Thing respond with an Asynchronous Action Response so that a Consumer may continue to monitor the status of an action request with a queryaction operation on a dynamically created ActionStatus resource, after the initial invokeaction response.

For short-lived actions which are expected to finish executing within the timeout period of an HTTP request, a Web Thing MAY wait until the action has completed to send a Synchronous Action Response.

If a Web Thing encounters an error in attempting to execute an action before responding to the invokeaction request, then it MUST send an Error Response.

Conforming Consumers MUST support all three types of response to the initial invokeaction request, but support for subsequent operations on an ActionStatus resource is OPTIONAL.

`ActionStatus` object

The status of an action invocation request is represented by an ActionStatus object which includes the following members:

Member	Description	Assignment	Type
`status`	The status of the action request.	mandatory	`string` (one of `pending`, `running`, `completed` or `failed`)
`output`	The output data, if any, of a completed action which MUST conform with the `output` data schema of the corresponding `ActionAffordance`.	optional	any type
`error`	An error message, if any, associated with a failed action which MUST conform with the Problem Details format [[RFC7807]] (only needed in response to a `queryaction` operation).	optional	`object`
`href`	The [[URL]] of an `ActionStatus` resource which can be polled with a `queryaction` operation to get the latest status of the action, the URI scheme [[RFC3986]] of which MUST resolve to `http` or `https` (only needed for an Asynchronous Action Response).	optional	`string`

Synchronous Action Response

If providing a Synchronous Action Response, a Web Thing MUST send an HTTP response with:

Status code set to 200
Content-Type header set to application/json
A body containing an ActionStatus object serialized in JSON

            HTTP/1.1 200 OK
            Content-Type: application/json
            {
              "status": "completed"
            }

Asynchronous Action Response

If providing an Asynchronous Action Response, a Web Thing MUST send an HTTP response containing the URL of an ActionStatus resource, the URI scheme [[RFC3986]] of which MUST resolve to http or https. The response MUST have:

Status code set to 201
Content-Type header set to application/json
Location header set to the URL of the ActionStatus resource
A body containing an ActionStatus object serialized in JSON, with its href member set to the URL of the ActionStatus resource

            HTTP/1.1 201 CREATED
            Content-Type: application/json
            Location: /things/lamp/actions/fade/123e4567-e89b-12d3-a456-426655
            {
              "status": "pending",
              "href": "/things/lamp/actions/fade/123e4567-e89b-12d3-a456-426655"
            }

`queryaction`

A queryaction operation is used to query the current state of an ongoing action request.

A Web Thing which provides Asynchronous Action Responses to an invokeaction operation on an Action MUST also support queryaction operations on that same Action. A Web Thing which only provides Synchronous Action Responses to an invokeaction operation on an Action SHOULD NOT support queryaction operations on that same Action.

The URL of an ActionStatus resource to be used in a queryaction operation MUST be obtained from the Location header of an Asynchronous Action Response, or the href member of the ActionStatus object in its body.

In order to query the status of an action request, a Consumer MUST send an HTTP request to a Web Thing with:

Method set to GET
URL set to the URL of the ActionStatus resource
Accept header set to application/json

          GET /things/lamp/actions/fade/123e4567-e89b-12d3-a456-426655
          Host: mythingserver.com
          Accept: application/json

If a Web Thing receives an HTTP request following the format above and the Consumer has permission to query the corresponding ActionStatus resource, then upon successfully reading the status of the action request it MUST send an HTTP response with:

Status code set to 200
Content-Type header set to application/json
A body containing an ActionStatus object representing the current status of the action request, serialized in JSON

            HTTP/1.1 200 OK
            Content-Type: application/json
            {
              "status": "running"
            }

If the queried action failed to execute, then the status member of the ActionStatus object MUST be set to "failed" and the error member may optionally provide additional error information conforming to the Problem Details format [[RFC7807]].

            HTTP/1.1 200 OK
            Content-Type: application/json
            {
              "status": "failed",
              "error": {
                "type": "https://mythingserver.com/docs/errors/invalid-level",
                "title": "Invalid value for level provided",
                "invalid-params": [
                  {
                    "name": "level",
                    "reason": "Must be a valid number between 0 and 100",
                  }
                ]
              }
            }

`cancelaction`

A cancelaction operation is used to cancel an ongoing Action request.

A Web Thing which provides Asynchronous Action Responses to an invokeaction operation on an Action MAY also support cancelaction operations on that same Action. A Web Thing which only provides Synchronous Action Responses to an invokeaction operation on an Action SHOULD NOT support cancelaction operations on that same Action.

The URL of an ActionStatus resource to be used in a cancelaction operation MUST be obtained from the Location header of an Asynchronous Action Response, or the href member of the ActionStatus object in its body.

In order to cancel an action request, a Consumer MUST send an HTTP request to a Web Thing with:

Method set to DELETE
URL set to the URL of the ActionStatus resource

            DELETE /things/lamp/actions/fade/123e4567-e89b-12d3-a456-426655 HTTP/1.1
            Host: mythingserver.com

If a Web Thing receives an HTTP request following the format above and the Consumer has permission to cancel the corresponding Action request, then upon successfully cancelling Action it MUST send an HTTP response with:

Status code set to 204

            HTTP/1.1 204 No Content

`queryallactions`

The URL of an Actions resource to be used when querying the status of all ongoing action requests MUST be obtained from a Thing Description by locating a Form inside the top level forms member for which:

Its op member contains the value queryallactions
After being resolved against a base URL where applicable, the URI scheme [[RFC3986]] of the value of its href member is http or https

The resolved value of the href member MUST then be used as the URL of the Actions resource.

In order to query the status of all ongoing action requests, a Consumer MUST send an HTTP request to a Web Thing with:

Method set to GET
URL set to the URL of the Actions resource
Accept header set to application/json

          GET /things/lamp/actions HTTP/1.1
          Host: mythingserver.com
          Accept: application/json

If a Web Thing receives an HTTP request following the format above, then upon successfully retreiving the status of all ongoing action requests to which the Consumer has permission to access, it MUST send an HTTP response with:

Status code set to 200
Content-Type header set to application/json
A body containing an object, keyed by Action name, with the value of each object member being an array of ActionStatus objects representing the action requests, serialized in JSON.

          HTTP/1.1 200 OK
          Content-Type: application/json
          {
            "fade": [
              {
                "status": "completed",
                "href": "/things/lamp/actions/fade/123e4567-e89b-12d3-a456-426655"
              },
              {
                "status": "failed",
                "href": "/things/lamp/actions/fade/123e4567-e89b-12d3-a456-558329",
              },
              {
                "status": "running",
                "href": "/things/lamp/actions/fade/123e4567-e89b-12d3-a457-434656"
              },
              {
                "status": "pending",
                "href": "/things/lamp/actions/fade/123e4567-e89b-12d3-a457-ea9519"
              }
            ]
          }

When an Action request is cancelled with a cancelaction operation, its ActionStatus object is deleted and need not be retained. For all other Action requests it is assumed that a Web Thing will store the ActionStatus object so that its status may later be queried with a queryaction or queryallactions operation. It is not expected that ActionStatus objects should be retained indefinitely, they may be stored in volatile memory and/or periodically pruned. The length of time for which to retain ActionStatus objects is expected to be implementation-specific and may depend on application-specific requirements or resource constraints.

Events

The Core Profile uses Server-Sent Events [[EVENTSOURCE]] as a mechanism for Consumers to subscribe to events emitted by a Web Thing.

Consumers are not required to implement the EventSource JavaScript API from the Server-Sent Events specification in order to conform with this profile. Any programming language may be used to consume an event stream.

`subscribeevent`

The URL of an Event resource to be used when subscribing to an event MUST be obtained from a Thing Description by locating a Form inside the corresponding EventAffordance for which:

After defaults have been applied, its op member contains the value subscribeevent
After being resolved against a base URL where applicable, the URI scheme [[RFC3986]] of the value of its href member is http or https
Its subprotocol member has a value of "sse"

The resolved value of the href member MUST then be used as the URL of the Event resource.

In order to subscribe to an event, a Consumer MUST follow the Server-Sent Events [[EVENTSOURCE]] specification to open a connection with the Web Thing at the URL of the Event resource.

This involves the Consumer sending an HTTP request to the Web Thing with:

Method set to GET
URL set to the URL of the Event resource
Accept header set to text/event-stream
Connection header set to keep-alive

          GET /things/lamp/events/overheated HTTP/1.1
          Host: mythingserver.com
          Accept: text/event-stream
          Connection: keep-alive

For Consumers implemented in JavaScript [[ECMASCRIPT]] and executed in a runtime which exposes the EventSource interface, a Server-Sent Events connection can be initiated using the EventSource constructor.

              const overheatedEventSource = new EventSource('/things/lamp/events/overheated');

If a Web Thing receives an HTTP request following the format above and the Consumer has permission to subscribe to the corresponding event, then it MUST follow the Server-Sent Events [[EVENTSOURCE]] specification to maintain an open connection with the Consumer and push event data to the Consumer as events of the specified type are emitted.

This involves the Web Thing initially sending an HTTP response to the Consumer with:

Status code set to 200
Content-Type header set to text/event-stream

          HTTP/1.1 200 OK
          Content-Type: text/event-stream

Whenever an event of the specified type occurs while the Web Thing has an open connection with a Consumer, the Web Thing MUST send event data to the Consumer using the event stream format in the Server-Sent Events [[EVENTSOURCE]] specification. For each message sent, the Web Thing MUST set the event field to the name of the EventAffordance and populate the data field with event data, if any. The event data MUST follow the data schema specified in the EventAffordance and MUST be serialized in JSON. The id field SHOULD be set to a unique identifier for the event, for use when re-establishing a dropped connection (see below).

            event: overheated\n
            data: 90\n
            id: 12345\n\n

If the connection between the Consumer and Web Thing drops (except as a result of the unsubscribe operation defined below), the Consumer MUST re-establish the connection following the steps outlined in the Server-Sent Events specification [[EVENTSOURCE]]. Once the connection is re-established the Web Thing SHOULD, if possible, send any missed events which occured since the last event specified by the Consumer in a Last-Event-ID header.

`unsubscribeevent`

In order to unsubscribe from an event, a Consumer MUST terminate the corresponding Server-Sent Events connection with the Web Thing as specified in the Server-Sent Events specification [[EVENTSOURCE]].

For Consumers implemented in JavaScript [[ECMASCRIPT]] and executed in a runtime which exposes the EventSource interface, a Server-Sent Events connection can be terminated using the close() method on an EventSource [[EVENTSOURCE]] object.

              overheatedEventSource.close();

`subscribeallevents`

The URL of an events resource to be used when subscribing to all events emitted by a Web Thing MUST be obtained from a Thing Description by locating a Form inside the top level forms member of a Thing Description for which:

Its op member contains the value subscribeallevents
After being resolved against a base URL where applicable, the URI scheme [[RFC3986]] of the value of its href member is http or https
Its subprotocol member has a value of "sse"

The resolved value of the href member MUST then be used as the URL of the events resource.

In order to subscribe to all events emitted by a Web Thing, a Consumer MUST follow the Server-Sent Events [[EVENTSOURCE]] specification to open a connection with the Web Thing at the URL of the events resource.

This involves the Consumer sending an HTTP request to the Web Thing with:

Method set to GET
URL set to the URL of the events resource
Accept header set to text/event-stream
Connection header set to keep-alive

            GET /things/lamp/events HTTP/1.1
            Host: mythingserver.com
            Accept: text/event-stream
            Connection: keep-alive

              const lampEventsSource = new EventSource('/things/lamp/events');

If a Web Thing receives an HTTP request following the format above then it MUST follow the Server-Sent Events [[EVENTSOURCE]] specification to maintain an open connection with the Consumer and push event data to the Consumer for all event types for which it has permission to subscribe.

This involves the Web Thing initially sending an HTTP response to the Consumer with:

Status code set to 200
Content-Type header set to text/event-stream

            HTTP/1.1 200 OK
            Content-Type: text/event-stream

Whenever an event occurs while the Web Thing has an open connection with a Consumer, the Web Thing MUST send event data to the Consumer using the event stream format in the Server-Sent Events [[EVENTSOURCE]] specification. For each message sent, the Web Thing MUST set the event field to the name of the EventAffordance and populate the data field with event data, if any. The event data MUST follow the data schema specified in the EventAffordance and MUST be serialized in JSON. The id field SHOULD be set to a unique identifier for the event, for use when re-establishing a dropped connection (see below).

            event: overheated\n
            data: 90\n
            id: 12345\n\n

If the connection between the Consumer and Web Thing drops (except as a result of the unsubscribeallevents operation defined below), the Consumer MUST re-establish the connection following the steps outlined in the Server-Sent Events specification [[EVENTSOURCE]]. Once the connection is re-established the Web Thing SHOULD, if possible, send any missed events which occured since the last event specified by the Consumer in a Last-Event-ID header.

`unsubscribeallevents`

In order to unsubscribe from all events, a Consumer MUST terminate the corresponding Server-Sent Events connection with the events endpoint of the Web Thing, following the steps specified in the Server-Sent Events specification [[EVENTSOURCE]].

              lampEventsSource.close();

Error Responses

If any of the operations defined above are unsuccessful then the Web Thing MUST send an HTTP response with an HTTP error code which describes the reason for the failure. It is RECOMMENDED that error responses use one of the following HTTP error codes:

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Web Things MAY respond with other valid HTTP error codes (e.g. 418 I'm a teapot), but Consumers MAY interpret those error codes as a generic 4xx or 5xx error with no special defined behaviour.

If we define the finite set of error responses as above then we should also define what a Consumer should do if it receives a 3xx redirect type response.

If an HTTP error response contains a body, the content of that body MUST conform with with the Problem Details format [[RFC7807]].

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

define action semantics
define subscription mechanism
Examples

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.

Motivation for a Profile

Introduction

Deployment Scenarios

Why a Core Profile?

Out-of-the-box interoperability

Structure of this document

Terminology

Additional Definitions:

Profiling Mechanism

WoT Core Profile

WoT Core Data Model

General

Mandatory fields

Date format

Length and Value Limits

Thing

Mandatory fields

Recommended practice

Data Schema

Data Schema Constraints

Property Affordance

Mandatory fields

Additional Constraints

Recommended Practice

Action Affordances

Mandatory fields

Additional Constraints

Recommended Practice

Event Affordance

Mandatory fields

Additional Constraints

Forms

Mandatory fields

Additional Constraints

Links

Security

Recommended Practice

Protocol Binding

Properties

readproperty

writeproperty

readallproperties

writemultipleproperties

Actions

invokeaction

ActionStatus object

Synchronous Action Response

Asynchronous Action Response

queryaction

cancelaction

queryallactions

Events

subscribeevent

unsubscribeevent

subscribeallevents

unsubscribeallevents

Error Responses

External TD representations

Canonical TD representation

Open Issues

JSON Schema of the Core Profile

`readproperty`

`writeproperty`

`readallproperties`

`writemultipleproperties`

`invokeaction`

`ActionStatus` object

`queryaction`

`cancelaction`

`queryallactions`

`subscribeevent`

`unsubscribeevent`

`subscribeallevents`

`unsubscribeallevents`