From 307adf18f3e73c08a8f588b128c1e080c8d9b5b2 Mon Sep 17 00:00:00 2001
From: Ben Francis
Date: Fri, 23 Apr 2021 19:17:47 +0100
Subject: [PATCH] Add event log operations - fixes #892
---
index.html | 827 +++++++++++++++++++++++++++--------------------------
1 file changed, 417 insertions(+), 410 deletions(-)
diff --git a/index.html b/index.html
index 8b410e2a6..3895e34e3 100644
--- a/index.html
+++ b/index.html
@@ -341,30 +341,30 @@
-
+
- This document describes a formal model and a common representation
- for a Web of Things (WoT) Thing Description 1.1.
+ This document describes a formal model and a common representation
+ for a Web of Things (WoT) Thing Description 1.1.
A Thing Description describes the metadata and interfaces of Things ,
where a Thing is an abstraction of a physical or virtual entity that
- provides interactions to and participates in the Web of Things.
- Thing Descriptions provide a set of interactions based on a small vocabulary
- that makes it possible both to integrate diverse devices and
- to allow diverse applications to interoperate.
+ provides interactions to and participates in the Web of Things.
+ Thing Descriptions provide a set of interactions based on a small vocabulary
+ that makes it possible both to integrate diverse devices and
+ to allow diverse applications to interoperate.
Thing Descriptions, by default, are encoded in a JSON format that also allows
JSON-LD processing. The latter provides a powerful foundation to represent
knowledge about Things in a machine-understandable way.
A Thing Description instance can be hosted by the Thing itself or hosted
externally when a Thing has resource restrictions (e.g., limited memory space)
- or when a Web of Things-compatible legacy device is retrofitted
+ or when a Web of Things-compatible legacy device is retrofitted
with a Thing Description.
- This specification describes a superset of the features defined in Thing Description 1.0 [[WOT-THING-DESCRIPTION]].
- Unless otherwise specified, documents created with version 1.0 of this specification remain
+ This specification describes a superset of the features defined in Thing Description 1.0 [[WOT-THING-DESCRIPTION]].
+ Unless otherwise specified, documents created with version 1.0 of this specification remain
compatible with Thing Description 1.1.
@@ -405,17 +405,17 @@ Introduction
that indicate how the Thing can be used,
schemas for the data
exchanged with the Thing for machine-understandability,
- and, finally, Web links to
+ and, finally, Web links to
express any formal or informal relation to other Things or documents on the Web.
{
@@ -590,11 +590,11 @@ Introduction
-
-
+
Security Vocabulary Definitions
@@ -1568,8 +1571,8 @@ Security Vocabulary Definitions
This specification provides a selection of well-established security mechanisms
that are directly built into protocols eligible as Protocol Bindings for W3C WoT
or are widely in use with those protocols.
- The current set of HTTP security schemes is partly based on
- OpenAPI 3.0.1 (see also [[?OPENAPI]]).
+ The current set of HTTP security schemes is partly based on
+ OpenAPI 3.0.1 (see also [[?OPENAPI]]).
However while the HTTP security schemes, Vocabulary , and syntax
given in this specification share many similarities with OpenAPI, they are not compatible.
@@ -1577,7 +1580,7 @@ Security Vocabulary Definitions
SecurityScheme
Metadata describing the configuration of a security
mechanism. The value assigned to the name
- scheme
MUST be defined within a
+ scheme
MUST be defined within a
Vocabulary
included in the Thing Description ,
either in the standard Vocabulary defined
@@ -1586,9 +1589,9 @@ Security Vocabulary Definitions
Extension.
For all security schemes,
- any private keys, passwords, or other sensitive information directly providing access
- should be shared and stored out-of-band and MUST NOT be stored in the TD.
- The purpose of a TD is to describe how to access a Thing if and only if a Consumer
+ any private keys, passwords, or other sensitive information directly providing access
+ should be shared and stored out-of-band and MUST NOT be stored in the TD.
+ The purpose of a TD is to describe how to access a Thing if and only if a Consumer
already has authorization, and is not meant be used to grant that authorization.
Security schemes generally may require additional authentication
@@ -1602,15 +1605,15 @@
Security Vocabulary Definitions
in a header provided by the protocol, with the name of the header
provided by the value of name
.
query
:
- The parameter will be appended to the URI as a query parameter, with the name of the
+ The parameter will be appended to the URI as a query parameter, with the name of the
query parameter provided by name
.
body
:
- The parameter will be provided in the body of the request payload, with the data schema element
+ The parameter will be provided in the body of the request payload, with the data schema element
used provided by name
.
- When used in the context of a
- body
security information location, the value of name
- MUST be in the form of a JSON pointer [[!RFC6901]] relative to
- the root of the input DataSchema
for each interaction it is used with.
+ When used in the context of a
+ body
security information location, the value of name
+ MUST be in the form of a JSON pointer [[!RFC6901]] relative to
+ the root of the input DataSchema
for each interaction it is used with.
Since this value is not a fragment identifier, and is not relative to the root of the TD but
to whichever data schemas the security scheme is bound to, this value should not start with #
;
it is a "pure" JSON pointer.
@@ -1622,51 +1625,51 @@ Security Vocabulary Definitions
When an element
of a data schema indicated by a JSON pointer indicated in a body
locator
does not already exist in the indicated schema, it
- MUST
+ MUST
be possible to insert the indicated element
at the location indicated by the pointer.
The JSON pointer
- used in the body
locator
- MAY
- use the "-
" character to indicate a non-existent array element when
+ used in the body
locator
+ MAY
+ use the "-
" character to indicate a non-existent array element when
it is necessary to insert an element after the last element of an existing array.
The element referenced
- (or created) by a
+ (or created) by a
body
security information location
- MUST be required and of type "string
".
+ MUST be required and of type "string
".
If name
is not given, it is assumed the entire body
is to be used as the security parameter.
cookie
:
- The parameter is stored in a cookie identified by the value of
+ The parameter is stored in a cookie identified by the value of
name
.
uri
:
The parameter is embedded in the URI itself, which is encoded in the
relevant interaction using a URI template variable defined by the value of name
.
- This is more general than the query
mechanism but more complex.
- The value uri
- SHOULD be specified
+ This is more general than the query
mechanism but more complex.
+ The value uri
+ SHOULD be specified
for the name in
in a security scheme only if
- query
is not applicable.
+ query
is not applicable.
The URIs provided
in interactions where a security scheme using uri
as the value for in
MUST be a URI template including the defined variable.
-
+
If multiple parameters are needed for a security scheme, repeat the security scheme definition for
each parameter and combine them using a combo
security scheme and allOf
.
In some cases parameters may not actually be secret but a user may wish to leave them
out of the TD to help protect privacy. As an example of this, some security mechanisms
- require both a client identifier and a secret key. In theory, the client identifier is
+ require both a client identifier and a secret key. In theory, the client identifier is
public however it may be hard to update and pose a tracking risk. In such a case it can
be provided as an additional security parameter so it does not appear in the TD.
- The names of URI variables
- declared in a SecurityScheme
- MUST be distinct from all other URI variables
+ The names of URI variables
+ declared in a SecurityScheme
+ MUST be distinct from all other URI variables
declared in the TD.
Vocabulary term Description Assignment Type @type
JSON-LD keyword to label the object with semantic tags (or types). optional string
or Array of string
description
Provides additional (human-readable)
information based on a default language. optional string
descriptions
Can be used to support (human-readable)
@@ -1690,7 +1693,7 @@ Security Vocabulary Definitions
"nosec"), indicating there is no authentication or
other mechanism required to access the resource.
ComboSecurityScheme
This section is at risk.
A combination of other security schemes identified by the Vocabulary Term combo
(i.e., "scheme": "combo"
). Elements of this scheme define various ways in which other named schemes defined in securityDefinitions
, including other ComboSecurityScheme
definitions, are to be combined to create a new scheme definition. Exactly one of either oneOf
or allOf
MUST be included. Only security scheme definitions which can be used together can be combined with allOf
. For example, it is not possible in general to combine different OAuth 2.0 flows together using allOf
unless one applies to a proxy and one to the endpoint. Note that when multiple named security scheme definitions are listed in a security
field the same semantics apply as in an allOf
combination (and the same limitations on allowable combinations). The oneOf
combination is equivalent to using different security schemes on forms that are otherwise identical. In this sense a oneOf
scheme is not an essential feature but it does avoid redundancy in such cases.
Vocabulary term Description Assignment Type oneOf
Array of two or more strings identifying other named security scheme definitions, any one of which, when satisfied, will allow access. Only one may be chosen for use. mandatory string
or Array of string
-allOf
Array of two or more strings identifying other named security scheme definitions, all of which must be satisfied for access. mandatory string
or Array of string
The
+
allOf
Array of two or more strings identifying other named security scheme definitions, all of which must be satisfied for access. mandatory string
or Array of string
The
ComboSecurityScheme may be applied recursively to generate Boolean expressions for combinations of security schemes. One use case for this is when multiple security schemes are needed for a proxy in combination with multiple security schemes for an endpoint. Suppose for example a proxy accepts either schemes A or B, and then the endpoint accepts either C or D. Then the possible combinations are AC, AD, BC, and BD. These could be expressed directly at the Form
level but would require four-fold redundancy. Instead, three combo
nodes can be used to combine the four leaf schemes in the correct way into a single scheme. It is not clear however if other use cases exist for deeper expression trees and if not, we may consider limiting the recursion depth to two.
BasicSecurityScheme
Basic Authentication [RFC7617 ]
security configuration identified by the Vocabulary Term basic
(i.e.,
@@ -1713,12 +1716,12 @@
Security Vocabulary Definitions
APIKeySecurityScheme
API key authentication security configuration
identified by the Vocabulary Term
apikey
(i.e., "scheme":
- "apikey"
).
+ "apikey").
This scheme is to be used when the access token is opaque,
for example when a key in an unknown or proprietary format is provided by a cloud service provider.
In this case the key may not be using a standard token format.
- This scheme indicates that the key provided by the service provider
- needs to be supplied as part
+ This scheme indicates that the key provided by the service provider
+ needs to be supplied as part
of service requests using the mechanism indicated by the "in"
field.
Vocabulary term Description Assignment Type name
Name for query, header, cookie, or uri
parameters. optional string
in
Specifies the location of security
@@ -1753,7 +1756,7 @@ Security Vocabulary Definitions
identified by the Vocabulary Term
psk
(i.e., "scheme":
"psk"
).
- This is meant to identify that a standard is used for pre-shared keys such as TLS-PSK [[rfc4279]],
+ This is meant to identify that a standard is used for pre-shared keys such as TLS-PSK [[rfc4279]],
and that the ciphersuite used for keys will be established during protocol negotiation.Vocabulary term Description Assignment Type identity
Identifier providing information which can be
used for selection or confirmation. optional string
OAuth2SecurityScheme
OAuth 2.0 authentication security configuration
@@ -1784,7 +1787,7 @@
Security Vocabulary Definitions
defined in [[!RFC8628]]. The mandatory elements for each flow are summarized in the
following table:
Element code
client
device
authorization
mandatory omit mandatory; refers to device authorization endpoint token
mandatory mandatory mandatory refresh
optional optional optional
- Note that the OAuth2SecurityScheme
class definition lists these elements as "optional".
+
Note that the OAuth2SecurityScheme
class definition lists these elements as "optional".
In fact whether they are mandatory or not depends on the flow. The token
element is listed as optional even though it is mandatory for all predefined flows
since it might not be mandatory for some flows defined in an extension. We should
@@ -1807,7 +1810,7 @@
Security Vocabulary Definitions
however an alternative design where there is a separate element,
device_authorization
, which MUST be included for the device
flow (and then the regular authorization endpoint then MUST NOT be used).
-
+
Link relations can be used to describe relations such as to other Things (e.g., a Switch Thing controls a Lamp Thing), to a specific kind of Thing Models (e.g., a Thing Description
- is an instance of a specific Thing Model), or to further documentations information (e.g., device manuel of a Thing). It is recommended to reuse existing and established
+ is an instance of a specific Thing Model), or to further documentations information (e.g., device manuel of a Thing). It is recommended to reuse existing and established
Link Relation definitions from IANA.
In the following a best practice relation type table is introduced that is recommended to use within WoT Thing Description
- or Thing Model instances.
+ or Thing Model instances.
- Value
+ Value
Occurrence
Explanation
Source of value origin
@@ -1900,7 +1903,7 @@ Hypermedia Controls Vocabulary Definitions
W3C WoT Thing Model
-
+
manifest
@@ -2017,7 +2020,7 @@ Hypermedia Controls Vocabulary Definitions
metadata that is only valid for the primary response
messages. optional ExpectedResponse
additionalResponses
This optional term can be used if additional expected responses
- are possible, e.g. for error reporting. Each additional response needs to be
+ are possible, e.g. for error reporting. Each additional response needs to be
distinguished from others in some way (for example, by specifying
a protocol-specific error code), and may also have its own data schema. optional AdditionalExpectedResponse
or Array of AdditionalExpectedResponse
subprotocol
Indicates the exact mechanism by which an
@@ -2043,7 +2046,7 @@ Hypermedia Controls Vocabulary Definitions
the correct form for the operation required. op can
be assigned one or more interaction verb(s) each
representing a semantic intention of an
- operation. optional any type (one of readproperty
, writeproperty
, observeproperty
, unobserveproperty
, invokeaction
, subscribeevent
, unsubscribeevent
, readallproperties
, writeallproperties
, readmultipleproperties
, writemultipleproperties
, observeallproperties
, or unobserveallproperties
)
Possible values for the contentCoding
+ operation.
optional any type (one of readproperty
, writeproperty
, observeproperty
, unobserveproperty
, invokeaction
, subscribeevent
, unsubscribeevent
, readeventlog
, readallproperties
, writeallproperties
, readmultipleproperties
, writemultipleproperties
, observeallproperties
unobserveallproperties
or readalleventlogs
) Possible values for the contentCoding
property can be found, e.g., in the
IANA HTTP content coding registry .
@@ -2061,7 +2064,7 @@ Hypermedia Controls Vocabulary Definitions
arbitrarily set by servients.
The optional response
name-value pair can
be used to provide metadata for the expected response
- message.
+ message.
With the core vocabulary, it only includes
content type information, but TD Context Extensions could
be applied. Hypermedia Controls Vocabulary Definitions
that the content type of the response is equal to the
content type assigned to the Form instance. Note
that contentType
within an
- ExpectedResponse
+ ExpectedResponse
Class does not
have a Hypermedia Controls Vocabulary Definitions
One example of this is error responses but in some cases
there might also be additional successful responses.
In this case the response
name-value pair
- is still used for the primary response but
+ is still used for the primary response but
additionalResponses
may also be provided,
whose value is an array of AdditionalExpectedResponse
objects.
@@ -2093,7 +2096,7 @@ Hypermedia Controls Vocabulary Definitions
protocol-specific settings such as error code header values.
Each additional response may also have a data schema
which can differ from the normal output data schema for the
- interaction.
+ interaction.
In some use cases, input and output data might be
represented in a different form, for instance an Action
@@ -2105,7 +2108,7 @@
Hypermedia Controls Vocabulary Definitions
the expected response differs from the content type of
the form, the Form
instance MUST include a name-value
- pair with the name response
.
+ pair with the name response
.
For instance, an ActionAffordance
could only
accept application/json
for its input data,
while it will respond with an image/jpeg
@@ -2124,14 +2127,14 @@ Hypermedia Controls Vocabulary Definitions
the form, the Form
instance MUST include an entry in the array
associated with the name additionalResponses
- that includes a value for the name contentType
.
+ that includes a value for the name contentType
.
If the data schema of
an additional expected response differs from the output data schema of
the interaction, the Form
instance MUST include an entry in the array
associated with the name additionalResponses
that
- includes a value for the name schema
.
+ includes a value for the name schema
.
ExpectedResponse
Communication metadata describing the expected
response message for the primary response.
Vocabulary term Description Assignment Type contentType
Assign a content type based on a media type
@@ -2344,19 +2347,19 @@ TD Representation Format
in order to streamline semantic evaluation.
Hence, the TD representation format can be processed either as raw JSON
or with a JSON-LD 1.1 processor
- (for details about semantic processing, please refer to
+ (for details about semantic processing, please refer to
and the documentation under the namespace IRIs, e.g.,
https://www.w3.org/2019/wot/td ).
In order to support interoperable internationalization,
-TDs MUST be serialized according to the
+TDs MUST be serialized according to the
requirements defined in Section 8.1 of RFC8259 [[!RFC8259]] for open ecosystems.
In summary, this requires the following:
TDs MUST be encoded using UTF-8 [[!RFC3629]].
-Implementations MUST NOT
+Implementations MUST NOT
add a byte order mark (U+FEFF) to the beginning of a TD document.
TD Processors MAY ignore
the presence of a byte order mark rather than treating it as an error.
@@ -2378,7 +2381,7 @@ Mapping to JSON Types
Every Simple Type mentioned in
(i.e., string
, anyURI
,
dateTime
, integer
, unsignedInt
,
- double
, and boolean
) maps to a primitive JSON
+ double
, and boolean
) maps to a primitive JSON
type (string, number, boolean), as per the rules listed below. These
rules apply to values in name-value pairs:
@@ -2396,8 +2399,8 @@ Mapping to JSON Types
2015-07-11T09:32:26+08:00
.
Values that are of type dateTime
- SHOULD use the literal Z
- representing the UTC time zone instead
+ SHOULD use the literal Z
+ representing the UTC time zone instead
of an offset.
@@ -2414,7 +2417,7 @@ Mapping to JSON Types
MUST be serialized as JSON boolean.
-
+
Every complex type of the TD Information Model (i.e., Arrays , Maps , and Class instances)
maps to a structured JSON type (array and object), as per the rules listed below:
@@ -2436,7 +2439,7 @@
Mapping to JSON Types
-
+
Omitting Default Values
@@ -2582,7 +2585,7 @@ Thing Root Object
includes a member with the name @context
and a value of type
string or array that equals or respectively contains http://www.w3.org/ns/td
.
-
+
In general, this URI is used to identify the
TD representation format version defined by this specification.
@@ -2591,7 +2594,7 @@
Thing Root Object
-{
+{
"@context": "http://www.w3.org/ns/td",
...
}
@@ -2667,7 +2670,7 @@ Thing Root Object
Human-Readable Metadata
- JSON members named title
and description
are
+ JSON members named title
and description
are
used within a TD document to provide human-readable metadata.
They can be used as comments for developers inspecting a TD document
or as display texts for user interface.
@@ -2687,21 +2690,21 @@
Human-Readable Metadata
- Strings on the Web [[?STRING-META]] suggests
+ Strings on the Web [[?STRING-META]] suggests
both strong-first and language-based inferencing as means
to determine the base text direction.
- Given that the Thing Description format is based on JSON-LD 1.1
+ Given that the Thing Description format is based on JSON-LD 1.1
[[?json-ld11]], which currently lacks explicit direction metadata,
- these approaches are currently considered appropriate
- at the time of this publication.
+ these approaches are currently considered appropriate
+ at the time of this publication.
However, if JSON-LD 1.1 adopts support for explicit
base direction metadata as recommended by [[?STRING-META]],
- the Thing Description format should be updated to take advantage of
+ the Thing Description format should be updated to take advantage of
that feature.
-
+
- A TD snippet using title
and description
is
+ A TD snippet using title
and description
is
shown below. The default language is set to en
through the
definition of the @language
member within a JSON object in the @context
array.
@@ -2733,7 +2736,7 @@ Human-Readable Metadata
- The JSON members named titles
and descriptions
are
+ The JSON members named titles
and descriptions
are
used within the TD document to provide human-readable metadata
in multiple languages within a single TD document.
@@ -2750,7 +2753,7 @@ Human-Readable Metadata
A TD snippet using titles
and descriptions
at different levels is given below:
-
+
{
"@context": "http://www.w3.org/ns/td",
@@ -2759,14 +2762,14 @@ Human-Readable Metadata
"en":"MyThing",
"de": "MeinDing",
"ja": "私の物",
- "zh-Hans": "我的东西",
+ "zh-Hans": "我的东西",
"zh-Hant": "我的東西"
},
"descriptions": {
"en":"Human readable information.",
"de": "Menschenlesbare Informationen.",
"ja": "人間が読むことができる情報",
- "zh-Hans": "人们可阅读的信息",
+ "zh-Hans": "人们可阅读的信息",
"zh-Hant": "人們可閱讀的資訊"
},
...
@@ -2796,7 +2799,7 @@ Human-Readable Metadata
...
}
-
+
TD instances may also combine the use of title
and description
with titles
and descriptions
.
@@ -2816,7 +2819,7 @@
Human-Readable Metadata
The language of the default text is indicated by the default language,
which is usually set by the creator of the Thing Description instance.
-
+
{
"@context": [
@@ -2828,7 +2831,7 @@ Human-Readable Metadata
"en":"MyThing",
"de": "MeinDing",
"ja": "私の物",
- "zh-Hans": "我的东西",
+ "zh-Hans": "我的东西",
"zh-Hant": "我的東西"
},
"description": "Menschenlesbare Informationen.",
@@ -2836,7 +2839,7 @@ Human-Readable Metadata
"en":"Human readable information.",
"de": "Menschenlesbare Informationen.",
"ja": "人間が読むことができる情報",
- "zh-Hans": "人们可阅读的信息",
+ "zh-Hans": "人们可阅读的信息",
"zh-Hant": "人們可閱讀的資訊"
},
...
@@ -2898,7 +2901,7 @@ version
MUST be serialized as JSON members with the Vocabulary Term as name.
-
+
A TD snippet of a version information object is given below:
@@ -2910,7 +2913,7 @@ version
- The version
member is intended as container for additional application- and/or device-specific version information based
+ The version
member is intended as container for additional application- and/or device-specific version information based
on TD Context Extensions . See for details.
@@ -2971,7 +2974,7 @@ securityDefinitions
and security
Note that the corresponding private security configuration
such as username/password and tokens must be configured in the Consumer
to interact successfully.
- When activating multiple security definitions,
+ When activating multiple security definitions,
the security
member becomes an array.
@@ -2993,10 +2996,10 @@ securityDefinitions
and security
"security": ["proxy_sc", "bearer_sc"],
...
-
+
However, the use of an array with multiple elements to combine security schemes
in a security
element is now deprecated.
- A ComboSecurityScheme
+ A ComboSecurityScheme
should be used instead as in the following example, which is exactly equivalent to the one above:
@@ -3038,10 +3041,10 @@ securityDefinitions
and security
- The nosec
security scheme is provided for the case that
+ The nosec
security scheme is provided for the case that
no security is needed.
The minimal security configuration for a Thing is activation
- of the nosec
security scheme
+ of the nosec
security scheme
at the Thing level, as shown in the following example:
@@ -3059,10 +3062,10 @@ securityDefinitions
and security
"events": {...},
"links": [...]
}
-
+
- To give a more complex example,
+ To give a more complex example,
suppose we have a Thing where all Interaction Affordances
require basic authentication except for one, for which
no authentication is required.
@@ -3118,11 +3121,11 @@
securityDefinitions
and security
mechanisms are allowed. Here is a TD snippet demonstrating three possible
ways to activate a Property affordance: via HTTPS with basic authentication,
with digest authentication, with bearer token authentication.
- In other words,
+ In other words,
the use of different security configurations within multiple forms
provides a way to combine security mechanisms in an "OR" fashion.
In contrast, putting multiple security configurations in the same
- security
member combines them in an "AND" fashion,
+ security
member combines them in an "AND" fashion,
since in that case they would all need to be satisfied to allow activation of the Interaction Affordance .
Note that activating one (default) configuration at the Thing level is still mandatory.
@@ -3156,7 +3159,7 @@ securityDefinitions
and security
To avoid redundancy in this case, e.g. repeating the details of the form
elements, a ComboSecurityScheme
- with oneOf
can be used instead.
+ with oneOf
can be used instead.
{
@@ -3165,9 +3168,9 @@ securityDefinitions
and security
"basic_sc": { "scheme": "basic" },
"digest_sc": { "scheme": "digest" },
"bearer_sc": { "scheme": "bearer" },
- "combo_sc": {
- "scheme": "combo",
- "oneOf": [ "basic_sc", "digest_sc", "bearer_sc" ]
+ "combo_sc": {
+ "scheme": "combo",
+ "oneOf": [ "basic_sc", "digest_sc", "bearer_sc" ]
}
},
"security": "combo_sc",
@@ -3185,9 +3188,9 @@ securityDefinitions
and security
- As another more complex example, OAuth 2.0 makes use of scopes.
- These are identifiers that
- may appear in tokens and must match with corresponding identifiers in a resource to allow
+ As another more complex example, OAuth 2.0 makes use of scopes.
+ These are identifiers that
+ may appear in tokens and must match with corresponding identifiers in a resource to allow
access to that resource (or Interaction Affordance in the case of W3C WoT).
For example, in the following, the status
Property can be
read by Consumers using bearer tokens containing the scope limited
,
@@ -3195,7 +3198,7 @@
securityDefinitions
and security
with a token containing the special
scope.
Scopes are not identical to roles, but are often associated with them;
for example, perhaps only those in an administrative role are authorized to perform "special" interactions.
- Tokens can have more than one scope.
+ Tokens can have more than one scope.
In this example, an administrator would
probably be issued tokens with both the limited
and special
scopes,
while ordinary users would only be issued tokens with the limited
scope.
@@ -3246,10 +3249,10 @@ securityDefinitions
and security
out-of-band, and the client ID, which is not secret, could be embedded in the TD.
However, if the client ID cannot be easily rotated we may want to avoid embedding it in
the TD to enhance privacy.
- In this case we can combine two instances of
+ In this case we can combine two instances of
APIKeySecurityScheme
, both
- using the uri
value for the in
location specifier, to
- declare two URI variables. These can then (in fact, they must) be used in the
+ using the uri
value for the in
location specifier, to
+ declare two URI variables. These can then (in fact, they must) be used in the
href
in a Form
where the security scheme is active.
An example follows:
@@ -3288,7 +3291,7 @@ securityDefinitions
and security
While not shown in this example, it is legal to declare additional URI template
variables using uriVariables
and include them in the same URI template,
-although the names cannot conflict with those declared in security schemes.
+although the names cannot conflict with those declared in security schemes.
Using a specific prefix as in the above example
for URI variables declared in security schemes can make it easier to avoid name conflicts.
@@ -3296,7 +3299,7 @@ securityDefinitions
and security
systems. For example, suppose a system requires every payload to be a JSON
object including a member named auth
whose value is an object
containing a member called key
containing an access key.
-Depending on the interaction, however, other elements of the JSON object might
+Depending on the interaction, however, other elements of the JSON object might
vary. This situation can be dealt with using the body
security
information location.
Note that for this location, the name
parameter is actually a JSON pointer
@@ -3304,7 +3307,7 @@ securityDefinitions
and security
it is bound with, which allows it to be used with payloads that vary in other respects.
As an example, here is a light that has a property to set its brightness and color
and two separate actions to turn it on and off. Although the JSON payloads
-are different for these actions the /auth/key
element occurs in the same
+are different for these actions the /auth/key
element occurs in the same
relative location so single JSON pointer can be used.
Note: if the security key occurs in different inconsistent locations, it will be
necessary to use multiple security scheme definitions.
@@ -3454,11 +3457,11 @@ securityDefinitions
and security
}
-
+
properties
-
+
The value assigned to properties
in a Thing
instance
is a Map of instances of PropertyAffordance
.
@@ -3602,7 +3605,7 @@
actions
...
-
+
@@ -3665,7 +3668,7 @@ events
-Event affordances have been defined in a flexible manner,
+Event affordances have been defined in a flexible manner,
in order to adopt existing (e.g., WebSub [[websub]]) or customer-oriented event mechanisms (e.g., Webhooks).
For this reason, subscription
and cancellation
can be defined according to the desired mechanism. Please find further details in [[?WOT-BINDING-TEMPLATES]].
Example illustrates how Events can use subscription
and cancellation
to describe Webhooks.
@@ -3689,7 +3692,7 @@
links
A reference can be provided that points to a Thing (e.g., a controller) that controlls the underlying
unit (e.g., a lamp). For this controlledBy
can be used:
-
+
@@ -3901,7 +3904,7 @@ forms
In some cases binary data is embedded in text-based values, e.g., a JSON string-based value embedds a base64 encoded image.
-The terms contentMediaType
and contentEncoding
can be used to clearify the context and encoding
+The terms contentMediaType
and contentEncoding
can be used to clearify the context and encoding
format of such name-value pairs. A sample usage of contentMediaType
and contentEncoding
is shown below:
@@ -3910,17 +3913,17 @@ forms
{
...
"properties": {
- "image": {
- "description": "Provides latest image",
+ "image": {
+ "description": "Provides latest image",
"type": "string",
"contentMediaType": "image/png",
"contentEncoding": "base64",
- "forms": [{
- "op": "readproperty",
- "href": "coaps://mylamp.example.com/lastPicture",
+ "forms": [{
+ "op": "readproperty",
+ "href": "coaps://mylamp.example.com/lastPicture",
"cov:methodName": "GET",
- "contentType": "application/json"
- }]
+ "contentType": "application/json"
+ }]
}
},
...
@@ -4122,7 +4125,7 @@ Data Schemas
Identification
- The JSON-based serialization of Thing Descriptions is identified by
+ The JSON-based serialization of Thing Descriptions is identified by
the media type application/td+json
or the
CoAP Content-Format ID 432
(see ).
@@ -4142,27 +4145,27 @@ Canonicalization
There are many places in which optional features are included in JSON,
such as white space, or where different representation formats are possible, such as
the number of digits in a number representation or the order of elements in an object.
- In addition to variation due to JSON serialization,
+ In addition to variation due to JSON serialization,
TDs have additional features that also permit different ways to express the
same thing.
However, whenever there is a choice of multiple ways to present information,
- canonicalization needs to select only one.
+ canonicalization needs to select only one.
- Some of the choices leading to the efficient computation of a canonical form,
- such as the suppression of white space and sorting of elements in objects
+ Some of the choices leading to the efficient computation of a canonical form,
+ such as the suppression of white space and sorting of elements in objects
do make the representation less human readable.
In general, the canonical form presented here is optimized for machine-to-machine
use cases such as signing.
- The starting point for the process described here is
- the JSON serialization of a TD.
- The following sequence of transformations and constraints are then applied:
+
The starting point for the process described here is
+ the JSON serialization of a TD.
+ The following sequence of transformations and constraints are then applied:
- In the Canonical TD ,
+ In the Canonical TD ,
values that are of type dateTime
- MUST use the literal Z
- representing the UTC time zone instead
+ MUST use the literal Z
+ representing the UTC time zone instead
of an offset.
@@ -4171,7 +4174,7 @@ Canonicalization
and are assigned their default value.
For example, the default value of observable
- is false
.
+ is false
.
If an input TD omits observable
where it is allowed,
it must still explictly appear in the canonical form with the value of false
.
Note that this also applies to extension vocabularies, e.g. for protocol bindings.
@@ -4179,8 +4182,8 @@ Canonicalization
In the Canonical TD ,
- all values that can be expressed as either an array or as a single value
- MUST be written as a single value if there is only one element.
+ all values that can be expressed as either an array or as a single value
+ MUST be written as a single value if there is only one element.
In other words, square brackets around
arrays of single elements must be removed.
@@ -4195,9 +4198,9 @@ Canonicalization
Note that the JSON Canonicalization Scheme, and by extension the process defined here,
preserves the order of elements in arrays.
There are some array-valued elements in TDs where the order is not meaningful, such
- as the list of scopes
in a Form
.
+ as the list of scopes
in a Form
.
- In order to support canonicalization, implementations
+ In order to support canonicalization, implementations
of TD Processors MUST preserve the order of elements in all arrays.
If extension vocabularies are used, the prefixes need to be preserved
@@ -4207,28 +4210,28 @@
Canonicalization
However, doing so would result in a different serialization
and would invalidate signatures.
- In order to support canonicalization, implementations
+ In order to support canonicalization, implementations
of TD Processors MUST preserve the prefixes used for extension vocabularies.
This includes preserving and expressing a vocabulary term as a URL if no prefix was used.
Some systems support different forms of URLs that are equivalent, for example,
by mapping upper to lower case. It is also legal to percent-encode
- unreserved characters, even though this is unnecessary and discouraged [[!RFC3986]].
+ unreserved characters, even though this is unnecessary and discouraged [[!RFC3986]].
For canonicalization, however, such URL variants cannot be considered equivalent.
- In order to support canonicalization, implementations
+ In order to support canonicalization, implementations
of TD Processors MUST NOT modify input URLs.
- Of course some applications will need to modify URLs in TDs,
+ Of course some applications will need to modify URLs in TDs,
i.e. to express the result of protocol translation
or to add entry points to a proxy.
The result should technically be considered a new TD related to the old one, but not equivalent.
- TDs should be validated before being canonicalized.
+ TDs should be validated before being canonicalized.
TD validation requires that URLs
- be fully confomant with the standard [[!RFC3986]] and this in particular
+ be fully confomant with the standard [[!RFC3986]] and this in particular
requires (for example) that
- characters outside the basic set defined for URLs
- be percent-encoded.
+ characters outside the basic set defined for URLs
+ be percent-encoded.
Here is an example TD that is in canonical form, except that white space
and newlines have been inserted to make it more readable:
@@ -4356,7 +4359,7 @@
Example I: Version and Unit Annotations
by adding version numbers for the hardware and firmware of the Thing , and uses
values from external Vocabularies for the Thing and for the
data schema unit: SAREF ,
- also used in , and
+ also used in , and
OM , the
Ontology of Units of Measure [[?RIJGERSBERG]]. These Vocabularies
are used as examples—others may exist, in particular in the home automation domain.
@@ -4478,13 +4481,13 @@ Example III: Geolocation Annotations
For many use cases like in building, agriculture, or smart city location based data is required. This
information can be provided in the Thing Description in different ways and can be relied on
- different kind of location ontologies (e.g.,[[w3c-basic-geo]], schema.org) depending on purpose (e.g., indoor, outdoor).
+ different kind of location ontologies (e.g.,[[w3c-basic-geo]], schema.org) depending on purpose (e.g., indoor, outdoor).
Also see [[sdw-bp]].
-
+
- The TD snippet below uses lat
and long
from the [[w3c-basic-geo]] ontology to
- provide static latitude and longitude metadata at Thing's top level.
+ The TD snippet below uses lat
and long
from the [[w3c-basic-geo]] ontology to
+ provide static latitude and longitude metadata at Thing's top level.
@@ -4492,7 +4495,7 @@ Example III: Geolocation Annotations
"@context": [
"http://www.w3.org/ns/td",
{
- "geo": "http://www.w3.org/2003/01/geo/wgs84_pos#"
+ "geo": "http://www.w3.org/2003/01/geo/wgs84_pos#"
}
],
"@type": "Thing",
@@ -4501,13 +4504,13 @@ Example III: Geolocation Annotations
...
"properties": {
...
-
+
}
- In some use cases location based metadata have to be provided at the interaction level, e.g.,
+ In some use cases location based metadata have to be provided at the interaction level, e.g.,
as provided as a Property that returns the latest longitude
, latitude
, and elevation
values
based on schema.org:
@@ -4539,8 +4542,8 @@ Example III: Geolocation Annotations
- In case a different name is desired for, e.g., longitude
, latitude
,
- and elevation
in the data model, the jsonld:context
can be used to link
+ In case a different name is desired for, e.g., longitude
, latitude
,
+ and elevation
in the data model, the jsonld:context
can be used to link
terms to specific vocabulary from an ontology (also see [[JSON-SCHEMA-ONTOLOGY]], Section 3.3 Defining a JSON-LD context for data instances):
@@ -4583,7 +4586,7 @@ Adding Protocol Bindings
through additional Vocabulary Terms serialized into JSON objects representing a Form
instance.
(see also ).
-
+
The following TD example uses a fictional CoAP Protocol Binding ,
as no such Protocol Binding is available at the time of writing this specification.
@@ -4595,7 +4598,7 @@
Adding Protocol Bindings
POST
for the CoAP Method Code 0.02,
or iPATCH
for CoAP Method Code 0.07).
-
+
{
@@ -4626,12 +4629,12 @@ Adding Protocol Bindings
}
-
+
-
+
Adding Security Schemes
-
+
Finally, new security schemes that are not included in
can be imported using the TD Context Extension mechanism.
@@ -4641,7 +4644,7 @@
Adding Security Schemes
Note that such additional security schemes must be Subclasses of the
Class SecurityScheme
.
-
+
{
@context: [
@@ -4695,51 +4698,51 @@ Adding Security Schemes
Note that all security schemes defined in
are already part of the TD context and need not to be included through a TD Context Extension .
-
+
Behavioral Assertions
- The following assertions relate to the behavior of components of a
- WoT system, as opposed to the representation or information model of the TD.
+ The following assertions relate to the behavior of components of a
+ WoT system, as opposed to the representation or information model of the TD.
However, note that TDs are descriptive, and may in particular be used to
describe pre-existing network interfaces. In these cases, assertions cannot
be made that constrain the behavior of such pre-existing interfaces. Instead,
the assertions must be interpreted as constraints on the TD to accurately
- represent such interfaces.
-
+ represent such interfaces.
+
Security Configurations
- To enable secure interoperation,
+ To enable secure interoperation,
security configurations must accurately reflect the requirements of the Thing :
If a Thing requires a specific access mechanism for an interaction, that
mechanism MUST be specified in the security configuration of the Thing Description.
-
+
+
- Some security protocols may ask for authentication
- information dynamically, including required encoding or encryption schemes.
+ Some security protocols may ask for authentication
+ information dynamically, including required encoding or encryption schemes.
One consequence of the above is that if a protocol asks for
- a form of security credentials or an encoding or encryption scheme
- not declared in the Thing Description
+ a form of security credentials or an encoding or encryption scheme
+ not declared in the Thing Description
then the Thing Description is to be considered invalid.
Data Schemas
-The data schemas provided in the TD should accurately represent the
+
The data schemas provided in the TD should accurately represent the
data payloads returned and accepted by the described Thing
in the interactions specified in the TD. In general, Consumers should
follow the data schemas strictly, not generating anything not given
@@ -4749,26 +4752,26 @@
Data Schemas
interacting with Things .
-
A Thing acting as a Consumer when interacting with another target Thing
-described in a WoT Thing Description MUST generate data
+described in a WoT Thing Description MUST generate data
organized according to the data schemas given in the corresponding
interactions.
-
-A WoT Thing Description MUST accurately describe the
+A WoT Thing Description MUST accurately describe the
data returned and accepted by each interaction.
-
This applies to ObjectSchema
and ArraySchema
(when items
is an Array of
@@ -4776,10 +4779,10 @@ Data Schemas
"additionalProperties":true
or "additionalItems":true
as defined in [[?JSON-SCHEMA]].
-
This applies to ObjectSchema
and ArraySchema
(when items
is an Array of
@@ -4787,14 +4790,14 @@ Data Schemas
"additionalProperties":true
or "additionalItems":true
as defined in [[?JSON-SCHEMA]].
-
-
A Thing acting as a Consumer when interacting with another Thing MUST generate URIs
according to the URI Templates, base URIs, and form href parameters
@@ -4802,7 +4805,7 @@ Data Schemas
-
URI Templates, base URIs, and href members
in a WoT Thing Description MUST accurately describe the WoT Interface of the Thing .
@@ -4852,11 +4855,11 @@ Protocol Bindings
Protocol Binding based on HTTP
- Per default the Thing Description supports the Protocol Binding based on HTTP
+ Per default the Thing Description supports the Protocol Binding based on HTTP
by including the HTTP RDF vocabulary definitions from HTTP Vocabulary in RDF 1.0 [[?HTTP-in-RDF10]].
- This vocabulary can be
- directly used within TD instances by the usage of the prefix htv
, which
- points to http://www.w3.org/2011/http#
.
+ This vocabulary can be
+ directly used within TD instances by the usage of the prefix htv
, which
+ points to http://www.w3.org/2011/http#
.
Further details of Protocol Binding based on HTTP can be found in [[?WOT-BINDING-TEMPLATES]].
@@ -4867,7 +4870,7 @@
Protocol Binding based on HTTP
sake of conciseness, the Protocol Binding based on HTTP defines Default Values for the operation types listed below,
which also aims at convergence of the methods expected by Things (e.g., GET to read, PUT to write).
- When no method is indicated in a form representing an Protocol Binding based on HTTP,
+ When no method is indicated in a form representing an Protocol Binding based on HTTP,
a Default Value MUST be assumed as shown in
the following table.
@@ -4888,7 +4891,7 @@ Protocol Binding based on HTTP
GET
- Form
with operation type readproperty
, readallproperties
, readmultipleproperties
+ Form
with operation type readproperty
, readallproperties
, readmultipleproperties
, readalleventlogs
@@ -4914,7 +4917,7 @@ Protocol Binding based on HTTP
For example, the Example 1 in
- does not contain operation types and HTTP methods in the forms.
+ does not contain operation types and HTTP methods in the forms.
The following Default Values should be assumed for the forms in the Example 1 :
@@ -5027,13 +5030,13 @@ Protocol Binding based on HTTP
}
- In the case of a forms
entry that has multiple op
values the usage
+
In the case of a forms
entry that has multiple op
values the usage
of the htv:methodName
is not permitted. A TD Processor will extend
- the multiple op
values to separate forms
entries and associates
- a single operation with the default assumption. The address information (e.g. href
) and
+ the multiple op
values to separate forms
entries and associates
+ a single operation with the default assumption. The address information (e.g. href
) and
other metadata are taken over in the extended version.
-
+
@@ -5119,26 +5122,26 @@
Other Protocol Bindings
Fingerprinting Privacy Risk
- As noted above, the id
member in a TD can pose a privacy risk.
+
As noted above, the id
member in a TD can pose a privacy risk.
However, even if the id
is updated as described to mitigate its
tracking risk, it may still be possible to associate
- a TD with a particular physical device, and from there to an identifiable person,
+ a TD with a particular physical device, and from there to an identifiable person,
through fingerprinting.
Even if a specific device instance cannot be identified through fingerprinting,
@@ -5221,13 +5224,13 @@
Fingerprinting Privacy Risk
Only authorized users should be provided access
to the Thing Description for a Thing , and only the amount of
information needed for the level of authorization and the use case should be provided.
- If the TD is only distributed to authorized users
+ If the TD is only distributed to authorized users
through secure and confidential channels, for
example through a directory service that requires authentication,
then external unauthorized parties will not have access to the TD to fingerprint it.
To further mitigate this risk, information not necessary for a particular
use case of a TD should be omitted whenever possible. For example,
- for an ad-hoc connection to a device where the Consumer does
+ for an ad-hoc connection to a device where the Consumer does
not store state about the Thing, the id
can be omitted.
If the Consumer does not need certain interactions for its use case, they can be omitted.
If the Consumer is not authorized to use certain interactions, they can likewise be omitted.
@@ -5242,7 +5245,7 @@ Globally Unique Identifier Privacy Risk
Mitigation:
The id
field in TDs are intentionally not required to be globally unique.
- There are several cryptographic mechanisms available to generate suitable IDs in a
+ There are several cryptographic mechanisms available to generate suitable IDs in a
distributed fashion that do
not require a central registry. These mechanisms typically have a very low probability
of generating duplicate identifiers, and this needs to be taken into account in the system
@@ -5254,7 +5257,7 @@ Globally Unique Identifier Privacy Risk
TD Interception and Tampering Security Risk
Intercepting and tampering with TDs can be used to launch man-in-the-middle attacks,
- for example by rewriting URLs in TDs to redirect accesses to a malicious
+ for example by rewriting URLs in TDs to redirect accesses to a malicious
intermediary that can capture or manipulate data.
Mitigation:
@@ -5268,13 +5271,13 @@ TD Interception and Tampering Security Risk
Context Interception and Tampering Security Risk
Intercepting and tampering with context files can be used to facilitate attacks
- by modifying the interpretation of vocabulary.
+ by modifying the interpretation of vocabulary.
Mitigation:
Ideally context files would only be obtained through authenticated channels
but it is notable (and unfortunate) that many contexts are indicated using
- HTTP URLs, which are vulnerable to interception and modification if
- dereferenced. However, if context files are immutable and cached,
+ HTTP URLs, which are vulnerable to interception and modification if
+ dereferenced. However, if context files are immutable and cached,
and dereferencing is avoided whenever possible, then this risk can be reduced.
@@ -5295,16 +5298,16 @@ Inferencing of Personally Identifiable Information Privacy Risk
which can lead to additional inferences about that person.
Mitigation:
- Treat a Thing Description associated with a
+ Treat a Thing Description associated with a
personal device as if it contained
personally identifiable information.
As an example application of this principle,
- consider how to obtain user consent.
+ consider how to obtain user consent.
Consent for usage of personally identifiable data
generated by a Thing is often obtained when a Thing is paired with system
consuming the data,
which is frequently also when the Thing Description
- is registered with a local directory or the system consuming the
+ is registered with a local directory or the system consuming the
Thing Description in order to access the device.
In this case, consent for using data from a Thing can be combined with
consent for accessing the Thing Description of the Thing .
@@ -5318,11 +5321,11 @@ Inferencing of Personally Identifiable Information Privacy Risk
Thing Model
-
+
- The following section has its origin in [[wot-thing-description]], Annex C. Here Thing Description
+ The following section has its origin in [[wot-thing-description]], Annex C. Here Thing Description
Template is renamed to Thing Model , but keeps the same intention.
- For this version of the specification, Thing Model and its model features (e.g., extensions, referencing, obligations, placeholder) are formal
+ For this version of the specification, Thing Model and its model features (e.g., extensions, referencing, obligations, placeholder) are formal
introduced. For Thing Model, an own content type is under discussion. Pleace note this section is in work in progress.
@@ -5331,16 +5334,16 @@ Basic Concept
A Thing Model enables the oppertunity to define the basic information model of a Thing . It can be seen
- as a template for Thing Descriptions , however, that have less restriction as
- driven in and . Typically Thing Model examples
- does not contain any instance-specific information such as protocol specific data like IP addresses. However, instead of having, e.g., concrete URLs,
- Thing Model allows the usage of URL templates.
+ as a template for Thing Descriptions , however, that have less restriction as
+ driven in and . Typically Thing Model examples
+ does not contain any instance-specific information such as protocol specific data like IP addresses. However, instead of having, e.g., concrete URLs,
+ Thing Model allows the usage of URL templates.
- The figure below illustrates the relation of the Thing Model and Thing Description . A Thing Model mainly describes
- interaction affordances such as the Properties , Actions , and Events and common metadata. This kind of template should
- be valid and followed for all instantiated Thing Descriptions that are relied on this Thing Model . This paradigm can be compared
+ The figure below illustrates the relation of the Thing Model and Thing Description . A Thing Model mainly describes
+ interaction affordances such as the Properties , Actions , and Events and common metadata. This kind of template should
+ be valid and followed for all instantiated Thing Descriptions that are relied on this Thing Model . This paradigm can be compared
with abstract class or interface definition (~Thing Model) in object-oriented programming to create objects (~Thing Descriptions).
@@ -5366,15 +5369,15 @@ Basic Concept
The Thing Model is a logical description of the interface and possible interaction with Thing 's
Properties , Actions , and Events , however it does not contain Thing instance-specific
information, such as concrete protocol usage (e.g., IP address), or even a serial number and GPS location.
- However, Thing Models allows to include, e.g., security schemes if they apply to the entire class of instances the
- model describes. They might have URLs (e.g., like token servers) that might need to be omitted or parameterized
- (with templates) although in a lot of cases these might also be given.
+ However, Thing Models allows to include, e.g., security schemes if they apply to the entire class of instances the
+ model describes. They might have URLs (e.g., like token servers) that might need to be omitted or parameterized
+ (with templates) although in a lot of cases these might also be given.
- Thing Model can be serialized in the same JSON-based format as a Thing Description which also allows JSON-LD processing.
- Note that a Thing Model cannot be validated in the same way as Thing Description instances due to some missing
+ Thing Model can be serialized in the same JSON-based format as a Thing Description which also allows JSON-LD processing.
+ Note that a Thing Model cannot be validated in the same way as Thing Description instances due to some missing
mandatory terms.
@@ -5384,7 +5387,7 @@ Thing Model Declaration
A Thing Model is recognized by the top level @type .
- Thing Model definitions MUST use the keyword @type at top level
+ Thing Model definitions MUST use the keyword @type at top level
and a value of type string or array that equals or respectively contains ThingModel
.
@@ -5394,18 +5397,18 @@ Thing Model Declaration
A Thing Model MAY NOT contain instance specific Protocol Binding information such as endpoint address.
- As consequent, Thing Model definitions will be also valid if there are no JSON members like forms ,
+ As consequent, Thing Model definitions will be also valid if there are no JSON members like forms ,
securityDefinitions , and security . Thing Models are also valid even if these JSON members are used, however,
the nested mandatory members like href are omitted.
-
+
In the following there is a sample Thing Model for a lamp without any protocol and security information.
-
+
{
- "@context": ["http://www.w3.org/ns/td"],
+ "@context": ["http://www.w3.org/ns/td"],
"@type" : "ThingModel",
"title": "Lamp Thing Model",
"description": "Lamp Thing Description Model",
@@ -5438,12 +5441,12 @@ Modeling Tools
Versioning
-
+
- Over time, Thing Model definitions may change and must be made identifiable through versioning.
- In that case the string-based term model
can be used within the version
container to
+ Over time, Thing Model definitions may change and must be made identifiable through versioning.
+ In that case the string-based term model
can be used within the version
container to
provide a version pattern like [[SEMVER]]. The following snopped shows the usage of model
in a
- Thing Model instance.
+ Thing Model instance.
@@ -5458,7 +5461,7 @@ Versioning
- Due to the definition of Thing Model the term instance
can be omitted within the version
container.
+ Due to the definition of Thing Model the term instance
can be omitted within the version
container.
@@ -5468,21 +5471,21 @@ Extension and Import
A Thing Model can also extend
an existing Thing Model .
- A Thing Model MUST use at least one links
entry with "rel":"extend"
+ A Thing Model MUST use at least one links
entry with "rel":"extend"
that targets to a Thing Model that is be extended.
- The Thing Model will inherit all definitions from the extended Thing Model . There is the opportunity
- to extend the existing definition with further metadata by providing further JSON name-value pairs from existing
- TD information model ( ) or using the context extension concept
- ( ). A Thing Model can also overwrite existing defintions such as title(s)
- and description(s)
. For this there exists two limitiations:
+ The Thing Model will inherit all definitions from the extended Thing Model . There is the opportunity
+ to extend the existing definition with further metadata by providing further JSON name-value pairs from existing
+ TD information model ( ) or using the context extension concept
+ ( ). A Thing Model can also overwrite existing defintions such as title(s)
+ and description(s)
. For this there exists two limitiations:
- A Thing Model SHOULD NOT overwrite the JSON names defined within the
+ A Thing Model SHOULD NOT overwrite the JSON names defined within the
properties
, actions
, and/or events
Map of the extended Thing Model .
The value of the types
in data schema definitions of the extended Thing Model SHOULD NOT change the value type.
- An exception is allowed when the extended Thing Model uses number
as data schema type value, the context Thing Model
+ An exception is allowed when the extended Thing Model uses number
as data schema type value, the context Thing Model
is allowed only to overwrite this value type to integer
.
Those assertations preserve the semantics throughout of the extended Thing Model .
@@ -5494,7 +5497,7 @@
Extension and Import
{
- "@context": ["http://www.w3.org/ns/td"],
+ "@context": ["http://www.w3.org/ns/td"],
"@type" : "ThingModel",
"title": "Basic On/Off Thing Model",
"properties": {
@@ -5505,14 +5508,14 @@ Extension and Import
}
- Now it is designed a new device class model called 'Smart Lamp Control' that should be used as template
+
Now it is designed a new device class model called 'Smart Lamp Control' that should be used as template
for creating TD instances. This model will reuse the existing definition of the 'Basic On/Off Thing Model'
and extend it with a dim
property:
{
- "@context": ["http://www.w3.org/ns/td"],
+ "@context": ["http://www.w3.org/ns/td"],
"@type" : "ThingModel",
"title": "Smart Lamp Control with Dimming",
"links" : [{
@@ -5536,26 +5539,26 @@ Extension and Import
The extend
feature only allows to inherit all definitions of one TM. In many use cases, however,
it is desired to import sub-definition of one or more TMs. For doing this, the tm:ref
term is introduced
- with a JSON Pointer-based value [[rfc6901]] that allows to copy a defintion within an existing TM into a new created
- local context definition.
+ with a JSON Pointer-based value [[rfc6901]] that allows to copy a defintion within an existing TM into a new created
+ local context definition.
The value of tm:ref
term MUST be a valid JSON Pointer that identifys to a pre-existing definition based on
- Thing Model specifications.
+ Thing Model specifications.
- Every time tm:ref
is used, the referenced pre-definition and its dependencies
+ Every time tm:ref
is used, the referenced pre-definition and its dependencies
(e.g., by context extension) MUST be assumed at this point.
- The following example shows a new TM definition that imports the existing definition of the property
- onOff
from into the new property definition
+ The following example shows a new TM definition that imports the existing definition of the property
+ onOff
from into the new property definition
switch
.
{
- "@context": ["http://www.w3.org/ns/td"],
+ "@context": ["http://www.w3.org/ns/td"],
"@type" : "ThingModel",
"title": "Smart Lamp Control",
"properties" : {
@@ -5567,15 +5570,15 @@ Extension and Import
- At the place the "tm:ref" is defined, additional name-value pairs can be added.
- It is also allow to override name-value pairs from the referenced definition.
+ At the place the "tm:ref" is defined, additional name-value pairs can be added.
+ It is also allow to override name-value pairs from the referenced definition.
If it is intended to override an existing JSON name-value pair definition from tm:ref
, the same JSON name MUST be used
- at the same level of the tm:ref
declearation that provides a new value.
+ at the same level of the tm:ref
declearation that provides a new value.
To keep the semantic meaning of the referenced definition it is not allowed to relax any restriction (e.g., increase value ranges) or
- change a data type definition.
+ change a data type definition.
@@ -5586,7 +5589,7 @@ Extension and Import
{
- "@context": ["http://www.w3.org/ns/td"],
+ "@context": ["http://www.w3.org/ns/td"],
"@type" : "ThingModel",
"title": "Smart Lamp Control",
"properties" : {
@@ -5598,17 +5601,17 @@ Extension and Import
}
}
-
+
- The extend
and the import mechanism based on tm:ref
can be also used at the same time in
+ The extend
and the import mechanism based on tm:ref
can be also used at the same time in
a TM definition. The following example extends the TM from and imports
- the status
and dim
definitions from and
+ the status
and dim
definitions from and
respectively.
{
- "@context": ["http://www.w3.org/ns/td"],
+ "@context": ["http://www.w3.org/ns/td"],
"@type" : "ThingModel",
"title": "Smart Lamp Control",
"links" : [{
@@ -5634,27 +5637,27 @@ Extension and Import
Placeholder
- Thing Model can specify which terms should be taken in a TD instance, but their values are unspecific and are first known during TD instantiation.
- In such a case the placeholder labeling MAY be used in Thing Model that MUST be substituted with a concrete value when TD instance is created
- from the Thing Model.
+ Thing Model can specify which terms should be taken in a TD instance, but their values are unspecific and are first known during TD instantiation.
+ In such a case the placeholder labeling MAY be used in Thing Model that MUST be substituted with a concrete value when TD instance is created
+ from the Thing Model.
- The string-based pattern of the placeholder MUST follow {{PLACEHOLDER_IDENTIFIER}}
,
+ The string-based pattern of the placeholder MUST follow {{PLACEHOLDER_IDENTIFIER}}
,
which should contain a placeholder identifier name. The identifier name can be used to identify the placeholder for the substitution process.
- Placeholder can be only applied within the value of the JSON name-value pair and the value have to be typed as JSON string.
-
+ Placeholder can be only applied within the value of the JSON name-value pair and the value have to be typed as JSON string.
+
- In the case a non string-based value of a JSON name-value pair should have a placeholder the value must be (temporary) typed
+ In the case a non string-based value of a JSON name-value pair should have a placeholder the value must be (temporary) typed
as string.
- After replacing the placeholder, e.g. when creating a Thing Description instance, the original type can be applied with the
- corresponding replaced value.
+ After replacing the placeholder, e.g. when creating a Thing Description instance, the original type can be applied with the
+ corresponding replaced value.
The following Thing Model example defines different placeholders. The placeholder map is used to apply the replacement and to
- transform the intended value type.
+ transform the intended value type.
@@ -5667,7 +5670,7 @@
Placeholder
{
- "@context": ["http://www.w3.org/ns/td"],
+ "@context": ["http://www.w3.org/ns/td"],
"@type" : "ThingModel",
"title": "Thermostate No. {{THERMOSTATE_NUMBER}}",
"base": "mqtt://{{MQTT_BROKER_ADDRESS}}",
@@ -5685,15 +5688,15 @@ Placeholder
{
- "THERMOSTATE_NUMBER": 4,
+ "THERMOSTATE_NUMBER": 4,
"MQTT_BROKER_ADDRESS" : "192.168.178.72:1883",
- "THERMOSTATE_TEMPERATURE_MAXIMUM": 47.7,
+ "THERMOSTATE_TEMPERATURE_MAXIMUM": 47.7,
"THERMOSTATE_TEMPERATURE_OBSERVABLE" : true
}
{
- "@context": ["http://www.w3.org/ns/td"],
+ "@context": ["http://www.w3.org/ns/td"],
"@type" : "Thing",
"title": "Thermostate No. 4",
"base": "mqtt://192.168.178.72:1883",
@@ -5717,35 +5720,35 @@ Placeholder
Required
-
- In some cases it is desirable to force the information which interaction model is mandatory
- and has to be definitely implemented in a Thing Description instance or can be always expected
+
+ In some cases it is desirable to force the information which interaction model is mandatory
+ and has to be definitely implemented in a Thing Description instance or can be always expected
by the Thing Model .
- To guarantee the implementation of particular kind of interaction models, Thing Model definitions MUST use
- the JSON member name tm:required
.
+ To guarantee the implementation of particular kind of interaction models, Thing Model definitions MUST use
+ the JSON member name tm:required
.
- tm:required
MUST be a JSON array at the top level.
+ tm:required
MUST be a JSON array at the top level.
- The value of tm:required
MUST provide JSON Pointer [[RFC6901]] references to the required interaction model
- definitions.
+ The value of tm:required
MUST provide JSON Pointer [[RFC6901]] references to the required interaction model
+ definitions.
- The JSON Pointers of tm:required
MUST resolve to an entire interaction affordance Map
+ The JSON Pointers of tm:required
MUST resolve to an entire interaction affordance Map
definition.
-
+
The following sample shows the usage of tm:required
for the Property interaction status
-and Action interaction toggle
.
+and Action interaction toggle
.
{
- "@context": ["http://www.w3.org/ns/td"],
+ "@context": ["http://www.w3.org/ns/td"],
"@type" : "ThingModel",
"title": "Lamp Thing Model",
"description": "Lamp Thing Description Model",
@@ -5773,9 +5776,9 @@ Required
}
}
-
+
-Since the Event overheating
is not mandatory it may be not available in a Thing Description
+Since the Event overheating
is not mandatory it may be not available in a Thing Description
instance.
@@ -5784,25 +5787,25 @@ Required
-
+
Derivation to Thing Description Instances
- Thing Models can be used as template to generate Thing Description based on the restriction defined in
- Sections and . During this process
+ Thing Models can be used as template to generate Thing Description based on the restriction defined in
+ Sections and . During this process
missing data such as communication and seceurity metadata have to be complemented to create valid Thing Description instances.
- A Thing Model MUST be defined in such a way that there are no inconsistencies that would result in a Thing Description not
+ A Thing Model MUST be defined in such a way that there are no inconsistencies that would result in a Thing Description not
being able to meet the requirements as described in Section and .
A TM-to-TD generation processor MUST at least address the following considerations:
- All definitions in the applied Thing Model have to taken over in the Thing Description instance. If used, the extension and imports feature according to Section must be resolved
+ All definitions in the applied Thing Model have to taken over in the Thing Description instance. If used, the extension and imports feature according to Section must be resolved
and represented in the Thing Description instance as well.
The value ThingModel
value of the top-level @type
have to be replaced by the value Thing
in the Thing Description instance.
If the required
feature is used based on Section , the required interactions must definitly be taken over in the Thing Description instance.
@@ -5813,11 +5816,11 @@ Derivation to Thing Description Instances
-
- Thing description instances that follow a Thing model can carry the information which type
+
+
Thing description instances that follow a Thing model can carry the information which type
of Thing model is derived. In this context, the linking concept can be used with "rel" : "type"
(also see
- Section ), as shown in the following example:
+ Section ), as shown in the following example:
@@ -5857,14 +5860,14 @@
Derivation to Thing Description Instances
-
Please not that a TD can only be an instance of only one TM at a time.
+
Please not that a TD can only be an instance of only one TM at a time.
That means for Thing Descriptions:
The links
array can use the entry with "rel" : "type"
maximum one.
-
+
-
+
@@ -5873,13 +5876,13 @@
Derivation to Thing Description Instances
Examples
- The following Thing Model extends the model as shown in and
- overwrites the maximum
value of the dim
property
+ The following Thing Model extends the model as shown in and
+ overwrites the maximum
value of the dim
property
{
- "@context": ["http://www.w3.org/ns/td"],
+ "@context": ["http://www.w3.org/ns/td"],
"@type" : "ThingModel",
"links" : [{
"rel": "extends",
@@ -5898,7 +5901,7 @@ Examples
{
- "@context": ["http://www.w3.org/ns/td"],
+ "@context": ["http://www.w3.org/ns/td"],
"@type" : "Thing",
"title": "Smart Lamp Control",
"securityDefinitions": {
@@ -5926,15 +5929,15 @@ Examples
}
-
+
-
+