diff --git a/index.html b/index.html index 0ae6fd0..1e819d4 100644 --- a/index.html +++ b/index.html @@ -198,8 +198,6 @@

Motivation for a Profile

- -

Introduction

The W3C WoT Architecture [[wot-architecture]] and the WoT @@ -386,18 +384,6 @@

Additional Definitions:

Synonym for WoT Core Profile.
- - - Core Data Model
@@ -416,60 +402,6 @@

Additional Definitions:

The Web of Things Thing Description as defined in [[wot-thing-description]].
- - -
@@ -516,996 +448,45 @@

Profiling Mechanism

+

WoT Core Profile

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

WoT Core Data Model

-

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

- -
-

General

- -

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

- -
-

Mandatory fields

-

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

-

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

-

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

-
- -
-

Length and Value Limits

-

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

-

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

-

-

- -

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

-

TODO: decide if multiple types and contexts are required.

- -

In this case the following section could be added:

-

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

-
- -

- -

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

-

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

- -
- - - -
-

Thing

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

Mandatory fields

-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
keywordtyperemarks
titlestringhuman readable documentation
idurn_typea globally unique urn of the - thing
descriptionstringhuman readable documentation
createddatehuman readable documentation
modifieddatehuman readable documentation
supporturn_typehuman readable documentation
securityarray of stringsimplified handling
versionVersionInfoclear 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: - -

- - - - - - - - - - - - - - - - - - - -
keywordtypeconstraints
descriptionhuman readable description
typestringone 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: - -

- - - - - - - - - - - - - - - - - - - - - - - - - -
keywordtypeconstraints
titlestringunique name among all - properties
descriptionstringhuman readable description
typestring - - 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: - -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
keywordtypeconstraint
constanyType - - MUST NOT be used - -
enumarray of simple type - - Values of enums MAY - only be simple types. Handling of any - type is too complex to implement - on resource constrained devices - -
formsarray of Forms - - The Array of Form - of each property MUST contain only a - single endpoint for each - operation readproperty - , writeproperty , observeproperty - , unobserveproperty. - -
formatstring - - If the field format - is used, only formats defined in - section 7.3.1-7.3.6 of - [[JSON-SCHEMA]] MAY be used. - -
oneOfstring - - The DataSchema field oneOf - does not make sense for properties - and MUST NOT be used. - -
uriVariablesMap 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. -

-
-
- + This section defines the Core Profile by describing: +
    +
  1. An identifier to denote that a given Thing Description + [[wot-thing-description]] conforms to the WoT Core Profile
    2. +
  2. A protocol binding for communicating with a Web Thing using JSON + [[JSON]] payloads over the HTTP [[HTTP11]] protocol, which all + conforming + Web Things + and + + Consumers [[wot-architecture]] MUST support
    3. +
  3. A list of + link + relation types [[wot-thing-description]] which a Web Thing MAY use and a + Consumer MUST support
    4. +
  4. A list of + security schemes + [[wot-thing-description]] which a Web Thing MAY use and a Consumer MUST + support
    5. +
  5. A list of discovery mechanisms [[wot-discovery]] which a Web Thing MAY + use and a Consumer MUST support
    6. +
- - -
-

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: - -

- - - - - - - - - - - - - - - - - - - - - - - - - -
keywordtypeconstraints
titlestringunique name among all actions
inputarray of DataSchema - - all elements of the subclasses - objectSchema and dataSchema MUST - only contain simple types. - -
outputarray 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: - -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
keywordtypeconstraint
formsarray of Forms - - The Array of Form - of each action MUST contain only a single - endpoint. - -
formatstring - - If the field format - is used, only formats defined in - section 7.3.1-7.3.6 of - [[JSON-SCHEMA]] MAY be used. - -
oneOfstring - - The DataSchema field oneOf - does not make sense for properties - and MUST NOT be used. - -
uriVariablesMap 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: - -

- - - - - - - - - - - - - - - - - - - - - - - - - -
keywordtypeconstraints
titlestringunique name among all events
descriptionstringhuman readable description
dataset of DataSchema instances in - a JSON objectonly 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: - -

- - - - - - - - - - - - - - - - - - - - -
keywordtypeconstraint
formsarray of Forms - - The Array of Form - of each event MUST contain only a single - endpoint. - -
uriVariablesMap 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: - -

- - - - - - - - - - - - - - - - - - - - - - - - - -
keywordtypeconstraints
titlestringunique name among all events
descriptionstringhuman readable description
dataset of DataSchema instances in - a JSON objectonly 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: - -

- - - - - - - - - - - - - - - - - - - - -
keywordtypeconstraint
securitystring or Array of string - - security at form - level MUST NOT be used. - -
scopesstring or Array of string - - scopes MUST NOT be - used. - -
-
-
- - - -
- -
TODO: Consider - selecting a defined set from [[RFC8288]].
- -

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

-
- - - -
-

Security

-

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

-

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

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

+ The name "Core Profile" is still under discussion + (see #21). +

-
-

Recommended Practice

-

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

-
-
+ +
+

Identifier

+

+ This section will define an identifier which can be included in a + Thing Description, using the profiling mechanism, to denote that the + Web Thing it describes conforms to the WoT Core Profile. +

@@ -1927,79 +908,48 @@

Error Responses

- -
-

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

-
- - + +
+

Security

+

+ The following is a list of security schemes which conformant Web Things + MAY use and which conformant Consumers MUST support: +

+

- -
-
-

Open Issues

- + +
+

Discovery

+

+ This section will define discovery mechanisms which conformant Web + Things MAY support and conformant Consumers MUST support. +

+