This specification defines a Profiling Mechanism and a set of Profiles which enable out-of-the-box interoperability between Web Things and their Consumers on the Web of Things.

Being out-of-the-box interoperable means that any Consumer which conforms with a given Profile can interact with any Thing which conforms with the same profile, without additional customization.

A Profile is a technical specification which provides a set of assertions to which conformant Consumers and Things must conform.

The Profiling Mechanism provides a means to denote that a given Thing conforms to one or more Profiles, by referring to the identifiers of those Profiles in the profile member of its Thing Description.

The specification defines three profiles:

The normative HTTP Basic Profile defines a protocol binding for reading and writing properties and invoking, querying and cancelling actions using the HTTP protocol.
The informative HTTP SSE Profile defines a protocol binding for observing properties and subscribing to and unsubscring from events using Server-Sent Events.
The informative HTTP Webhook Profile defines a protocol binding for subscribing to and unsubscribing from events using Webhooks.

The Profiles defined in this specification share a set of Common Constraints to which implementations of those Profiles must also conform. This includes constraints on units, date formats, security mechanisms, discovery mechanisms, link relations, errors and default language.

Future versions of this specification, or extension specifications, may define additional Profiles.

Common Constraints

The following sections are applicable for all of the HTTP profiles defined by this document.

Accessibility

Authors of Thing Descriptions must ensure that the things described by them are accessible to users with disabilities.

It is REQUIRED to provide a title that can be automatically rendered in a non-visual way (e.g. using a screen reader) for things that may be used in deployments with users with disabilities.

It is highly RECOMMENDED to provide a description that can be automatically rendered in a non-visual way (e.g. using a screen reader) for things that may be used in deployments with users with disabilities.

This is just a baseline set of requirements, which needs additional input from the APA group. It needs to be clarified which TD elements are used by people with disabilities and to which these constraints are applied.

Units

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.

It is highly RECOMMENDED to provide a unit, if a value has a physical quantity.

It is highly RECOMMENDED to use the metric system (SI units) for devices that are used in global deployments.

Date Format

All date and time values MUST use the date-time format defined in [[RFC3339]].

        2022-09-21T23:20:50.52Z

In order to reduce ambiguity, RFC 3339 only permits an hour with a value between 00 and 23 (not 24), and time zones expressed as a numerical offset relative to UTC. The suffix "Z" when applied to a time denotes a UTC offset of 00:00.

Security

Below is a list of security schemes [[wot-thing-description]] which conformant Web Things MAY use:

Conformant Consumers MUST support at least all of these security schemes.

A Thing MAY implement multiple security schemes.

A Thing MUST support at least one of the above security schemes.

For the BasicSecurityScheme the "in" field MUST be either omitted or be given its default value of "header" as defined in [[wot-thing-description11]. For the BasicSecurityScheme the "name" field MUST be provided using the value "Authorization" if a "proxy" endpoint is not given. For the BasicSecurityScheme the "name" field MUST be provided using the value "Proxy-Authorization" if a"proxy" endpoint is given.

Conformant Consumers MUST support security bootstrapping for all implemented security schemes, as defined in Security Bootstrapping in the WoT Discovery [[wot-discovery]] specification.

Conformant Things which require authentication in order to retrieve their Thing Description MUST implement security bootstrapping, as defined in Security Bootstrapping in the WoT Discovery [[wot-discovery]] specification.

Discovery

A Web Thing's Thing Description [[wot-thing-description]] MUST be retrievable from a Thing Description Server [[wot-architecture11]] using an HTTP [[HTTP11]] URL provided by a Direct Introduction Mechanism [[wot-discovery]].

Links

Hypermedia links in the HTTP Profiles are significantly constrained to ensure a common interpretation and interoperability between things and consumers.

The following keywords are defined for links in the HTTP profiles and MAY be present in profile-compliant TDs with the constraints defined by this section.

Other keywords for links MAY be present in a TD, however their interpretation is undefined in the context of the HTTP profiles These other link types MAY be ignored by all profile-compliant consumers.

These links enable consumers to interpret linked content that is provided by the link target in an unambiguous way. This interpretation is a "best effort" mechanism, that depends on the capabilities of the consumer. A consumer with a browser could render HTML content, a consumer with a PDF engine can display PDF content, a consumer with a dot-matrix display only can display icons.

For consumers that can render images or documents this implies to display appropriate documentation to a human reader.

Consumers that are capable of working with nested things and thing model structures are able to navigate between things and thing models in a well defined way.

Keyword	Type	Constraint
`href`	IRI of the link target	mandatory,`anyURI`
`type`	media type [RFC2046] of the link target	mandatory, the supported set of media types is defined in Media Types for Link Targets below.
`rel`	link relation type IANA Link Relations	mandatory, the supported subset of relation types is described in Link Relation Types below.
`sizes`	string with icon dimensions	mandatory for `icon` link targets, forbidden otherwise.
`hreflang`	`array of string` with valid language tags according to [BCP47]	optional.

Link Relation Types

Relation Type	Constraint	Remarks
`icon`	supported media types: `image/png`, `image/jpeg`.
`type`	link target MUST be a profile-compliant Thing Model	No other types are defined in the Profile.
`service-doc`	human readable documentation, supported formats are Unicode Text, markdown, HTML and PDF.
`collection`	link target is a collection of things or thing models.
`item`	link target is a collection member of the thing or thing model.

Media Types for Link Targets

The following media types from IANA MAY be used as the link targets of profile compliant TDs with the constraints in this section. Other media types MAY be present in a TD, however their heir interpretation is undefined in the context of the HTTP profiles and they MAY be ignored by all profile-compliant consumers.

Type	Constraint
`text/plain`	charset=UTF-8
`text/html`
`text/markdown`	charset=UTF-8
`text/pdf`
`application/json`
`application/ld+json`
`application/octet-stream`
`image/jpeg`
`image/png`

If a Consumer encounters a link with "rel": "icon" and "type": "image/*" and it is capable of rendering images in the provided format, then it SHOULD interpret the link as an icon for the Thing and display it to the user.

If a Consumer encounters a link with "rel": "alternate" and "type": "text/html" and it is capable of rendering an HTML page and accepting user input, then it SHOULD interpret the link as a user interface for the Thing and provide a means for the user to follow that link and view and interact with the HTML page.

If a Consumer encounters a link with "rel": "service-doc" and "type": "text/plain", "type": "text/html" or "type": "text/pdf", and is capable of rendering documents in the provided format, then it SHOULD interpret the link as a user manual for the Thing and provide a means for the user to follow that link and read the user manual.

If a Consumer encounters a link with "rel": "item" and "type": "application/td+json" and is capable of rendering a hierarchical tree of Things, then it should interpret the link as an indication that the target is a sub-Thing of the current Thing and render this in a meaningful way to the user.

If a Consumer encounters a link with "rel": "collection" and "type": "application/td+json" and is capable of rendering a hierarchical tree of Things, then it should interpret the link as an indication that the target describes a Thing (e.g. a group, system of Things or Thing Directory) which contains the current Thing and render this in a meaningful way to the user.

Errors

If any of the operations defined in the protocol bindings of HTTP profiles 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
503 Service Unavailable

A Web Thing MAY respond with 3xx status codes for the purposes of redirection, caching or authentication. A Web Thing MUST NOT respond with a 300 Multiple Choices status code.

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

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

Default Language

One Map contained in an @context Array MUST contain a name-value pair that defines the default language for the Thing Description, where the name is the Term @language and the value is a well-formed language tag as defined by [BCP47] (e.g., en, de-AT, gsw-CH, zh-Hans, zh-Hant-HK, sl-nedis).

HTTP Basic Profile

This section defines the HTTP Basic Profile, which includes a Protocol Binding for reading and writing properties and invoking, querying and cancelling actions.

This profile may be used in conjunction with the HTTP SSE Profile or the HTTP Webhook Profile in order to provide operations for observing properties and listening for events.

In order to conform with the HTTP Basic Profile, Web Things and Consumers MUST also conform with all of the assertions in the Common Constraints section.

Identifier

In order to denote that a given Web Thing conforms to the HTTP Basic Profile, its Thing Description MUST have a profile member [[wot-thing-description]] with a value of https://www.w3.org/2022/wot/profile/http-basic/v1.

Protocol Binding

This section defines a protocol binding which describes how a Consumer communicates with a Web Thing [[wot-architecture11]] using JSON [[JSON]] payloads over the HTTP [[HTTP11]] protocol.

A Consumer or Web Thing conforming to the HTTP Basic Profile MUST implement this protocol binding.

The examples provided throughout this section describe how a Consumer would communicate with a Web Thing which produces the following Thing Description:

          {
            "@context": "https://www.w3.org/2022/wot/td/v1.1",
            "id": "https://mywebthingserver.com/things/lamp",
            "profile": "https://www.w3.org/2022/wot/profile/http-basic/v1",
            "base": "https://mywebthingserver.com/things/lamp/",
            "title": "My Lamp",
            "description": "A web connected lamp",
            "securityDefinitions": {
              "oauth2": {
                "scheme": "oauth2",
                "flow": "code",
                "authorization": "https://mywebthingserver.com/oauth/authorize",
                "token": "https://mywebthingserver.com/oauth/token"
              }
            },
            "security": "oauth2",
            "properties": {
              "on": {
                "type": "boolean",
                "title": "On/Off",
                "description": "Whether the lamp is turned on",
                "forms": [{"href": "properties/on"}]
              },
              "level" : {
                "type": "integer",
                "title": "Brightness",
                "description": "The level of light from 0-100",
                "unit": "percent",
                "minimum" : 0,
                "maximum" : 100,
                "forms": [{"href": "properties/level"}]
              }
            },
            "actions": {
              "fade": {
                "title": "Fade",
                "description": "Fade the lamp to a given level",
                "input": {
                  "type": "object",
                  "properties": {
                    "level": {
                      "title": "Brightness",
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 100,
                      "unit": "percent"
                    },
                    "duration": {
                      "title": "Duration",
                      "type": "integer",
                      "minimum": 0,
                      "unit": "milliseconds"
                    }
                  }
                },
                "forms": [{"href": "actions/fade"}]
              }
            },
            "forms": [
              {
                "op": ["readallproperties", "writemultipleproperties"],
                "href": "properties"
              },
              {
                "op": "queryallactions",
                "href": "actions"
              }
            ]
          }

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
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
            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
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
            {
              "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

The readmultipleproperties operation is excluded due to the complexities of the request payload format and because it doesn't add much functionality over readproperty and readallproperties. writeallproperties is 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

If the synchronous member of the ActionAffordance [[wot-thing-description11]] is set to true then the Web Thing MUST respond with a Synchronous Action Response.

If the synchronous member of the ActionAffordance [[wot-thing-description11]] is set to false then the Web Thing MUST respond with an Asynchronous Action Response.

If the synchronous member of the ActionAffordance [[wot-thing-description11]] is undefined then the Web Thing MAY respond with either a Synchronous Action Response or Asynchronous Action 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. After the initial request, support for subsequent operations on an ActionStatus resource is OPTIONAL.

`ActionStatus` object

The status of an asynchronous 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 use the JSON serialization of 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 used by `queryaction` and `cancelaction` operations, the URI scheme [[RFC3986]] of which MUST resolve to `http` or `https` (only needed for an Asynchronous Action Response).	optional	`string`
`timeRequested`	A timestamp indicating the time at which the Thing received the request to execute the action. (See Date Format for date format constraints).	optional	`string`
`timeEnded`	A timestamp indicating the time at which the Thing successfully completed executing the action, or failed to execute the action. (See Date Format for date format constraints).	optional	`string`

It is possible that a Thing's clock may not be set to the correct time. If timings are important then a Consumer may therefore choose to treat the timeEnded member of an ActionStatus object as being relative to the timeRequested member, but not necessarily as relative to its own internal clock, or the clocks of other Things.

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 the output of the action, if any, serialized in JSON

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

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",
              "timeRequested": "2021-11-10T11:43:19.135Z"
            }

In resource constrained environments, the ActionStatus objects of older completed/failed actions MAY be deleted to make room for newly invoked actions.

A Web Thing SHOULD return a 503 error response if the invocation cannot be accepted because the action is unavailable, e.g. because the Thing is overloaded.

`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",
              "timeRequested": "2021-11-10T11:43:19.135Z"
            }

If the queried action failed to execute, then the status member of the ActionStatus object MUST be set to "failed". If the queried action failed to execute, then the error member MAY 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"
                  }
                ]
              },
              "timeRequested": "2021-11-10T11:43:19.135Z",
              "timeEnded": "2021-11-10T11:43:20.513Z"
            }

`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.

Each array in the result object MUST be sorted in reverse chronological order such that the most recent action request appears first.

          HTTP/1.1 200 OK
          Content-Type: application/json
          {
            "fade": [
              {
                "status": "completed",
                "href": "/things/lamp/actions/fade/123e4567-e89b-12d3-a456-426655",
                "timeRequested": "2021-11-10T11:43:19.135Z",
                "timeEnded": "2021-11-10T11:43:20.513Z"
              },
              {
                "status": "failed",
                "href": "/things/lamp/actions/fade/123e4567-e89b-12d3-a456-558329",
                "timeRequested": "2021-11-10T11:42:15.133Z",
                "timeEnded": "2021-11-10T11:42:22.524Z"
              },
              {
                "status": "running",
                "href": "/things/lamp/actions/fade/123e4567-e89b-12d3-a457-434656",
                "timeRequested": "2021-11-10T11:41:53.351Z"
              },
              {
                "status": "pending",
                "href": "/things/lamp/actions/fade/123e4567-e89b-12d3-a457-ea9519",
                "timeRequested": "2021-11-10T11:39:53.651Z"
              }
            ]
          }

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.

HTTP SSE Profile

This section defines the HTTP SSE Profile, including a Protocol Binding for observing properties and listening for events using Server-Sent Events [[EVENTSOURCE]].

This profile may be used in conjunction with the HTTP Basic Profile in order to provide operations to read and write properties and invoke, query and cancel actions.

In order to conform with the HTTP SSE Profile, Web Things and Consumers MUST also conform with all of the assertions in the Common Constraints section.

Identifier

In order to denote that a given Web Thing conforms to the HTTP SSE Profile, its Thing Description MUST have a profile member [[wot-thing-description]] with a value of https://www.w3.org/2022/wot/profile/http-sse/v1.

Protocol Binding

This section defines a protocol binding which describes how a Consumer communicates with a Web Thing [[wot-architecture11]] using Server-Sent Events [[EVENTSOURCE]].

A Consumer or Web Thing conforming to the HTTP SSE Profile MUST implement this protocol binding.

The examples provided throughout this section describe how a Consumer would communicate with a Web Thing which produces the following Thing Description:

        {
          "@context": "https://www.w3.org/2022/wot/td/v1.1",
          "id": "https://mywebthingserver.com/things/lamp",
          "profile": [
            "https://www.w3.org/2022/wot/profile/http-basic/v1",
            "https://www.w3.org/2022/wot/profile/http-sse/v1",
          ],
          "base": "https://mywebthingserver.com/things/lamp/",
          "title": "My Lamp",
          "description": "A web connected lamp",
          "securityDefinitions": {
            "oauth2": {
              "scheme": "oauth2",
              "flow": "code",
              "authorization": "https://mywebthingserver.com/oauth/authorize",
              "token": "https://mywebthingserver.com/oauth/token"
            }
          },
          "security": "oauth2",
          "properties": {
            "on": {
              "type": "boolean",
              "title": "On/Off",
              "description": "Whether the lamp is turned on",
              "forms": [{"href": "properties/on"}]
            },
            "level" : {
              "type": "integer",
              "title": "Brightness",
              "description": "The level of light from 0-100",
              "unit": "percent",
              "minimum" : 0,
              "maximum" : 100,
              "forms": [{"href": "properties/level"}]
            }
          },
          "actions": {
            "fade": {
              "title": "Fade",
              "description": "Fade the lamp to a given level",
              "input": {
                "type": "object",
                "properties": {
                  "level": {
                    "title": "Brightness",
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100,
                    "unit": "percent"
                  },
                  "duration": {
                    "title": "Duration",
                    "type": "integer",
                    "minimum": 0,
                    "unit": "milliseconds"
                  }
                }
              },
              "forms": [{"href": "actions/fade"}]
            }
          },
          "events": {
            "overheated": {
              "title": "Overheated",
              "data": {
                "type": "number",
                "unit": "degree celsius"
              },
              "description": "The lamp has exceeded its safe operating temperature",
              "forms": [{
                "href": "events/overheated",
                "subprotocol": "sse"
              }]
            }
          },
          "forms": [
            {
              "op": ["readallproperties", "writemultipleproperties"],
              "href": "properties"
            },
            {
              "op": ["observeallproperties", "unobserveallproperties"],
              "href": "properties",
              "subprotocol": "sse"
            },
            {
              "op": "queryallactions",
              "href": "actions"
            },
            {
              "op": ["subscribeallevents", "unsubscribeallevents"],
              "href": "events",
              "subprotocol": "sse"
            }
          ]
        }

Properties

`observeproperty`

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

Its op member contains the value observeproperty
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 Property resource.

In order to observe a property, a Consumer MUST follow the Server-Sent Events [[EVENTSOURCE]] specification to open a connection with the Web Thing at the URL of the Property 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 Property resource
Accept header set to text/event-stream
Connection header set to keep-alive

            GET /things/lamp/properties/level 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 levelSource = new EventSource('/things/lamp/properties/level');

If a Web Thing receives an HTTP request following the format above and the Consumer has permission to observe the corresponding property, then it MUST follow the Server-Sent Events [[EVENTSOURCE]] specification to maintain an open connection with the Consumer and push a property value to the Consumer each time the value of the specified property changes.

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 the value of the specified property changes while the Web Thing has an open connection with a Consumer, the Web Thing MUST send a property value 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 PropertyAffordance and populate the data field with the property value, serialized in JSON and following the data schema specified in the PropertyAffordance. The id field SHOULD be set to a unique identifier for the property change, for use when re-establishing a dropped connection (see below). It is RECOMMENDED that the identifier is a timestamp representing the time at which the property changed (see Date Format for date format constraints).

            event: level\n
            data: 42\n
            id: 2021-11-17T15:33:20.827Z\n\n

If the connection between the Consumer and Web Thing drops (except as a result of the unobserve 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 property changes which occurred since the last change specified by the Consumer in a Last-Event-ID header.

`unobserveproperty`

In order to stop observing a property, 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.

              levelSource.close();

`observeallproperties`

The URL of a properties resource to be used when observing changes to all properties of 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 observeallproperties
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 properties resource.

In order to observe changes to all properties of 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 properties 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 properties resource
Accept header set to text/event-stream
Connection header set to keep-alive

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

              const lampPropertiesSource = new EventSource('/things/lamp/properties');

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 new property values to the Consumer for all properties for which it has permission to observe.

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 a property changes while the Web Thing has an open connection with a Consumer, the Web Thing MUST send the new property value 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 PropertyAffordance and populate the data field with the new property value. The property data MUST follow the data schema specified in the PropertyAffordance 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). It is RECOMMENDED that the identifier is a timestamp representing the time at which the property changed (see Date Format for date format constraints).

            event: level\n
            data: 42\n
            id: 2021-11-17T15:33:20.827Z\n\n

If the connection between the Consumer and Web Thing drops (except as a result of the unobserveallproperties 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 property changes which occurred since the last change specified by the Consumer in a Last-Event-ID header.

`unobserveallproperties`

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

              lampPropertiesSource.close();

Events

The HTTP SSE 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

              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 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). It is RECOMMENDED that the identifier is a timestamp representing the time at which the event ocurred (see Date Format for date format constraints).

            event: overheated\n
            data: 90\n
            id: 2021-11-16T16:53:50.817Z\n\n

If the connection between the Consumer and Web Thing drops (except as a result of the unsubscribeevent 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 occurred 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]].

              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 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). It is RECOMMENDED that the identifier is a timestamp representing the time at which the event ocurred (see Date Format for date format constraints).

            event: overheated\n
            data: 90\n
            id: 2021-11-16T16:53:50.817Z\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 occurred 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();

HTTP Webhook Profile

This section defines the HTTP Webhook Profile, including a Protocol Binding for observing properties and listening for events using Webhooks.

The HTTP Webhook profile MAY be used in conjunction with the HTTP Basic Profile in order to provide operations to read and write properties and invoke, query and cancel actions.

The HTTP Webhook profile may be used as an alternative event mechanism to the HTTP SSE Profile.

In order to conform with the HTTP Webhook Profile, Web Things and Consumers MUST also conform with all of the assertions in the Common Constraints section.

Introduction

Webhooks can be used as a mechanism for Consumers to subscribe to events and observe properties of a Web Thing.

The mechanism is scalable and supports Consumers that receive events from multiple Things. Consumers implement a Webhook listener which handles notifications emitted by Things. For Webhook mechanism to function, the Consumer provides a server and client behavior. The client behavior is used for the initial subscription operation, whereas the server behavior is used to accept the events sent by the Thing. Thus, interactions can be initiated both by the Thing and the Consumer.

A Webhook is similar to a callback mechanism in programming languages. Consumers can subscribe to properties or events they are interested in by registering a listener with that endpoint. When the property change or the event condition occurs, the WebThing is notifying all listeners with a corresponding notification, which is transmitted over HTTP(s). The notification message contains details about the event, such as timestamp, event type, event source etc. in the data payload.

Depending on the deployment scenarios and integration requirements for existing consumers, it may be required to use specific data payload formats (e.g. Cloud Events). When a listener receives a notification message in a data payload, in many cases it just acknowledges the successful reception of the message. Additionally, it may provide a dataResponse payload, which provides a back-channel that can be used to communicate further details from the consumer to the WebThing.

Depending on the use case, a single listener for multiple things and multiple endpoints MAY be used.

To minimize network traffic, the same Consumer SHOULD NOT perform multiple subscriptions to the same endpoint.

Webhook Example

The following sequence diagram illustrates the flow of messages between a Consumer and a Web Thing when subscribing to, unsubscribing from and receiving events.

HTTP Webhook Profile - Sequence of operations and notifications

A similar flow applies to observing property changes.

The following example contains a snippet from a TD that illustrates how a Webhook event can be described.

TODO: Fix example - align with updated text.

              ...
  
              {
                  "events": {
                      "fireAlarm": {
                          "title": "Fire Alarm"
                          "description": "Critical Condition - Fire!",
                          "subscription": {
                              "type": "object",
                              "properties": {

                                "callbackURI": {
                                    "type": "string",
                                    "format": "uri",
                                    "description": "Callback URL provided by subscriber for Webhook notifications.",
                                    "writeOnly": true
                                },
                                ...
                              }
                          "data": {
                              "type": "boolean",
                              "description": "true, if the alert button has been pushed, false, if the button was armed again."
                          },
                          "dataResponse": {
                              "type": "string",
                              "description": "sprinkler status"
                          },
  
                          "cancellation": {
                            "type": "object",
                            "properties": {
                                "subscriptionID": {
                                    "type": "integer",
                                    "description": "subscription ID to cancel",
                                    "writeOnly": true
                                }
                            }
                        },
                        "forms": [
                              {
                                  "op": "subscribeevent",
                                  "href": "http://192.168.0.124:8080/events/fireAlarm/subscribe",
                                  "contentType": "application/json",
                                  "htv:methodName": "POST"
                              },
                              {
                                  "op": "unsubscribeevent",
                                  "href": "http://192.168.0.124:8080/events/fireAlarm/unsubscribe",
                                  "htv:methodName": "POST"
                              }
                          ]
                      },
                      "batteryLow": {
                          ...
                      }
                  }
              }

Identifier

In order to denote that a given Web Thing conforms to the HTTP Webhook Profile, its Thing Description MUST have a profile member [[wot-thing-description]] with a value of https://www.w3.org/2022/wot/profile/http-webhook/v1.

Note that the profile member is an array that may contain multiple profile entries, which indicates that a Web Thing conforms to all of the profiles in that array.

Message Format

Notification messages MUST comply with the following data schema.

TODO: Describe data and dataResponse schemas.

Protocol Binding

This section defines a protocol binding which describes how a Consumer and a Web Thing communicate using Webhook Events.

A Consumer or Web Thing conforming to the HTTP Webhook Profile MUST implement this protocol binding.

Properties

`observeproperty`

Its op member contains the value observeproperty
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 Content-Type header has a value of application/json
Its subprotocol member has a value of webhook

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

In order to observe a property, a Consumer MUST provide the listener URL in the request payload of the observeproperty operation of the Property resource.

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

Method set to POST
URL set to the URL of the Property resource
Content-Type header set to application/json
A body with a subscription request payload, serialized in JSON.

The subscription payload contains the URI for the notification listener in the field with the callbackURI key.

              POST /things/lamp/properties/level HTTP/1.1
              Host: mythingserver.com
              Content-Type: application/json
              {
                callbackURI: "http://myConsumer.com/myNotificationListener"
              }

If a Web Thing receives an HTTP request following the format above and the Consumer has permission to observe the corresponding property, then it MUST send a notification to the Consumer each time the value of the specified property changes.

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

Status code set to 201 Created
Content-Type header set to application/json
Location header set to the URL of the Event resource followed by a unique subscriptionId

              HTTP/1.1 201 Created
              Content-Type: application/json
              Location: /things/properties/level/1234-4544-1211

Whenever a change of the property occurs, the Web Thing MUST send the new value to the Consumer with an HTTP POST request with a Content-Type header set to application/json, in the payload format defined in section ["#http-webhook-profile-protocol-binding-notification-format"].

`unobserveproperty`

In order to stop observing a property, a Consumer MUST terminate the corresponding subscription with the Web Thing using the unobserveproperty operation of the Property resource.

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

Method set to DELETE
URL set to the subscription URL provided in the Location header of the response to the subscribe request

Properties

`observeproperty`

Its op member contains the value observeproperty
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 Content-Type header has a value of application/json
Its subprotocol member has a value of webhook

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

In order to observe a property, a Consumer MUST provide the listener URL in the request payload of the observeproperty operation of the Property resource.

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

Method set to POST
URL set to the URL of the Property resource
Content-Type header set to application/json
A body with a subscription request payload, serialized in JSON.

The subscription payload contains the URI for the notification listener in the field with the key callbackURI.

              POST /things/lamp/properties/level HTTP/1.1
              Host: mythingserver.com
              Content-Type: application/json
              {
                callbackURI: "http://myConsumer.com/myNotificationListener"
              }

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

Status code set to 201 Created
Content-Type header set to application/json
Location header set to the URL of the selected Property resource followed by a unique subscriptionId

              HTTP/1.1 201 Created
              Content-Type: application/json
              Location: /things/properties/level/1234-4544-1211

`unobserveproperty`

In order to stop observing a property, a Consumer MUST terminate the corresponding subscription with the Web Thing using the unobserveproperty operation of the Property resource.

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

Method set to DELETE
URL set to the subscription URL provided in the Location header of the response to the subscribe request

If a Web Thing receives an HTTP request following the format above and the Consumer has previously subscribed to the corresponding property with the subscriptionID provided, then the subscription is cancelled.

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

Status code set to 204 No Content

          HTTP/1.1 204 No Content

`observeallproperties`

The URL of a Properties resource to be used when observing changes to all properties of 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 observeallproperties
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 Content-Type header has a value of application/json
Its subprotocol member has a value of webhook

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

In order to observe changes to all properties of 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 properties resource
Content-Type header set to application/json
Request Payload contains a JSON object with a subscription request payload.

            POST /things/lamp/properties HTTP/1.1
            Host: mythingserver.com
            Content-Type: application/json
  
            {
              callbackURI: "http://myConsumer.com/myNotificationListener"
            }

If a Web Thing receives an HTTP request following the format above, then it MUST send notifications to the Consumer for all properties 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 201 Created
Content-Type header set to application/json
Location header set to the URL of the root Property resource followed by a unique subscriptionId

            HTTP/1.1 201 Created
            Content-Type: application/json
            Location: /things/lamp/properties/1234-4544-1211

Whenever a property changes while a Consumer is oberving Properties, the Web Thing MUST send the new value to the Consumer with an HTTP POST request with a Content-Type header set to application/json, and the payload format defined in section ["#http-webhook-profile-protocol-binding-notification-format"].

`unobserveallproperties`

In order to unobserve all properties, a Consumer MUST invoke the unobserveallproperties operation of the Property resource.

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

Method set to DELETE
URL set to the subscription URL provided in the Location header of the response to the subscribealleproperties request.

              DELETE /things/lamp/properties/1234-4544-1211 HTTP/1.1
              Host: mythingserver.com

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

Status code set to 204 No Content

              HTTP/1.1 204 No Content

Events

`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 Content-Type header has a value of application/json
Its subprotocol member has a value of webhook

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 provide the listener URL in the request payload of the subscribeevent operation of the Event resource.

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

Method set to POST
URL set to the URL of the Event resource
Content-type header set to application/json
A body with a subscription request payload, serialized in JSON.

The subscription payload contains the URI for the event message listener in the field with the callbackURI key.

              POST /things/lamp/events/overheated HTTP/1.1
              Host: mythingserver.com
              Content-Type: application/json
              {
                callbackURI: "http://myConsumer.com/myEventListener"
              }

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 send notification messages to the Consumer as events of the specified type occur.

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

Status code set to 201 Created
Content-Type header set to application/json
Location header set to the URL of the selected Event resource followed by a unique subscriptionId

              HTTP/1.1 201 Created
              Location: /things/lamp/events/overheated/1234-4544-1211

Whenever an event of the specified type occurs, the Web Thing MUST send event notifications to the Consumer using the event payload format defined in section ["#http-webhook-profile-protocol-binding-notification-format"].

`unsubscribeevent`

In order to unsubscribe to an event, a Consumer MUST terminate the corresponding subscription with the Web Thing using the unsubscribeevent operation of the Event resource.

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

Method set to DELETE
URL set to the subscription URL provided in the Location header of the response to the subscribe request

If a Web Thing receives an HTTP request following the format above and the Consumer has subscribed to the corresponding event with the subscriptionID provided, then the subscription is cancelled.

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

Status code set to 204 No Content

            HTTP/1.1 204 No Content

`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 Content-Type header has a value of application/json
Its subprotocol member has a value of webhook

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 send an HTTP request to the Web Thing with:

Method set to POST
URL set to the URL of the events resource
Content-Type header set to application/json
Request Payload contains a JSON object with a subscription request payload.

            POST /things/lamp/events HTTP/1.1
            Host: mythingserver.com
            Content-Type: application/json

            {
              callbackURI: "http://myConsumer.com/myEventListener"
            }

If a Web Thing receives an HTTP request following the format above, then it MUST send event messages 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 201 Created
Content-Type header set to application/json
Location header set to the URL of the Event resource followed by a unique subscriptionId

            HTTP/1.1 201 Created
            Content-Type: application/json
            Location: /things/lamp/events/overheated/1234-4544-1211

Whenever an event occurs, the Web Thing MUST send event data to the Consumer using the event payload format defined in section Notification Format.

`unsubscribeallevents`

In order to unsubscribe from all events, a Consumer MUST invoke the unsubscribeevent operation of the Event resource.

If a Web Thing receives an HTTP request following the format above and the Consumer has previously subscribed to the root event with the subscriptionID provided, then the subscription is cancelled.

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

Method set to DELETE
URL set to the subscription URL provided in the Location header of the response to the subscribeallevents request.

              DELETE /things/lamp/events HTTP/1.1
              Host: mythingserver.com

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

Status code set to 204 No Content

              HTTP/1.1 204 No Content

Webhook Notifications

Webhook notifications are sent by the WebThing to registered Consumers to notify them of value changes of properties or of events occuring on the WebThing.

An HTTP(s) connection to the notification listener of a Consumer MUST be initiated and managed by the Web Thing.

Notifications must be sent with an HTTP POST request with a Content-Type header set to application/json.

A Consumer MUST actively terminate the subscription with the event or property endpoint that is sending notifications of the Web Thing.

If a Consumer becomes unavailable and the Web Thing cannot successfully transmit notification messages to the consumer, it SHOULD attempt several retries at increasing intervals.

After the maximum number of retries was reached, the Web Thing MAY terminate the subscription without having received an explicit request corresponding to an unsubscribe or unsubscribeall operation.

When a notification message has been received, the Consumer MUST respond with an HTTP 200 OK response code, if the response contains a body.

If the response to an notification by the Consumer does not contain a payload, the Consumer MUST respond with an HTTP 204 No Content response code.

An (optional) JSON payload MAY be provided to return a response back to the Web Thing via the same communication channel.

Privacy Considerations

The privacy considerations of the WoT Architecture and WoT Thing Description MUST be adopted by compliant implementations.

Security Considerations

The security considerations of the WoT Architecture and WoT Thing Description MUST be adopted by compliant implementations.

Please see WoT Security Best Practices for implementation advice.

Introduction

Motivation

Use Cases and Requirements

Out-of-the-Box Interoperability

Technical Interoperability

Syntactic Interoperability

Semantic Interoperability

Organisational Interoperability

Terminology

Additional Definitions

Profiling Mechanism

Common Constraints

Accessibility

Units

Date Format

Security

Discovery

Links

Link Relation Types

Media Types for Link Targets

Errors

Default Language

HTTP Basic Profile

Identifier

Protocol Binding

Properties

readproperty

writeproperty

readallproperties

writemultipleproperties

Actions

invokeaction

ActionStatus object

Synchronous Action Response

Asynchronous Action Response

queryaction

cancelaction

queryallactions

HTTP SSE Profile

Identifier

Protocol Binding

Properties

observeproperty

unobserveproperty

observeallproperties

unobserveallproperties

Events

subscribeevent

unsubscribeevent

subscribeallevents

unsubscribeallevents

HTTP Webhook Profile

Introduction

Webhook Example

Identifier

Message Format

Protocol Binding

Properties

observeproperty

unobserveproperty

Properties

observeproperty

unobserveproperty

observeallproperties

unobserveallproperties

Events

subscribeevent

unsubscribeevent

subscribeallevents

unsubscribeallevents

Webhook Notifications

Privacy Considerations

Security Considerations

Recent Specification Changes

Changes from the FPWD published 24 November 2020

`readproperty`

`writeproperty`

`readallproperties`

`writemultipleproperties`

`invokeaction`

`ActionStatus` object

`queryaction`

`cancelaction`

`queryallactions`

`observeproperty`

`unobserveproperty`

`observeallproperties`

`unobserveallproperties`

`subscribeevent`

`unsubscribeevent`

`subscribeallevents`

`unsubscribeallevents`

`observeproperty`

`unobserveproperty`

`observeproperty`

`unobserveproperty`

`observeallproperties`

`unobserveallproperties`

`subscribeevent`

`unsubscribeevent`

`subscribeallevents`

`unsubscribeallevents`