diff --git a/index.html b/index.html index 493aca2..048f243 100644 --- a/index.html +++ b/index.html @@ -150,15 +150,15 @@
  • In addition, it defines a HTTP Basic Profile of the Thing Description, which contains protocol binding rules for HTTP. -

    The normative HTTP Basic Profile is complemented by two - informative profiles for events: The HTTP SSE Profile +

    The normative HTTP Basic Profile is complemented by two + informative profiles for events: The HTTP SSE Profile and the HTTP Webhook Profile. - +

    In the current version of this document these event bindings are provided in informative sections, to illustrate how these event mechanisms could be supported in other profiles.

    -

    It is planned that future versions of this document normatively define +

    It is planned that future versions of this document normatively define these event mechanisms.

    @@ -183,7 +183,7 @@ hold only for the HTTP Basic Profile subset.

    Future versions of this document may contain other profiles, - e.g. a profile for digital twins and a profile for resource constrained devices.

    + e.g. a profile for digital twins and a profile for resource constrained devices.

    Motivation for a Profile

    @@ -478,8 +478,8 @@

    Additional Definitions

    Profile
    A technical specification which provides a set of assertions such that - any Consumer which conforms with the those - assertions is out-of-the-box + any Consumer which conforms with the those + assertions is out-of-the-box interoperable with any Thing which also conforms with those assertions.
    @@ -562,12 +562,12 @@

    Accessibility

    users with disabilities.

    - It is REQUIRED to provide a title that can be automatically rendered in a non-visual way + 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 + 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.

    @@ -575,22 +575,22 @@

    Accessibility

    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 + 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, + 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) + It is highly RECOMMENDED to use the metric system (SI units) for devices that are used in global deployments.

    @@ -600,7 +600,7 @@

    Units

    Date Format

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

    @@ -645,22 +645,22 @@ 

    Security

    Conformant Consumers MUST support all of these security schemes.

    - +

    A Thing MAY implement multiple security schemes.

    - +

    - Conformant Consumers MUST support security bootstrapping for all + 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 + Conformant Things which require authentication in order to retrieve their Thing Description MUST implement security bootstrapping, as - defined in + defined in Security Bootstrapping in the WoT Discovery [[wot-discovery]] specification.

    @@ -670,7 +670,7 @@

    Security

    Discovery

    - A Web Thing's Thing Description [[wot-thing-description]] MUST be + A Web Thing's Thing Description [[wot-thing-description]] MUST be retrievable from a Thing Description Server [[wot-architecture11]] using an HTTP @@ -687,7 +687,7 @@

    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. @@ -698,7 +698,7 @@

    Links

    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. @@ -800,7 +800,7 @@

    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 + 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. @@ -868,7 +868,7 @@

    Media Types for Link Targets

    - + 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 @@ -877,7 +877,7 @@

    Media Types for Link Targets

    - + 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 @@ -886,7 +886,7 @@

    Media Types for Link Targets

    - + If a Consumer encounters a link with "rel": "collection" and "type": "application/td+json" and is capable of rendering a @@ -976,7 +976,7 @@

    HTTP Basic Profile

    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 + Common Constraints section.

    @@ -1132,7 +1132,7 @@
    readproperty
  • URL set to the URL of the Property resource
  • Accept header set to application/json
  • - +
                   GET /things/lamp/properties/on HTTP/1.1
    @@ -1452,32 +1452,32 @@ 
    invokeaction

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

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

    - - If the synchronous member of the + If the synchronous member of the ActionAffordance - [[wot-thing-description11]] is undefined then the Web - Thing MAY respond with either a + [[wot-thing-description11]] is undefined then the Web + Thing MAY respond with either a Synchronous Action Response or Asynchronous Action Response. @@ -1565,7 +1565,7 @@

    ActionStatus object
    @@ -1592,8 +1592,8 @@
    ActionStatus object
    @@ -2223,8 +2223,8 @@
    observeproperty
    It is RECOMMENDED that the identifier is a timestamp representing the time at which the - property changed (see - Date Format for date format + property changed (see + Date Format for date format constraints).

    @@ -2382,8 +2382,8 @@ 
    observeallproperties
    below). It is RECOMMENDED that the identifier is a timestamp - representing the time at which the property changed (see - Date Format for date format + representing the time at which the property changed (see + Date Format for date format constraints).

    @@ -2557,8 +2557,8 @@ 
    subscribeevent
    below). It is RECOMMENDED that the identifier is a timestamp - representing the time at which the event ocurred (see - Date Format for date format + representing the time at which the event ocurred (see + Date Format for date format constraints).

    @@ -2805,17 +2805,17 @@ 

    Introduction

    A Webhook is similar to a callback mechanism in programming languages. Consumers can subscribe to events they are interested in by registering a listener with the event endpoint. When the event condition occurs, the WebThing - is notifying all listeners with a corresponding event message, which is transmitted over HTTP(s). - The event message contains details about the event, such as timestamp, event type, + is notifying all listeners with a corresponding event message, which is transmitted over HTTP(s). + The event 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 + 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 an event message in a data payload, in many cases it just acknowledges the + When a listener receives an event message in a data payload, in many cases it just acknowledges the successful reception of the event. - 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. -

    + 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 event types MAY be used. @@ -2928,7 +2928,7 @@

    Message Format

    TODO: Describe data and dataResponse schemas.

    - +

    Protocol Binding

    @@ -2999,7 +2999,7 @@

    subscribeevent

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

    href The [[URL]] of an ActionStatus resource which - can be used by queryaction and + can be used by queryaction and cancelaction operations, the URI scheme [[RFC3986]] of which MUST resolve to @@ -1580,8 +1580,8 @@
    ActionStatus object
    timeRequested A timestamp indicating the time at which the Thing received - the request to execute the action. (See - Date Format for date format + the request to execute the action. (See + Date Format for date format constraints). optional 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 + execute the action. (See + Date Format for date format constraints). optional