-
+ Additional Definitions:
- The core data model incorporates the data model defined by chapter 5 of
+ The core information model incorporates the information 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.
-
+ The normative rules defined by that model
+ are the baseline for the definition of the core information model
+ and are normative.
- The following rules are applicable to multiple
+ The profile enables to create generic consumers that can present a common UI
+ from the data of the Thing Description without further out of band information.
+ For this purpose a minimum set of information is required to be present in all Thing Descriptions.
+ A common way to display IoT device data are dashboards that are constructed from various UI widgets.
+ Typical elements are gauges, graphs, labels, histograms and labeled text fileds that display a value of properties.
+ Actions are typically triggered by labeled buttons.
+
+ It is common for UIs to have an information button or a hovering text box on fields,
+ that shows the human user an additional description, when needed.
+
+ The profile contains a few length limitations on fields to ensure that automaticall generated UIs
+ are possible.
+ For numeric values the range (minimum, maximum) should be provided to enable the display of graphs and gauges.
+ Values with have a metric unit should contain a unit field to ensure a common interpretation by consumers.
+
+ The following constraints and 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.
+ define interaction semantics and enable common processing of Web Things
+ that are created by different manufacturers and authors.
- 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
- 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.
- The length of
-
+ TODO: define constraints for - date and time values - units - geolocation - charset constraints for UI elementsProfiling 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
+ Information Model and a Protocol
+ Binding for [HTTP11].
+ WoT Core Information Model
General
-
Mandatory fields
title
- and
- description
- are MANDATORY for Things, Property Affordances,
+
+ The field
+ title is
+ MANDATORY for Things, Property Affordances,
Action Affordances, Event Affordances and Data
Schemas.
Length and Value Limits
+ Recommended fields
+
+ The field
+ description is
+ RECOMMENDED for Things, Property Affordances,
+ Action Affordances, Event Affordances and Data
+ Schemas.
+
id
- ,
- description
- and
- descriptions
- values is limited to 512 characters.
+ This recommendation enables generic UIs and provides additional
+ documentation for development and maintenance activities.
Type and Value Constraints
+ Length and Value Limits
+
The length of
title
and
titles
values is limited to 64 characters.
-
- - -
-
- Where a type permits using an
- 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 array of string
- or a
- string
- , an
- array of string
- MUST be used.
- @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.
+
+ The length of
+ id, description and
+ descriptions
+ values MUST NOT exceed to 512 characters.
-
-
+
To provide minimum interoperability, the
following metadata fields of a Thing MUST
be contained in a compliant Thing Description:
@@ -684,92 +638,105 @@ Mandatory fields
-
keyword
- type
- remarks
+ Keyword
+ Type
+ Constraints
+ Rationale
title
- string
- human readable documentation
+ stringmax length: 64 characters
+ generic UI
-
id
- urn_type
- a globally unique urn of the
- thing
+ base
+ anyURI
+ discovery
-
- description
- string
- human readable documentation
-
-
- created
- date
- human readable documentation
-
-
- modified
- date
- human readable documentation
-
-
support
- urn_type
- human readable documentation
+ id
+ urn_typea Globally unique urn of the
+ thing
+ large scale deployments
-
security
- array of string
- simplified handling
+ profile
+ stringvalue: "https://www.w3.org/2021/wot/profile/core-json-http11"
version
- VersionInfo
- clear versioning, easy to
- compare different TDs
+ VersionInfosemantic versioning as defined by [SEMVER]
+ enforce versioning, easy to
+ distinguish different versions of the same TD
It is RECOMMENDED to use the value - "" for strings, where the - value cannot be determined.
++ + The following metadata fields of a Thing SHOULD be contained in a compliant + Thing Description: + +
+| Keyword | +Type | +Constraints | +Rationale | +
|---|---|---|---|
| description | +string |
+ Descriptive text that explains the title. | +generated UI, maintenance, developer documentation | +
| created | +date |
+ Creation date of the TD | +maintenance and developer documentation | +
| modified | +date |
+ Date when the TD was last modified | +maintenance and developer documentation | +
| support | +anyURI |
+ Contact information to obtain further help on the TD. + This could be a company website or an email address of customer support. | +maintenance and developer documentation | +
- + 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. - -
-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.
-
- 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. -
+ +format field permits to define new schema types.
+ The profile needs to define, how mismatching types
+ that are passed in as parameters or returned objects
+ are handled, i.e. specify an error behavior.
- - The following fields MUST be contained in a - DataSchema: - -
-| keyword | -type | -constraints | -
|---|---|---|
| description | -human readable description | -|
| type | -string | -one of boolean, integer, number, - string, array or object | -
-
- The values
- object
- ,
- array MAY only be used at the top level of a Data Schema.
-
-
- The type value MUST NOT be null .
-
-
PropertyAffordance
- class of section 5.3.1.3 of the WoT Thing Description Specification.
+ class of the WoT Thing Description Specification.
-
+
The following property fields MUST be contained
in the
- 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
-
-
+
The following additional constraints MUST be
applied to the Property Affordances of a Thing
Description conforming to the Core
@@ -963,97 +830,113 @@
+
+ For a single protocol the
+
+ The value of If multiple endpoints for the same protocol are present,
+ a common selection algorithm has to be defined.
+ This may imply invoking form elements in sequence with
+ a trial and error method that can lead to significant
+ delays due to timeout handling obligations.
+
+ Combination of operations are ambiguous and have very
+ complex interaction semantics.
+ properties
@@ -898,36 +784,34 @@ Mandatory fields
@@ -936,24 +820,7 @@
-
keyword
- type
- constraints
+ Keyword
+ Type
+ Constraints
+ Rationale
- title
- string
+ stringunique name among all
properties
-
-
description
- string
- human readable description
+ unambigous UI labels
type
- string
+ string
-
- one of
+ boolean ,
- string ,
- number , integer
- , object or
- array . The type value
+
+ one of boolean,
+ string ,
+ number , integer
+ , object or
+ array . The type value
null MUST NOT be used.
well defined types
Mandatory fields
Additional Constraints
array
- or
- object
- elements. It is RECOMMENDED to keep the nesting
- of these elements below 4.
-
- Additional Constraints
-
-
- keyword
- type
- constraint
+ Keyword
+ Type
+ Constraint
+ Rationale
-
- const
- anyType
-
-
- MUST NOT be used
-
-
-
-
enum
- array of simple type
-
-
- Values of enums MAY
- only be simple types. Handling of any
- type is too complex to implement
- on resource constrained devices
-
-
-
forms
- array of Forms
+ array of Forms
-
- The
+ Array of Form
+ Array of Form
of each property MUST contain only a
single endpoint for each
- operation readproperty
- , writeproperty , observeproperty
- , unobserveproperty.
+ operation readproperty,
+ writeproperty, observeproperty,
+ unobserveproperty.
+
+ op MUST be a single value.
+ Arrays with combinations of these values are NOT PERMITTED.
+
- format
- string
+ string
-
+
If the field
- format
is used, only formats defined in
section 7.3.1-7.3.6 of
- [[JSON-SCHEMA]] MAY be used.
-
-
-
oneOf
- string
-
-
- The DataSchema field
+ oneOf
- does not make sense for properties
- and MUST NOT be used.
+ [[JSON-SCHEMA]] MUST be used.
Predictive finite set of choices.
-
uriVariables
Map of DataSchema
-
+
uriVariables MUST
NOT be used.
+ The semantic meaning of URI variables cannot be described in a TD in an unambiguous way.
default and
+ oneOf
+ are undefined for properties and MUST NOT be used.
+
+
+
+ The following property fields SHOULD be contained in the properties
+ element of a Profile compliant TD:
+
+
| Keyword | +Type | +Constraints | +Rationale | +
|---|---|---|---|
| description | +string |
+ max length | +generated UI, maintenance, developer documentation | +
+
It is highly RECOMMENDED to always specify a
- unit
- , if a value has a metric.
-
+ 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 @@ -1069,17 +952,18 @@
bin
,
-
to indicate how the value should be
- interpreted. It is strongly RECOMMENDED to use
+ interpreted.
+
+ It is strongly RECOMMENDED to use
the values
-
hex
,
oct
or
bin
- in this case to achieve interoperability.
+ for non-decimal numeric types to achieve interoperability.
+
ActionAffordance
- class of section 5.3.1.4 of the WoT Thing Description Specification.
+ class of the WoT Thing Description Specification.
-
+
The following fields MUST be contained in an
action element of an Core Profile compliant TD:
@@ -1106,38 +990,18 @@
- The elements of the DataSchema subclasses
- ArraySchema and ObjectSchema for the fields
-
-
+
The following additional constraints MUST be
applied to the Interaction Affordances of a Thing
Description conforming to the Core
@@ -1171,9 +1021,10 @@
+ For a single protocol the
+
+ The value of If multiple endpoints for the same protocol would be present,
+ a common selection algorithm has to be defined.
+ This may imply invoking form elements in sequence with
+ a trial and error method that can lead to significant
+ delays due to timeout handling obligations.
+
+ Combination of operations are ambiguous and have very
+ complex interaction semantics.
+ TODO: - no optional parameters - timeoutMandatory fields
@@ -1145,23 +1009,9 @@
-
keyword
- type
- constraints
+ Keyword
+ Type
+ Constraints
+ Rationale
- title
- string
+ stringunique name among all actions
-
-
- input
- array of DataSchema
-
-
- all elements of the subclasses
- objectSchema and dataSchema MUST
- only contain simple types.
-
-
-
-
output
- array of DataSchema
-
-
- all elements of the subclasses
- objectSchema and dataSchema MUST
- only contain simple types.
-
-
+ unambigous UI labels
Mandatory fields
Additional Constraints
- 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.
- Additional Constraints
-
@@ -1181,273 +1032,79 @@ keyword
- type
- constraint
+ Keyword
+ Type
+ Constraint
+ Rationale
Additional Constraints
forms
array of Forms
-
- The
-
- Array of Form
- of each action MUST contain only a single
- endpoint.
-
-
-
- format
- string
-
-
- If the field
- format
- is used, only formats defined in
- section 7.3.1-7.3.6 of
- [[JSON-SCHEMA]] MAY be used.
-
+ array of Form
+ of each property MUST contain only a
+ single endpoint for each
+ operation readproperty,
+ writeproperty, observeproperty,
+ unobserveproperty.
+
+ op MUST be a single value.
+ Arrays with combinations of these values are NOT PERMITTED.
+
+
-
- oneOf
- string
-
-
- The DataSchema field
- oneOf
- does not make sense for properties
- and MUST NOT be used.
-
-
-
+ uriVariables
- Map of DataSchema
-
-
- uriVariables MUST
- NOT be used.
-
-
+
+ format
+ string
+
+ If the field
+ format
+ is used, only formats defined in
+ section 7.3.1-7.3.6 of
+ [[JSON-SCHEMA]] MUST be used.
+
+ Predictive finite set of choices.
+
+
uriVariables
+ Map of DataSchema
+
+
+ uriVariables MUST
+ NOT be used.
+
+ The semantic meaning of URI variables cannot be described in a TD in an unambiguous way.
+
+ Recommended Practice
- const, default,
+ unit, oneOf and enum
+ are undefined for actions and MUST NOT be used.
+
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.
-- - The following fields MUST be present in an event - element of a Core TD: - -
-| keyword | -type | -constraints | -
|---|---|---|
| title | -string | -unique name among all events | -
| description | -string | -human readable description | -
| data | -set of DataSchema instances in - a JSON object | -only the DataSchema subclasses - booleanSchema, IntegerSchema, - NumberSchema, StringSchema are - permitted | -
- - The following additional constraints MUST be - applied to the Event Affordances of a WoT Thing - Description conforming to the profile: - -
-| keyword | -type | -constraint | -
|---|---|---|
| forms | -array of Forms | -
-
- The Array of Form
- of each event MUST contain only a single
- endpoint.
-
- |
-
| uriVariables | -Map of DataSchema | -
-
- uriVariables MUST
- NOT be used.
-
- |
-
- - A Thing may provide more than one event - mechanism to enable a variety of consumers. - -
-- - The following fields MUST be present in a form - element of a Core TD: - -
-| keyword | -type | -constraints | -
|---|---|---|
| title | -string | -unique name among all events | -
| description | -string | -human readable description | -
| data | -set of DataSchema instances in - a JSON object | -only the DataSchema subclasses - booleanSchema, IntegerSchema, - NumberSchema, StringSchema are - permitted | -
- - The following additional constraints MUST be - applied to the Form elements of a WoT Thing - Description conforming to the Core - profile: - -
-| keyword | -type | -constraint | -
|---|---|---|
| security | -string or Array of string | -
-
- security at form
- level MUST NOT be used.
-
- |
-
| scopes | -string or Array of string | -
-
- scopes MUST NOT be
- used.
-
- |
-
-
+
+
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.
@@ -1484,7 +1143,7 @@
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:
@@ -1510,7 +1169,7 @@
This section defines a protocol binding which describes how a
Consumer
TODO
THIS SECTION STILL NEEDS TO BE REWORKED.Security
Recommended Practice
Protocol Binding
+ HTTP 1.1 Protocol Binding