From 76ed6e1f19b8bcbc087621ff0bd37873cb912068 Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Wed, 10 Jan 2024 13:15:04 +0100 Subject: [PATCH 01/43] fix respec errors --- ontology/hctl.html | 36 +++++++++++++++++++++-- ontology/hctl.template.html | 36 +++++++++++++++++++++-- ontology/jsonschema.html | 36 +++++++++++++++++++++-- ontology/jsonschema.template.html | 36 +++++++++++++++++++++-- ontology/td.html | 32 +++++++++++---------- ontology/td.template.html | 32 +++++++++++---------- ontology/wotsec.html | 48 ++++++++++++++++++++++++++----- ontology/wotsec.template.html | 44 ++++++++++++++++++++++++---- ontology/wotsec.ttl | 4 +-- 9 files changed, 252 insertions(+), 52 deletions(-) diff --git a/ontology/hctl.html b/ontology/hctl.html index 2f208f9f1..a06ca185b 100644 --- a/ontology/hctl.html +++ b/ontology/hctl.html @@ -3,19 +3,20 @@ - Hypermedia Controls Ontology + Web of Things (WoT) Hypermedia Controls Ontology @@ -23,16 +24,49 @@

- This is required. + This document introduces an RDF vocabulary for the security metadata definitions. + This vocabulary provides a stable namespace IRI for security keywords, as well as simple axioms, defined against schema.org's meta-model. + Examples on how to use the vocabulary are also introduced.

-

- Validation of the document by the Working Group is expected by the end of June 2019. -

Introduction

+

+ +

+
+ +
+ +
+

Terminology

+ +

The fundamental WoT terminology such as + Thing, + Consumer, + Thing Description (TD), + Interaction Model, + Interaction Affordance, + Property, + Action, + Event, + Protocol Binding, + Servient, + etc. is defined in Section 3 + of the WoT Architecture specification [[WOT-ARCHITECTURE]]. +

+ +

+ The Thing Description terminology such as + TD Information Model, + TD Document, + Term (Vocabulary Term), TD Context Extension + etc. is defined in Section 3 + of the WoT Thing Description specification [[WOT-THING-DESCRIPTION]]. +

+
@@ -40,12 +74,12 @@

Introduction

AutoSecurityScheme

IRI: https://www.w3.org/2019/wot/security#AutoSecurityScheme

An automatic authentication security configuration identified by the term auto (i.e., "scheme": "auto"). This scheme indicates that the security parameters are going to be negotiated by the underlying protocols at runtime, subject to the respective specifications for the protocol (e.g. [[!RFC8288]] for Basic Authentication when using HTTP).
Sub-class ofwotsec:SecurityScheme

BasicSecurityScheme

IRI: https://www.w3.org/2019/wot/security#BasicSecurityScheme

Basic authentication security configuration identified by the term basic (i.e., "scheme": "basic"), using an unencrypted username and password.
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:in
wotsec:name

BearerSecurityScheme

IRI: https://www.w3.org/2019/wot/security#BearerSecurityScheme

Bearer token authentication security configuration identified by the term bearer (i.e., "scheme": "bearer"). This scheme is intended for situations where bearer tokens are used independently of OAuth2. If the oauth2 scheme is specified it is not generally necessary to specify this scheme as well as it is implied. For format, the value jwt indicates conformance with RFC7519, jws indicates conformance with RFC7797, cwt indicates conformance with RFC8392, and jwe indicates conformance with !RFC7516, with values for alg interpreted consistently with those standards. Other formats and algorithms for bearer tokens MAY be specified in vocabulary extensions.
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:alg
wotsec:authorization
wotsec:format
wotsec:in
wotsec:name
-

ComboSecurityScheme

IRI: https://www.w3.org/2019/wot/security#ComboSecurityScheme

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.

Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:allOf
wotsec:oneOf
+

ComboSecurityScheme

IRI: https://www.w3.org/2019/wot/security#ComboSecurityScheme

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.

Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:allOf
wotsec:oneOf

DigestSecurityScheme

IRI: https://www.w3.org/2019/wot/security#DigestSecurityScheme

Digest authentication security configuration identified by the term digest (i.e., "scheme": "digest"). This scheme is similar to basic authentication but with added features to avoid man-in-the-middle attacks.
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:in
wotsec:name
wotsec:qop

NoSecurityScheme

IRI: https://www.w3.org/2019/wot/security#NoSecurityScheme

A security configuration corresponding to identified by the term nosec (i.e., "scheme": "nosec"), indicating there is no authentication or other mechanism required to access the resource.
Sub-class ofwotsec:SecurityScheme

OAuth2SecurityScheme

IRI: https://www.w3.org/2019/wot/security#OAuth2SecurityScheme

OAuth 2.0 authentication security configuration for systems conformant with [[!RFC6749]] and [[!RFC8252]], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). For the code flow both authorization and token MUST be included. For the client flow token MUST be included. For the client flow authorization MUST NOT be included. The mandatory elements for each flow are summarized in the following table:
Elementcodeclient
authorizationmandatoryomit
tokenmandatorymandatory
refreshoptionaloptional

Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:authorization
wotsec:flow
wotsec:refresh
wotsec:scopes
wotsec:token

PSKSecurityScheme

IRI: https://www.w3.org/2019/wot/security#PSKSecurityScheme

Pre-shared key authentication security configuration identified by the 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]], and that the ciphersuite used for keys will be established during protocol negotiation.
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:identity
-

SecurityScheme

IRI: https://www.w3.org/2019/wot/security#SecurityScheme

Metadata describing the configuration of a security mechanism. The value assigned to the name scheme MUST be defined within a Vocabulary included in the Thing Description, either in the standard Vocabulary defined in § 5. TD Information Model or in a TD Context Extension.

For all security schemes, any keys, passwords, or other sensitive information directly providing access MUST NOT be stored in the TD and should instead be shared and stored out-of-band via other mechanisms. 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.

Each security scheme object used in a TD defines a set of requirements to be met before access can be granted. We say a security scheme is satisfied when all its requirements are met. In some cases requirements from multiple security schemes will have to be met before access can be granted.

Security schemes generally may require additional authentication parameters, such as a password or key. The location of this information is indicated by the value associated with the name in, often in combination with the value associated with name. The in name can take one of the following values:

header:
The parameter will be given 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 query parameter provided by name.
body:
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. 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. Since this value is not a fragment identifier, it also does not need to URL-encode special characters. The targeted element may or may not already exist at the specified location in the referenced data schema. If it does not, it will be inserted. This avoids having to duplicate definitions in the data schemas of every interaction. 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 be possible to insert the indicated element at the location indicated by the pointer.. For example, pointing to a key of a Map where that key does not exist in the corresponding Data Schema, the key and its value, which is the credential, would be inserted to the Map at the specified location during the operation execution. On the other hand, pointing to an Array's item with a number as the item index, that number should be outside the range of the Array's already specified items in order to not alter the strict sequence of items. The JSON pointer 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 body security information location 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 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 for in in a security scheme only if query is not applicable. The URIs provided in interactions where a security scheme using uri MUST be a URI template including the defined variable.
auto:
The location is determined as part of the protocol, or negotiated. If a value of auto is set for the in field of a SecurityScheme, then the name field SHOULD NOT be set. In this case, the application of the SecurityScheme is subject to the respective specification for the given protocol (e.g. [[!RFC8288]] when using the BasicSecurityScheme with HTTP).
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 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 declared in the TD.

Super-class ofwotsec:APIKeySecurityScheme
wotsec:AutoSecurityScheme
wotsec:BasicSecurityScheme
wotsec:BearerSecurityScheme
wotsec:ComboSecurityScheme
wotsec:DigestSecurityScheme
wotsec:NoSecurityScheme
wotsec:OAuth2SecurityScheme
wotsec:PSKSecurityScheme
In the domain ofwotsec:proxy
td:description
td:descriptionInLanguage
td:hasConfigurationInstance

Object Properties

allOf

IRI: https://www.w3.org/2019/wot/security#allOf

Array of two or more strings identifying other named security scheme definitions, all of which must be satisfied for access.
Domain includeswotsec:ComboSecurityScheme
+

SecurityScheme

IRI: https://www.w3.org/2019/wot/security#SecurityScheme

Metadata describing the configuration of a security mechanism. The value assigned to the name scheme MUST be defined within a Vocabulary included in the Thing Description, either in the standard Vocabulary defined in § 5. TD Information Model or in a TD Context Extension.

For all security schemes, any keys, passwords, or other sensitive information directly providing access MUST NOT be stored in the TD and should instead be shared and stored out-of-band via other mechanisms. 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.

Each security scheme object used in a TD defines a set of requirements to be met before access can be granted. We say a security scheme is satisfied when all its requirements are met. In some cases requirements from multiple security schemes will have to be met before access can be granted.

Security schemes generally may require additional authentication parameters, such as a password or key. The location of this information is indicated by the value associated with the name in, often in combination with the value associated with name. The in name can take one of the following values:

header:
The parameter will be given 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 query parameter provided by name.
body:
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. 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. Since this value is not a fragment identifier, it also does not need to URL-encode special characters. The targeted element may or may not already exist at the specified location in the referenced data schema. If it does not, it will be inserted. This avoids having to duplicate definitions in the data schemas of every interaction. 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 be possible to insert the indicated element at the location indicated by the pointer.. For example, pointing to a key of a Map where that key does not exist in the corresponding Data Schema, the key and its value, which is the credential, would be inserted to the Map at the specified location during the operation execution. On the other hand, pointing to an Array's item with a number as the item index, that number should be outside the range of the Array's already specified items in order to not alter the strict sequence of items. The JSON pointer 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 body security information location 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 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 for in in a security scheme only if query is not applicable. The URIs provided in interactions where a security scheme using uri MUST be a URI template including the defined variable.
auto:
The location is determined as part of the protocol, or negotiated. If a value of auto is set for the in field of a SecurityScheme, then the name field SHOULD NOT be set. In this case, the application of the SecurityScheme is subject to the respective specification for the given protocol (e.g. [[!RFC8288]] when using the BasicSecurityScheme with HTTP).
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 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 declared in the TD.

Super-class ofwotsec:APIKeySecurityScheme
wotsec:AutoSecurityScheme
wotsec:BasicSecurityScheme
wotsec:BearerSecurityScheme
wotsec:ComboSecurityScheme
wotsec:DigestSecurityScheme
wotsec:NoSecurityScheme
wotsec:OAuth2SecurityScheme
wotsec:PSKSecurityScheme
In the domain ofwotsec:proxy
td:description
td:descriptionInLanguage
td:hasConfigurationInstance

Object Properties

allOf

IRI: https://www.w3.org/2019/wot/security#allOf

Array of two or more strings identifying other named security scheme definitions, all of which must be satisfied for access.
Domain includeswotsec:ComboSecurityScheme

authorization

IRI: https://www.w3.org/2019/wot/security#authorization

URI of the authorization server.
Domain includeswotsec:BearerSecurityScheme
wotsec:OAuth2SecurityScheme

oneOf

IRI: https://www.w3.org/2019/wot/security#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.
Domain includeswotsec:ComboSecurityScheme

refresh

IRI: https://www.w3.org/2019/wot/security#refresh

URI of the refresh server.
Domain includeswotsec:OAuth2SecurityScheme
diff --git a/ontology/wotsec.template.html b/ontology/wotsec.template.html index 0925f72b5..eedf9e124 100644 --- a/ontology/wotsec.template.html +++ b/ontology/wotsec.template.html @@ -9,13 +9,14 @@ var respecConfig = { specStatus: "ED", latestVersion: null, + group: "wg/wot", editors: [{ name: "Victor Charpenay" }, { name: "Michael McCool" }], edDraftURI: "https://www.w3.org/2019/wot/security", - shortName: "wot-td-ontology" + shortName: "wot-sec-ontology" }; @@ -23,16 +24,49 @@

- This is required. + This document introduces an RDF vocabulary for the security metadata definitions. + This vocabulary provides a stable namespace IRI for security keywords, as well as simple axioms, defined against schema.org's meta-model. + Examples on how to use the vocabulary are also introduced.

-

- Validation of the document by the Working Group is expected by the end of June 2019. -

Introduction

+

+ +

+
+ +
+ +
+

Terminology

+ +

The fundamental WoT terminology such as + Thing, + Consumer, + Thing Description (TD), + Interaction Model, + Interaction Affordance, + Property, + Action, + Event, + Protocol Binding, + Servient, + etc. is defined in Section 3 + of the WoT Architecture specification [[WOT-ARCHITECTURE]]. +

+ +

+ The Thing Description terminology such as + TD Information Model, + TD Document, + Term (Vocabulary Term), TD Context Extension + etc. is defined in Section 3 + of the WoT Thing Description specification [[WOT-THING-DESCRIPTION]]. +

+
diff --git a/ontology/wotsec.ttl b/ontology/wotsec.ttl index 0237f1da2..53c6c8872 100644 --- a/ontology/wotsec.ttl +++ b/ontology/wotsec.ttl @@ -123,7 +123,7 @@ :ComboSecurityScheme rdf:type rdfs:Class, owl:Class ; rdfs:label "ComboSecurityScheme" ; rdfs:subClassOf :SecurityScheme ; - rdfs:comment "

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.

"@en . + rdfs:comment "

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.

"@en . # :CertSecurityScheme rdf:type rdfs:Class, owl:Class ; # rdfs:label "CertSecurityScheme" ; @@ -162,4 +162,4 @@ :SecurityScheme rdf:type rdfs:Class, owl:Class ; rdfs:label "SecurityScheme" ; - rdfs:comment "

Metadata describing the configuration of a security mechanism. The value assigned to the name scheme MUST be defined within a Vocabulary included in the Thing Description, either in the standard Vocabulary defined in § 5. TD Information Model or in a TD Context Extension.

For all security schemes, any keys, passwords, or other sensitive information directly providing access MUST NOT be stored in the TD and should instead be shared and stored out-of-band via other mechanisms. 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.

Each security scheme object used in a TD defines a set of requirements to be met before access can be granted. We say a security scheme is satisfied when all its requirements are met. In some cases requirements from multiple security schemes will have to be met before access can be granted.

Security schemes generally may require additional authentication parameters, such as a password or key. The location of this information is indicated by the value associated with the name in, often in combination with the value associated with name. The in name can take one of the following values:

header:
The parameter will be given 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 query parameter provided by name.
body:
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. 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. Since this value is not a fragment identifier, it also does not need to URL-encode special characters. The targeted element may or may not already exist at the specified location in the referenced data schema. If it does not, it will be inserted. This avoids having to duplicate definitions in the data schemas of every interaction. 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 be possible to insert the indicated element at the location indicated by the pointer.. For example, pointing to a key of a Map where that key does not exist in the corresponding Data Schema, the key and its value, which is the credential, would be inserted to the Map at the specified location during the operation execution. On the other hand, pointing to an Array's item with a number as the item index, that number should be outside the range of the Array's already specified items in order to not alter the strict sequence of items. The JSON pointer 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 body security information location 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 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 for in in a security scheme only if query is not applicable. The URIs provided in interactions where a security scheme using uri MUST be a URI template including the defined variable.
auto:
The location is determined as part of the protocol, or negotiated. If a value of auto is set for the in field of a SecurityScheme, then the name field SHOULD NOT be set. In this case, the application of the SecurityScheme is subject to the respective specification for the given protocol (e.g. [[!RFC8288]] when using the BasicSecurityScheme with HTTP).
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 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 declared in the TD.

" . + rdfs:comment "

Metadata describing the configuration of a security mechanism. The value assigned to the name scheme MUST be defined within a Vocabulary included in the Thing Description, either in the standard Vocabulary defined in § 5. TD Information Model or in a TD Context Extension.

For all security schemes, any keys, passwords, or other sensitive information directly providing access MUST NOT be stored in the TD and should instead be shared and stored out-of-band via other mechanisms. 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.

Each security scheme object used in a TD defines a set of requirements to be met before access can be granted. We say a security scheme is satisfied when all its requirements are met. In some cases requirements from multiple security schemes will have to be met before access can be granted.

Security schemes generally may require additional authentication parameters, such as a password or key. The location of this information is indicated by the value associated with the name in, often in combination with the value associated with name. The in name can take one of the following values:

header:
The parameter will be given 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 query parameter provided by name.
body:
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. 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. Since this value is not a fragment identifier, it also does not need to URL-encode special characters. The targeted element may or may not already exist at the specified location in the referenced data schema. If it does not, it will be inserted. This avoids having to duplicate definitions in the data schemas of every interaction. 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 be possible to insert the indicated element at the location indicated by the pointer.. For example, pointing to a key of a Map where that key does not exist in the corresponding Data Schema, the key and its value, which is the credential, would be inserted to the Map at the specified location during the operation execution. On the other hand, pointing to an Array's item with a number as the item index, that number should be outside the range of the Array's already specified items in order to not alter the strict sequence of items. The JSON pointer 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 body security information location 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 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 for in in a security scheme only if query is not applicable. The URIs provided in interactions where a security scheme using uri MUST be a URI template including the defined variable.
auto:
The location is determined as part of the protocol, or negotiated. If a value of auto is set for the in field of a SecurityScheme, then the name field SHOULD NOT be set. In this case, the application of the SecurityScheme is subject to the respective specification for the given protocol (e.g. [[!RFC8288]] when using the BasicSecurityScheme with HTTP).
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 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 declared in the TD.

" . From 9b37dc38b761eaaa564f554c9fcca724ffa965c7 Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Wed, 10 Jan 2024 13:46:32 +0100 Subject: [PATCH 02/43] add link to ttl file --- ontology/hctl.html | 10 ++++++++++ ontology/hctl.template.html | 10 ++++++++++ ontology/jsonschema.html | 10 ++++++++++ ontology/jsonschema.template.html | 10 ++++++++++ ontology/td.html | 12 +++++++++++- ontology/td.template.html | 12 +++++++++++- 6 files changed, 62 insertions(+), 2 deletions(-) diff --git a/ontology/hctl.html b/ontology/hctl.html index a06ca185b..950bfeb88 100644 --- a/ontology/hctl.html +++ b/ontology/hctl.html @@ -41,7 +41,17 @@ status : "Internet-Draft", date : " March 2019" } + }, + otherLinks: [{ + key: "Ontology in RDF", + data: [ + { + value: "Web of Things (WoT) Hypermedia Controls Ontology in RDF", + href: "hctl.ttl", + } + ] } + ] }; diff --git a/ontology/hctl.template.html b/ontology/hctl.template.html index f8ae636f2..ab702a1d0 100644 --- a/ontology/hctl.template.html +++ b/ontology/hctl.template.html @@ -41,7 +41,17 @@ status : "Internet-Draft", date : " March 2019" } + }, + otherLinks: [{ + key: "Ontology in RDF", + data: [ + { + value: "Web of Things (WoT) Hypermedia Controls Ontology in RDF", + href: "hctl.ttl", + } + ] } + ] }; diff --git a/ontology/jsonschema.html b/ontology/jsonschema.html index 8682448ac..2c53384a2 100644 --- a/ontology/jsonschema.html +++ b/ontology/jsonschema.html @@ -41,7 +41,17 @@ , status: "Internet-Draft" , publisher: "IETF" } + }, + otherLinks: [{ + key: "Ontology in RDF", + data: [ + { + value: "Web of Things (WoT) JSON Schema Ontology in RDF", + href: "jsonschema.ttl", + } + ] } + ] }; diff --git a/ontology/jsonschema.template.html b/ontology/jsonschema.template.html index ed8be39a7..288653671 100644 --- a/ontology/jsonschema.template.html +++ b/ontology/jsonschema.template.html @@ -41,7 +41,17 @@ , status: "Internet-Draft" , publisher: "IETF" } + }, + otherLinks: [{ + key: "Ontology in RDF", + data: [ + { + value: "Web of Things (WoT) JSON Schema Ontology in RDF", + href: "jsonschema.ttl", + } + ] } + ] }; diff --git a/ontology/td.html b/ontology/td.html index ffcfd70f4..15a14b696 100644 --- a/ontology/td.html +++ b/ontology/td.html @@ -28,7 +28,17 @@ , companyURL: "http://www.siemens.com/" }], edDraftURI: "https://www.w3.org/2019/wot/td", - shortName: "wot-td-ontology" + shortName: "wot-td-ontology", + otherLinks: [{ + key: "Ontology in RDF", + data: [ + { + value: "Web of Things (WoT) TD Ontology in RDF", + href: "td.ttl", + } + ] + } + ] }; + + + +Web of Things (WoT) Hypermedia Controls Ontology + + + + + + + + + + +
+

+

Web of Things (WoT) Hypermedia Controls Ontology

+

W3C Editor's Draft

+
+ More details about this document +
+
This version:
+ https://www.w3.org/2019/wot/hypermedia +
+
Latest published version:
+ none +
+
Latest editor's draft:
https://www.w3.org/2019/wot/hypermedia
+ + + + + + +
Editors:
+ Victor Charpenay +
+ Matthias Kovatsch +
+ + + + +
Ontology in RDF
+ Web of Things (WoT) Hypermedia Controls Ontology in RDF +
+
+
+ + +

+ Copyright + © + 2023 + + World Wide Web Consortium. + W3C® + liability, + trademark and + permissive document license rules apply. +

+
+
+

Abstract

+

+ This document introduces an ontology for links and forms, the main hypermedia + controls in use on the Web. This ontology offers, among others, a means to reify + RDF statements interpreted as links between Web resources. It also provides + a versatile exchange format for links and forms in RESTful Web applications. +

+ +

+ Hypermedia controls are of importance in the fields of the Web of Things and + the Embedded Web, in particular in the W3C Thing Description model and the IETF + Constrained RESTful Application Language. +

+
+

Status of This Document

This section describes the status of this + document at the time of its publication. A list of current W3C + publications and the latest revision of this technical report can be found + in the W3C technical reports index at + https://www.w3.org/TR/.

+

+ Validation of the document by the Working Group is expected by the end of June 2019. +

+

+ This document was published by the Web of Things Working Group as + an Editor's Draft. +

Publication as an Editor's Draft does not + imply endorsement by W3C and its Members.

+ This is a draft document and may be updated, replaced or obsoleted by other + documents at any time. It is inappropriate to cite this document as other + than work in progress. + +

+ + This document was produced by a group + operating under the + W3C Patent + Policy. + + + W3C maintains a + public list of any patent disclosures + made in connection with the deliverables of + the group; that page also includes + instructions for disclosing a patent. An individual who has actual + knowledge of a patent which the individual believes contains + Essential Claim(s) + must disclose the information in accordance with + section 6 of the W3C Patent Policy. + +

+ This document is governed by the + 03 November 2023 W3C Process Document. +

+

1. Introduction

+ + +

+ The concept of Representational State Transfer (REST) [rest] is at the core of most modern + Web applications. The state of a Web resources, exposed via a collection of Web + resources, can be browsed by clients by following links and acted upon by submitting + forms to servers. +

+ +

+ Links and forms have always be present in Web technologies, including HTML [html]. Web + linking [rfc8288] is a fundamental principle of the Web architecture that can be leveraged to + drive applications, e.g. when a server returns a link to a newly created resource as the + result of a client's request. Conversely, forms, are request templates that servers can expose + to clients for them to fill in with client-specific information and send back to servers. + Forms are similar in spirit to operation desriptions as defined by the Open API Specification + [openapis] or by the Hydra RDF vocabulary [hydra]. +

+ +

+ Links and forms are generically referred to as hypermedia controls. They are + of increasing importance in the fields of the Web of Things and the Embedded Web, + which respectively led to the standardization of the Thing Description (TD) model + [wot-thing-description] and the Constrained RESTful Application Language (CoRAL) + [coral]. The present hypermedia controls ontology is an attempt to formalize the + concepts these two standards specify. +

+
+ +

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

+ +

3. Terminology

+ + +

The fundamental WoT terminology such as + Thing, + Consumer, + Thing Description (TD), + Interaction Model, + Interaction Affordance, + Property, + Action, + Event, + Protocol Binding, + Servient, + etc. is defined in Section 3 + of the WoT Architecture specification [WOT-ARCHITECTURE]. +

+ +

+ The Thing Description terminology such as + TD Information Model, + TD Document, + Term (Vocabulary Term), + etc. is defined in Section 3 + of the WoT Thing Description specification [WOT-THING-DESCRIPTION]. +

+ +
+ + +

4. Axiomatization

4.1 Classes

4.1.1 AdditionalExpectedResponse

IRI: https://www.w3.org/2019/wot/hypermedia#AdditionalExpectedResponse

Communication metadata describing the expected response message for additional responses.
In the domain ofhctl:hasAdditionalOutputSchema
hctl:isSuccess
In the range ofhctl:additionalReturns
+

4.1.2 ExpectedResponse

IRI: https://www.w3.org/2019/wot/hypermedia#ExpectedResponse

Communication metadata describing the expected response message for the primary response.
In the range ofhctl:returns
+

4.1.3 Form

IRI: https://www.w3.org/2019/wot/hypermedia#Form

A form can be viewed as a statement of "To perform an operation type operation on form context, make a request method request to submission target" where the optional form fields may further describe the required request. In Thing Descriptions, the form context is the surrounding Object, such as Properties, Actions, and Events or the Thing itself for meta-interactions.
In the domain ofhctl:additionalReturns
hctl:forContentCoding
hctl:forContentType
hctl:forSubProtocol
hctl:hasOperationType
hctl:hasTarget
hctl:returns
td:hasSecurityConfiguration
In the range oftd:hasForm
+

4.2 Object Properties

4.2.1 additionalReturns

IRI: https://www.w3.org/2019/wot/hypermedia#additionalReturns

This optional term can be used if additional expected responses + 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 response code), and may also have its own data schema.
Domain includeshctl:Form
Range includeshctl:AdditionalExpectedResponse
+

4.2.2 hasAdditionalOutputSchema

IRI: https://www.w3.org/2019/wot/hypermedia#hasAdditionalOutputSchema

This optional term can be used to define a data schema for + an additional response if it differs from the default + output data schema. + Rather than a DataSchema object, the + name of a previous definition given in a + schemaDefinitions map must be used.
Domain includeshctl:AdditionalExpectedResponse
+

4.2.3 hasOperationType

IRI: https://www.w3.org/2019/wot/hypermedia#hasOperationType

Indicates the semantic intention of performing the operation(s) described by the form.
Domain includeshctl:Form
+

4.2.4 returns

IRI: https://www.w3.org/2019/wot/hypermedia#returns

This optional term can be used if, e.g., the output communication metadata differ from input metadata (e.g., output contentType differ from the + input contentType). The response name contains metadata that is only valid for the reponse messages.
Domain includeshctl:Form
Range includeshctl:ExpectedResponse

4.3 Datatype Properties

4.3.1 forContentCoding

IRI: https://www.w3.org/2019/wot/hypermedia#forContentCoding

Content coding values indicate an encoding transformation that has been or can be applied to a representation. Content codings are primarily used to allow a representation to be compressed or otherwise usefully transformed without losing the identity of its underlying media type and without loss of information. Examples of content coding include "gzip", "deflate", etc.
Domain includeshctl:Form
Range includesschema:Text
+

4.3.2 forContentType

IRI: https://www.w3.org/2019/wot/hypermedia#forContentType

Assign a content type based on a media type [IANA-MEDIA-TYPES] (e.g., 'text/plain') and potential parameters (e.g., 'charset=utf-8') for the media type.
Domain includeshctl:Form
Range includesschema:Text
+

4.3.3 forSubProtocol

IRI: https://www.w3.org/2019/wot/hypermedia#forSubProtocol

Indicates the exact mechanism by which an interaction will be accomplished for a given protocol when there are multiple options. + +For example, for HTTP and Events, it indicates which of several available mechanisms should be used for asynchronous notifications such as long polling, websub (also see https://www.w3.org/TR/websub/), or server sent events (also see https://www.w3.org/TR/eventsource/). Please note that there is no restriction on the sub-protocol selection and other mechanisms can also be announced by this subprotocol term.
Domain includeshctl:Form
Range includesschema:Text
+

4.3.4 hasAnchor

IRI: https://www.w3.org/2019/wot/hypermedia#hasAnchor

By default, the context, or anchor, of a link conveyed in the Link header field is the URL of the representation it is associated with, as defined in RFC7231, Section 3.1.4.1, and is serialized as a URI.
Domain includeshctl:Link
+

4.3.5 hasHreflang

IRI: https://www.w3.org/2019/wot/hypermedia#hasHreflang

The hreflang attribute specifies the language of a linked document. The value of this must be a valid language tag [BCP47].
Domain includeshctl:Link
+

4.3.6 hasRelationType

IRI: https://www.w3.org/2019/wot/hypermedia#hasRelationType

A link relation type identifies the semantics of a link.
Domain includeshctl:Link
+

4.3.7 hasSizes

IRI: https://www.w3.org/2019/wot/hypermedia#hasSizes

Target attribute that specifies one or more sizes for the referenced icon. Only applicable for relation type 'icon'. The value pattern follows {Height}x{Width} (e.g., "16x16", "16x16 32x32")
Domain includeshctl:Link
+

4.3.8 hasTarget

IRI: https://www.w3.org/2019/wot/hypermedia#hasTarget

target IRI of a link or submission target of a form.
Domain includeshctl:Form
hctl:Link
+

4.3.9 hintsAtMediaType

IRI: https://www.w3.org/2019/wot/hypermedia#hintsAtMediaType

Target attribute providing a hint indicating what the media type [IANA-MEDIA-TYPES] of the result of dereferencing the link should be.
Domain includeshctl:Link
Range includesschema:Text
+

4.3.10 isSuccess

IRI: https://www.w3.org/2019/wot/hypermedia#isSuccess

Signals if the additional response should not be considered an error.
Domain includeshctl:AdditionalExpectedResponse
Range includesschema:Boolean

4.4 Annotation Properties

No AnnotationProperty found in the ontology.

+ +

5. Alignments

+ + +

5.1 Hydra

+ + +

+ The following table gives alignment between the hypermedia controls + ontology and Hydra, + an alternative vocabulary for hypermedia-driven Web APIs. Each row + represents a close match between two classes. These alignments are + not to be understood as formal semantic equivalences but rather as + hints to Hydra users. +

+ + + + + + + + + + + + +
hctl:Linkhydra:Link
hctl:Formhydra:Operation
+
+
+ +

6. Usage Examples

+ + + + + +
+ + + + + +

A. References

A.1 Normative references

+ +
[BCP47]
+ Tags for Identifying Languages. A. Phillips, Ed.; M. Davis, Ed.. IETF. September 2009. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc5646 +
[coral]
+ The Constrained RESTful Application Language (CoRAL). Klaus Hartke. IETF. March 2019. Internet-Draft. URL: https://tools.ietf.org/html/draft-hartke-t2trg-coral +
[html]
+ HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/ +
[hydra]
+ Hydra Core Vocabulary. Markus Lanthaler. Hydra W3C Community Group. URL: https://www.hydra-cg.com/spec/latest/core/ +
[IANA-MEDIA-TYPES]
+ Media Types. IANA. URL: https://www.iana.org/assignments/media-types/ +
[openapis]
+ OpenAPI Specification. Darrell Miller; Jeremy Whitlock; Marsh Gardiner; Mike Ralphson; Ron Ratovsky; Uri Sarid; Tony Tam; Jason Harmon. OpenAPI Initiative. URL: https://www.openapis.org/ +
[rest]
+ REST: Architectural Styles and the Design of Network-based Software Architectures. University of California, Irvine. 2000. PhD thesis. +
[rfc8288]
+ Web Linking. M. Nottingham. IETF. October 2017. Proposed Standard. URL: https://httpwg.org/specs/rfc8288.html +
[WOT-ARCHITECTURE]
+ Web of Things (WoT) Architecture. Matthias Kovatsch; Ryuichi Matsukura; Michael Lagally; Toru Kawaguchi; Kunihiko Toumura; Kazuo Kajimoto. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-architecture/ +
[wot-thing-description]
+ Web of Things (WoT) Thing Description. Sebastian Käbisch; Takuki Kamiya; Michael McCool; Victor Charpenay; Matthias Kovatsch. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-thing-description/ +
+
\ No newline at end of file diff --git a/publication/ver11/7-resources/ontology/staticFiles/jsonschema.html b/publication/ver11/7-resources/ontology/staticFiles/jsonschema.html new file mode 100644 index 000000000..7c2db5f83 --- /dev/null +++ b/publication/ver11/7-resources/ontology/staticFiles/jsonschema.html @@ -0,0 +1,1198 @@ + + + + + + + + + +Web of Things (WoT) JSON Schema Ontology + + + + + + + + + + +
+

+

Web of Things (WoT) JSON Schema Ontology

+

W3C Editor's Draft

+
+ More details about this document +
+
This version:
+ https://www.w3.org/2019/wot/json-schema +
+
Latest published version:
+ none +
+
Latest editor's draft:
https://www.w3.org/2019/wot/json-schema
+ + + + + + +
Editors:
+ Victor Charpenay +
+ Maxime Lefrançois +
+ María Poveda Villalón +
+ + + + +
Ontology in RDF
+ Web of Things (WoT) JSON Schema Ontology in RDF +
+
+
+ + +

+ Copyright + © + 2023 + + World Wide Web Consortium. + W3C® + liability, + trademark and + permissive document license rules apply. +

+
+
+

Abstract

+

+ This document introduces an RDF vocabulary for JSON schema definitions. + This vocabulary provides a stable namespace IRI for JSON schema keywords, + as well as simple axioms, defined against schema.org's meta-model. Various + examples on how to use the vocabulary are also introduced, e.g. to annotate + schemas with JSON-LD metadata or to embed schema annotations inside RDF + graphs. +

+
+

Status of This Document

This section describes the status of this + document at the time of its publication. A list of current W3C + publications and the latest revision of this technical report can be found + in the W3C technical reports index at + https://www.w3.org/TR/.

+

+ Validation of the document by the Working Group is expected by the end of June 2019. +

+

+ This document was published by the Web of Things Working Group as + an Editor's Draft. +

Publication as an Editor's Draft does not + imply endorsement by W3C and its Members.

+ This is a draft document and may be updated, replaced or obsoleted by other + documents at any time. It is inappropriate to cite this document as other + than work in progress. + +

+ + This document was produced by a group + operating under the + W3C Patent + Policy. + + + W3C maintains a + public list of any patent disclosures + made in connection with the deliverables of + the group; that page also includes + instructions for disclosing a patent. An individual who has actual + knowledge of a patent which the individual believes contains + Essential Claim(s) + must disclose the information in accordance with + section 6 of the W3C Patent Policy. + +

+ This document is governed by the + 03 November 2023 W3C Process Document. +

+

1. Introduction

+ + +

+ JSON schema is a popular schema language for JSON documents + [json-schema-validation]. This vocabulary includes the main terms + defined by JSON schema in order to represent schema definitions in RDF. + Besides providing a stable namespace IRI for JSON schema terms, this + vocabulary also includes axioms based on schema.org's meta-model. Its + design favors simplicity of use over completeness. +

+ +

+ Representing JSON schema in RDF was originally intended to be used + as part of the W3C Web of Things (WoT) framework and in particular in + the Thing Description model [wot-thing-description]. However, + processing JSON schema in RDF is not limited to WoT. Other use cases + include: +

+ +
    +
  • Alignment of schema definitions with RDF vocabularies and RDF shapes
    • +
  • Rule-based validation or transformation of JSON data
    • +
  • Integration of various forms of data specfications, including JSON schema
    • +
+ +

+ incidentally, the RDF representation of JSON schema definitions + provides an alternative to the JSON hyper-schema [json-hyper-schema] + for cross-references and linking. Examples are provided at the end + of the document. +

+
+ +

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

+ +

3. Terminology

+ + +

The fundamental WoT terminology such as + Thing, + Consumer, + Thing Description (TD), + Interaction Model, + Interaction Affordance, + Property, + Action, + Event, + Protocol Binding, + Servient, + etc. is defined in Section 3 + of the WoT Architecture specification [WOT-ARCHITECTURE]. +

+ +

+ The Thing Description terminology such as + TD Information Model, + TD Document, + Term (Vocabulary Term), + etc. is defined in Section 3 + of the WoT Thing Description specification [WOT-THING-DESCRIPTION]. +

+ +
+ + +

4. Axiomatization

4.1 Classes

4.1.1 ArraySchema

IRI: https://www.w3.org/2019/wot/json-schema#ArraySchema

Metadata describing data of type array. This subclass is indicated by the value array assigned to type in DataSchema instances.
Sub-class ofjsonschema:DataSchema
In the domain ofjsonschema:items
jsonschema:maxItems
jsonschema:minItems
+

4.1.2 BooleanSchema

IRI: https://www.w3.org/2019/wot/json-schema#BooleanSchema

Metadata describing data of type boolean. This subclass is indicated by the value boolean assigned to type in DataSchema instances.
Sub-class ofjsonschema:DataSchema
+

4.1.3 DataSchema

IRI: https://www.w3.org/2019/wot/json-schema#DataSchema

Metadata that describes the data format used. It can be used for validation.
Super-class ofjsonschema:ArraySchema
jsonschema:BooleanSchema
jsonschema:IntegerSchema
jsonschema:NullSchema
jsonschema:NumberSchema
jsonschema:ObjectSchema
jsonschema:StringSchema
In the domain ofjsonschema:allOf
jsonschema:anyOf
jsonschema:const
jsonschema:default
jsonschema:enum
jsonschema:oneOf
jsonschema:propertyName
jsonschema:readOnly
jsonschema:writeOnly
td:description
td:descriptionInLanguage
td:title
td:titleInLanguage
In the range ofjsonschema:allOf
jsonschema:anyOf
jsonschema:items
jsonschema:oneOf
jsonschema:properties
+

4.1.4 IntegerSchema

IRI: https://www.w3.org/2019/wot/json-schema#IntegerSchema

Metadata describing data of type integer. This subclass is indicated by the value integer assigned to type in DataSchema instances.
Sub-class ofjsonschema:DataSchema
In the domain ofjsonschema:exclusiveMaximum
jsonschema:exclusiveMinimum
jsonschema:maximum
jsonschema:minimum
jsonschema:multipleOf
+

4.1.5 NullSchema

IRI: https://www.w3.org/2019/wot/json-schema#NullSchema

Metadata describing data of type null. This subclass is indicated by the value null assigned to type in DataSchema instances. This Subclass describes only one acceptable value, namely null. It is important to note that null does not mean the absence of a value. It is analogous to null in JavaScript, None in Python, null in Java and nil in Ruby programming languages. It can be used as part of a oneOf declaration, where it is used to indicate, that the data can also be null.
Sub-class ofjsonschema:DataSchema
+

4.1.6 NumberSchema

IRI: https://www.w3.org/2019/wot/json-schema#NumberSchema

Metadata describing data of type number. This subclass is indicated by the value number assigned to type in DataSchema instances.
Sub-class ofjsonschema:DataSchema
In the domain ofjsonschema:exclusiveMaximum
jsonschema:exclusiveMinimum
jsonschema:maximum
jsonschema:minimum
jsonschema:multipleOf
+

4.1.7 ObjectSchema

IRI: https://www.w3.org/2019/wot/json-schema#ObjectSchema

Metadata describing data of type object. This subclass is indicated by the value object assigned to type in DataSchema instances.
Sub-class ofjsonschema:DataSchema
In the domain ofjsonschema:properties
jsonschema:required
+

4.1.8 StringSchema

IRI: https://www.w3.org/2019/wot/json-schema#StringSchema

Metadata describing data of type string. This subclass is indicated by the value string assigned to type in DataSchema instances.
Sub-class ofjsonschema:DataSchema
In the domain ofjsonschema:contentEncoding
jsonschema:contentMediaType
jsonschema:format
jsonschema:maxLength
jsonschema:minLength
jsonschema:pattern

4.2 Object Properties

4.2.1 allOf

IRI: https://www.w3.org/2019/wot/json-schema#allOf

Used to ensure that the data is valid against all of the specified schemas in the array.
Domain includesjsonschema:DataSchema
Range includesjsonschema:DataSchema
+

4.2.2 anyOf

IRI: https://www.w3.org/2019/wot/json-schema#anyOf

Used to ensure that the data is valid against any of the specified schemas in the array.
Domain includesjsonschema:DataSchema
Range includesjsonschema:DataSchema
+

4.2.3 items

IRI: https://www.w3.org/2019/wot/json-schema#items

Used to define the characteristics of an array.
Domain includesjsonschema:ArraySchema
Range includesjsonschema:DataSchema
+

4.2.4 oneOf

IRI: https://www.w3.org/2019/wot/json-schema#oneOf

Used to ensure that the data is valid against exactly one of the specified schemas in the array.
Domain includesjsonschema:DataSchema
Range includesjsonschema:DataSchema
+

4.2.5 properties

IRI: https://www.w3.org/2019/wot/json-schema#properties

Data schema nested definitions
Domain includesjsonschema:ObjectSchema
Range includesjsonschema:DataSchema

4.3 Datatype Properties

4.3.1 const

IRI: https://www.w3.org/2019/wot/json-schema#const

Provides a constant value.
Domain includesjsonschema:DataSchema
+

4.3.2 contentEncoding

IRI: https://www.w3.org/2019/wot/json-schema#contentEncoding

Specifies the encoding used to store the contents, as specified in RFC 2054. The values that are accepted: "7bit", "8bit", "binary", "quoted-printable" and "base64".
Domain includesjsonschema:StringSchema
+

4.3.3 contentMediaType

IRI: https://www.w3.org/2019/wot/json-schema#contentMediaType

Specifies the MIME type (e.g., image/png, audio/mpeg) of the contents of a string value, as described in RFC 2046.
Domain includesjsonschema:StringSchema
+

4.3.4 default

IRI: https://www.w3.org/2019/wot/json-schema#default

Supply a default value. The value should validate against the data schema in which it resides.
Domain includesjsonschema:DataSchema
+

4.3.5 enum

IRI: https://www.w3.org/2019/wot/json-schema#enum

Restricted set of values provided as an array.
Domain includesjsonschema:DataSchema
+

4.3.6 exclusiveMaximum

IRI: https://www.w3.org/2019/wot/json-schema#exclusiveMaximum

Specifies a maximum numeric value, representing an exclusive upper limit. Only applicable for associated number or integer types.
Domain includesjsonschema:IntegerSchema
jsonschema:NumberSchema
+

4.3.7 exclusiveMinimum

IRI: https://www.w3.org/2019/wot/json-schema#exclusiveMinimum

Specifies a minimum numeric value, representing an exclusive lower limit. Only applicable for associated number or integer types.
Domain includesjsonschema:IntegerSchema
jsonschema:NumberSchema
+

4.3.8 format

IRI: https://www.w3.org/2019/wot/json-schema#format

Allows validation based on a format pattern such as "date-time", "email", "uri", etc.
Domain includesjsonschema:StringSchema
+

4.3.9 maxItems

IRI: https://www.w3.org/2019/wot/json-schema#maxItems

Defines the maximum number of items that have to be in the array.
Domain includesjsonschema:ArraySchema
+

4.3.10 maxLength

IRI: https://www.w3.org/2019/wot/json-schema#maxLength

Specifies the maximum length of a string. Only applicable for associated string types.
Domain includesjsonschema:StringSchema
+

4.3.11 maximum

IRI: https://www.w3.org/2019/wot/json-schema#maximum

Specifies a maximum numeric value, representing an inclusive upper limit. Only applicable for associated number or integer types.
Domain includesjsonschema:IntegerSchema
jsonschema:NumberSchema
+

4.3.12 minItems

IRI: https://www.w3.org/2019/wot/json-schema#minItems

Defines the minimum number of items that have to be in the array.
Domain includesjsonschema:ArraySchema
+

4.3.13 minLength

IRI: https://www.w3.org/2019/wot/json-schema#minLength

Specifies the minimum length of a string. Only applicable for associated string types.
Domain includesjsonschema:StringSchema
+

4.3.14 minimum

IRI: https://www.w3.org/2019/wot/json-schema#minimum

Specifies a minimum numeric value, representing an inclusive lower limit. Only applicable for associated number or integer types.
Domain includesjsonschema:IntegerSchema
jsonschema:NumberSchema
+

4.3.15 multipleOf

IRI: https://www.w3.org/2019/wot/json-schema#multipleOf

Specifies the multipleOf value number. The value must strictly greater than 0. Only applicable for associated number or integer types.
Domain includesjsonschema:IntegerSchema
jsonschema:NumberSchema
+

4.3.16 pattern

IRI: https://www.w3.org/2019/wot/json-schema#pattern

Provides a regular expression to express constraints of the string value. The regular expression must follow the ECMA 262 dialect.
Domain includesjsonschema:StringSchema
+

4.3.17 propertyName

IRI: https://www.w3.org/2019/wot/json-schema#propertyName

Used to store the indexing name in the parent object when this schema appears as a property of an object schema.
Domain includesjsonschema:DataSchema
+

4.3.18 readOnly

IRI: https://www.w3.org/2019/wot/json-schema#readOnly

Boolean value that is a hint to indicate whether a property interaction / value is read only (=true) or not (=false)
Domain includesjsonschema:DataSchema
+

4.3.19 required

IRI: https://www.w3.org/2019/wot/json-schema#required

Defines which members of the object type are mandatory, i.e. which members are mandatory in the payload that is to be sent (e.g. input of invokeaction, writeproperty) and what members will be definitely delivered in the payload that is being received (e.g. output of invokeaction, readproperty)
Domain includesjsonschema:ObjectSchema
+

4.3.20 writeOnly

IRI: https://www.w3.org/2019/wot/json-schema#writeOnly

Boolean value that is a hint to indicate whether a property interaction / value is write only (=true) or not (=false)
Domain includesjsonschema:DataSchema

4.4 Annotation Properties

No AnnotationProperty found in the ontology.

+ +

5. Usage Examples

+ + +

5.1 Interpreting JSON Schema as JSON-LD 1.1

+ + +

+ The following JSON-LD context [json-ld11] can be added to JSON schema + definitions to obtain an RDF representation of these definitions. +

+ + + +

+ The two following examples show the equivalence between the + JSON and the Turtle representations of schema definitions. + These examples were taken from the + collection of schemas managed by the Open Connectivity + Foundation (OCF). +

+ + + + + +
Note

+ The value defined for the const and enum terms + is always interpreted as a raw JSON value, even if it is an array or an + object. In RDF, it becomes a typed literal with datatype rdf:JSON. +

+ +
Note

+ In its latest version, the JSON schema items term can be interpreted + in two different ways: if the value is a single schema definition, all items in + the array must then be proper instance of that schema ; if the value is an array + of schema definitions, an item in the instance array must be an instance of the + schema at the same index in the schema array. In the latter case, the schema + array should be interpreted as an RDF list rather as a set of statement (to + preserve order). It is however not possible to express both cases with a single + JSON-LD context. The context given in Example 1 only + reflects the former case. +

+ +
Note

+ JSON schema allows schemas to be defined in a "collection" object under + definitions. This feature is purely syntactical, hence not reflected + in the present RDF vocabulary for JSON schema. Interpreting schemas under + definitions as JSON-LD requires prior normalization, by substituting + references in the main schema with their definition. This normalization procedure + may be directly supported by JSON-LD processors in the future. +

+ +
Note

+ The JSON Schema RDF vocabulary does not include terms for title + and description. Instead, the example context maps them to widely + used Dublin Core terms with equivalent semantics. +

+
+ +

5.2 Referencing and linking

+ + +

+ JSON schema defines the $id and $ref keywords + to increase reusability but also to define schemas in a recursive fashion. + This feature is natively supported by RDF: if schema definitions are named + resources (identified by an IRI) instead of blank nodes, they can be + referenced from anywhere on the Web. +

+ +

+ The id keyword (an alias for @id) can be used for + that purpose, as shown in the following example, taken from an OCF standard. +

+ + + +
Note

+ If the same schema definition (with the same IRI) is used twice as the + value of one of the properties of an object schema, it may result + in name collisions. Indeed, after transformation to RDF, this schema will have + two statements with :propertyValue that do not link back to the + object from which they respectively originate. +

+ +

+ Besides IRI references between schemas, JSON hyper-schema [json-hyper-schema] + allows arbitrary links to be embedded in a schema definition. An alternative to + JSON hyper-schema is to use plain RDF statements or the + RDF vocabulary for hypermedia + controls. Examples can be found in the documentation of that vocabulary. +

+
+ +

5.3 Defining a JSON-LD context for data instances

+ + +

+ JSON schema definitions may specify JSON structures that + are themselves interpretable as RDF (or JSON-LD). To be able + to do so, instances of a certain schema must be given a + JSON-LD context to map JSON terms to RDF IRIs. This can be + done within a schema definition using the + JSON-LD vocabulary in RDF, + and more precisely with the property jsonld:context. +

+ + + +

+ The example above allows schema-aware agents on the Web to interpret + any instance of the schema as JSON-LD by appending the context given + as annotation to the instance JSON, as shown below. +

+ + + +

+ Note the difference with using @context in the + schema definition: it is used to interpret instances + as JSON-LD, while @context would alter the way + the schema itself is interpreted. +

+ +

+ The JSON-LD vocabulary in RDF includes terms to represent any JSON-LD + context in RDF. As a result, contexts can be directly embedded in JSON + schema definitions as well. The example below is a variant of + Example 6 in which only a subset of schema.org's default + context is embedded in the schema. +

+ + +
+ +

5.4 Embedding schema definitions in data instances

+ + +

+ Although schema definitions are often put in separate documents, it may + be convenient to embed them in instance data itself, as in the following + example, which uses the Smart Appliance Reference vocabulary (SAREF) + [smartm2m]. This usage of the JSON schema vocabulary is similar to that + of schema:PropertyValue + and schema:PropertyValueSpecification. +

+ + + +

+ This way, it is possible to convey a JSON tree representation + that does not strictly follow the RDF structure of some entity. + In the following example, the temperature property expressed + in SAREF terms embeds a variant of the schema of + Example 3. +

+ + +
+
+ + + + + + +

A. References

A.1 Normative references

+ +
[json-hyper-schema]
+ JSON Hyper-Schema: A Vocabulary for Hypermedia Annotation of JSON. Henry Andrews; Austin Wright. IETF. Internet-Draft. URL: https://tools.ietf.org/html/draft-handrews-json-schema-hyperschema-00 +
[json-ld11]
+ JSON-LD 1.1. Gregg Kellogg; Pierre-Antoine Champin; Dave Longley. W3C. 16 July 2020. W3C Recommendation. URL: https://www.w3.org/TR/json-ld11/ +
[json-schema-validation]
+ JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Austin Wright; Henry Andrews; Geraint Luff. IETF. Internet-Draft. URL: https://tools.ietf.org/html/draft-handrews-json-schema-validation-00 +
[smartm2m]
+ ETSI TS 103 264 V2.1.1 (2017-03): SmartM2M; Smart Appliances; Reference Ontology and oneM2M Mapping. ETSI. March 2017. Published. URL: http://www.etsi.org/deliver/etsi_ts/103200_103299/103264/02.01.01_60/ts_103264v020101p.pdf +
[WOT-ARCHITECTURE]
+ Web of Things (WoT) Architecture. Matthias Kovatsch; Ryuichi Matsukura; Michael Lagally; Toru Kawaguchi; Kunihiko Toumura; Kazuo Kajimoto. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-architecture/ +
[wot-thing-description]
+ Web of Things (WoT) Thing Description. Sebastian Käbisch; Takuki Kamiya; Michael McCool; Victor Charpenay; Matthias Kovatsch. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-thing-description/ +
+
\ No newline at end of file diff --git a/publication/ver11/7-resources/ontology/staticFiles/td.html b/publication/ver11/7-resources/ontology/staticFiles/td.html new file mode 100644 index 000000000..cb4472787 --- /dev/null +++ b/publication/ver11/7-resources/ontology/staticFiles/td.html @@ -0,0 +1,1280 @@ + + + + + + + + +Web of Things (WoT) Thing Description (TD) Ontology + + + + + + + + + + + + +
+

+

Web of Things (WoT) Thing Description (TD) Ontology

+

W3C Editor's Draft

+
+ More details about this document +
+
This version:
+ https://www.w3.org/2019/wot/td +
+
Latest published version:
+ none +
+
Latest editor's draft:
https://www.w3.org/2019/wot/td
+ + + + + + +
Editors:
+ Victor Charpenay (Siemens AG) +
+ Maxime Lefrançois (École des Mines de Saint-Étienne) +
+ María Poveda Villalón (Universidad Politécnica de Madrid) +
+ Sebastian Käbisch (Siemens AG) +
+ + + + +
Ontology in RDF
+ Web of Things (WoT) TD Ontology in RDF +
+
+
+ + +

+ Copyright + © + 2023 + + World Wide Web Consortium. + W3C® + liability, + trademark and + permissive document license rules apply. +

+
+
+

Abstract

+

+ The Thing Description (TD) ontology is an RDF axiomatization of the TD information model, + one of the building blocks of the Web of Things (WoT). Besides providing an alternative + to the standard JSON representation format for TD documents, the TD ontology can also + be used to process contextual information on Things and for alignments with other + WoT-related ontologies. +

+
+

Status of This Document

This section describes the status of this + document at the time of its publication. A list of current W3C + publications and the latest revision of this technical report can be found + in the W3C technical reports index at + https://www.w3.org/TR/.

+

+ Validation of the document by the Working Group is expected by the end of June 2019. +

+

+ This document was published by the Web of Things Working Group as + an Editor's Draft. +

Publication as an Editor's Draft does not + imply endorsement by W3C and its Members.

+ This is a draft document and may be updated, replaced or obsoleted by other + documents at any time. It is inappropriate to cite this document as other + than work in progress. + +

+ + This document was produced by a group + operating under the + W3C Patent + Policy. + + + W3C maintains a + public list of any patent disclosures + made in connection with the deliverables of + the group; that page also includes + instructions for disclosing a patent. An individual who has actual + knowledge of a patent which the individual believes contains + Essential Claim(s) + must disclose the information in accordance with + section 6 of the W3C Patent Policy. + +

+ This document is governed by the + 03 November 2023 W3C Process Document. +

+

1. Introduction

+ + +

+ The TD ontology is an idiomatic RDF axiomatization of the TD information model [WOT-THING-DESCRIPTION], + which can be used to describe WoT things and their interaction affordances. The TD ontology imports + the hypermedia controls ontology. + However, although the TD information model also includes terms for data schemas and security + configurations, the TD ontology does not force the use of the corresponding + JSON schema and + WoT security vocabularies. Other schema languages + like SHACL [shacl] can thus be leveraged to describe WoT Things. +

+
+ +

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

+ +

3. Terminology

+ + +

The fundamental WoT terminology such as + Thing, + Consumer, + Thing Description (TD), + Interaction Model, + Interaction Affordance, + Property, + Action, + Event, + Protocol Binding, + Servient, + etc. is defined in Section 3 + of the WoT Architecture specification [WOT-ARCHITECTURE]. +

+ +

+ The Thing Description terminology such as + TD Information Model, + TD Document, + Term (Vocabulary Term), + etc. is defined in Section 3 + of the WoT Thing Description specification [WOT-THING-DESCRIPTION]. +

+ +
+ + +

4. Axiomatization

4.1 Classes

4.1.1 ActionAffordance

IRI: https://www.w3.org/2019/wot/td#ActionAffordance

An Interaction Affordance that allows to invoke a function of the Thing, which manipulates state (e.g., toggling a lamp on or off) or triggers a process on the Thing (e.g., dim a lamp over time).
Sub-class oftd:InteractionAffordance
In the domain oftd:hasInputSchema
td:hasOutputSchema
td:isIdempotent
td:isSafe
td:isSynchronous
In the range oftd:hasActionAffordance
+

4.1.2 EventAffordance

IRI: https://www.w3.org/2019/wot/td#EventAffordance

An Interaction Affordance that describes an event source, which asynchronously pushes event data to Consumers (e.g., overheating alerts).
Sub-class oftd:InteractionAffordance
In the domain oftd:hasCancellationSchema
td:hasNotificationResponseSchema
td:hasNotificationSchema
td:hasSubscriptionSchema
In the range oftd:hasEventAffordance
+

4.1.3 InteractionAffordance

IRI: https://www.w3.org/2019/wot/td#InteractionAffordance

Metadata of a Thing that shows the possible choices to Consumers, thereby suggesting how Consumers may interact with the Thing. There are many types of potential affordances, but W3C WoT defines three types of Interaction Affordances: Properties, Actions, and Events.
Super-class oftd:ActionAffordance
td:EventAffordance
td:PropertyAffordance
In the domain oftd:description
td:descriptionInLanguage
td:hasForm
td:hasUriTemplateSchema
td:name
td:title
td:titleInLanguage
In the range oftd:hasInteractionAffordance
+

4.1.4 OperationType

IRI: https://www.w3.org/2019/wot/td#OperationType

Enumeration of well-known operation types necessary to implement the WoT interaction model
Enumeration memberstd:cancelAction
td:invokeAction
td:observeAllProperties
td:observeProperty
td:queryAction
td:queryAllActions
td:readAllProperties
td:readMultipleProperties
td:readProperty
td:subscribeAllEvents
td:subscribeEvent
td:unobserveAllProperties
td:unobserveProperty
td:unsubscribeAllEvents
td:unsubscribeEvent
td:writeAllProperties
td:writeMultipleProperties
td:writeProperty
+

4.1.5 PropertyAffordance

IRI: https://www.w3.org/2019/wot/td#PropertyAffordance

An Interaction Affordance that exposes state of the Thing. This state can then be retrieved (read) and/or updated (write). Things can also choose to make Properties observable by pushing the new state after a change.
Sub-class oftd:InteractionAffordance
In the domain oftd:isObservable
In the range oftd:hasPropertyAffordance
+

4.1.6 Thing

IRI: https://www.w3.org/2019/wot/td#Thing

An abstraction of a physical or a virtual entity whose metadata and interfaces are described by a WoT Thing Description, whereas a virtual entity is the composition of one or more Things.
In the domain oftd:baseURI
td:definesSecurityScheme
td:description
td:descriptionInLanguage
td:followsProfile
td:hasForm
td:hasInteractionAffordance
td:hasSecurityConfiguration
td:instance
td:model
td:title
td:titleInLanguage

4.2 Object Properties

4.2.1 definesSecurityScheme

IRI: https://www.w3.org/2019/wot/td#definesSecurityScheme

A Thing may define abstract security schemes, used to configure the secure access of (a set of) affordance(s).
Domain includestd:Thing
+

4.2.2 hasActionAffordance

IRI: https://www.w3.org/2019/wot/td#hasActionAffordance

All Action-based interaction affordance of the Thing.
Range includestd:ActionAffordance
+

4.2.3 hasCancellationSchema

IRI: https://www.w3.org/2019/wot/td#hasCancellationSchema

Defines any data that needs to be passed to cancel a subscription, e.g., a specific message to remove a Webhook
Domain includestd:EventAffordance
+

4.2.4 hasConfigurationInstance

IRI: https://www.w3.org/2019/wot/td#hasConfigurationInstance

Instantiation, as used here, is a form of non-symmetric equivalence between a scheme and a configuration: whatever statement on the scheme is also true of the configuration but not vice-versa.
Domain includeswotsec:SecurityScheme
+

4.2.5 hasEventAffordance

IRI: https://www.w3.org/2019/wot/td#hasEventAffordance

All Event-based interaction affordance of the Thing.
Range includestd:EventAffordance
+

4.2.6 hasForm

IRI: https://www.w3.org/2019/wot/td#hasForm

Set of form hypermedia controls that describe how an operation can be performed. Forms are serializations of Protocol Bindings. The array cannot be empty
Domain includestd:InteractionAffordance
td:Thing
Range includeshctl:Form
+

4.2.7 hasInputSchema

IRI: https://www.w3.org/2019/wot/td#hasInputSchema

Used to define the input data schema of the action.
Domain includestd:ActionAffordance
+

4.2.8 hasInteractionAffordance

IRI: https://www.w3.org/2019/wot/td#hasInteractionAffordance

Offers an affordance to interact with the Thing
Domain includestd:Thing
Range includestd:InteractionAffordance
+ +

4.2.10 hasNotificationResponseSchema

IRI: https://www.w3.org/2019/wot/td#hasNotificationResponseSchema

Defines the data schema of the Event response messages sent by the consumer in a response to a data message.
Domain includestd:EventAffordance
+

4.2.11 hasNotificationSchema

IRI: https://www.w3.org/2019/wot/td#hasNotificationSchema

Defines the data schema of the Event instance messages pushed by the Thing.
Domain includestd:EventAffordance
+

4.2.12 hasOutputSchema

IRI: https://www.w3.org/2019/wot/td#hasOutputSchema

Used to define the output data schema of the action.
Domain includestd:ActionAffordance
+

4.2.13 hasPropertyAffordance

IRI: https://www.w3.org/2019/wot/td#hasPropertyAffordance

All Property-based interaction affordance of the Thing.
Range includestd:PropertyAffordance
+

4.2.14 hasSecurityConfiguration

IRI: https://www.w3.org/2019/wot/td#hasSecurityConfiguration

A security configuration is a a security scheme applied to a (set of) affordance(s).
Domain includeshctl:Form
td:Thing
+

4.2.15 hasSubscriptionSchema

IRI: https://www.w3.org/2019/wot/td#hasSubscriptionSchema

Defines data that needs to be passed upon subscription, e.g., filters or message format for setting up Webhooks.
Domain includestd:EventAffordance
+

4.2.16 hasUriTemplateSchema

IRI: https://www.w3.org/2019/wot/td#hasUriTemplateSchema

Define URI template variables according to [RFC6570] as collection based on schema specifications. The individual variables DataSchema cannot be an ObjectSchema or an ArraySchema.
Domain includestd:InteractionAffordance

4.3 Datatype Properties

4.3.1 baseURI

IRI: https://www.w3.org/2019/wot/td#baseURI

Define the base URI that is used for all relative URI references throughout a TD document. In TD instances, all relative URIs are resolved relative to the base URI using the algorithm defined in [RFC3986]. base does not affect the URIs used in @context and the IRIs used within Linked Data [LINKED-DATA] graphs that are relevant when semantic processing is applied to TD instances.
Domain includestd:Thing
Range includesschema:URL
+

4.3.2 description

IRI: https://www.w3.org/2019/wot/td#description

description of the TD element (Thing, interaction affordance, security scheme or data schema)
Domain includesjsonschema:DataSchema
wotsec:SecurityScheme
td:InteractionAffordance
td:Thing
Range includesschema:Text
+

4.3.3 descriptionInLanguage

IRI: https://www.w3.org/2019/wot/td#descriptionInLanguage

description of the TD element (Thing, interaction affordance, security scheme or data schema) with language tag. By convention, a language tag must be added to the object of 'descriptionInLanguage' triples. Otherwise, use 'description'.
Domain includesjsonschema:DataSchema
wotsec:SecurityScheme
td:InteractionAffordance
td:Thing
Range includesschema:Text
+

4.3.4 followsProfile

IRI: https://www.w3.org/2019/wot/td#followsProfile

Indicates the WoT Profile mechanisms followed by this Thing Description and the corresponding Thing implementation.
Domain includestd:Thing
Range includes
+

4.3.5 instance

IRI: https://www.w3.org/2019/wot/td#instance

Provides a version identicator of this TD instance.
Domain includestd:Thing
+

4.3.6 isIdempotent

IRI: https://www.w3.org/2019/wot/td#isIdempotent

Indicates whether the action is idempotent (=true) or not. Informs whether the action can be called repeatedly with the same result, if present, based on the same input.
Domain includestd:ActionAffordance
Range includesschema:Boolean
+

4.3.7 isObservable

IRI: https://www.w3.org/2019/wot/td#isObservable

A hint that indicates whether Servients hosting the Thing and Intermediaries should provide a Protocol Binding that supports the observeproperty and unobserveproperty operations for this Property.
Domain includestd:PropertyAffordance
Range includesschema:Boolean
+

4.3.8 isSafe

IRI: https://www.w3.org/2019/wot/td#isSafe

Signals if the action is safe (=true) or not. Used to signal if there is no internal state (cf. resource state) is changed when invoking an Action. In that case responses can be cached as example.
Domain includestd:ActionAffordance
Range includesschema:Boolean
+

4.3.9 isSynchronous

IRI: https://www.w3.org/2019/wot/td#isSynchronous

Indicates whether the action is synchronous (=true) or not. A synchronous action means that the response of action contains all the information about the result of the action and no further querying about the status of the action is needed. Lack of this keyword means that no claim on the synchronicity of the action can be made.
Domain includestd:ActionAffordance
Range includesschema:Boolean
+

4.3.10 model

IRI: https://www.w3.org/2019/wot/td#model

Provides a version indicator of the underlying TM.
Domain includestd:Thing
+

4.3.11 name

IRI: https://www.w3.org/2019/wot/td#name

Indexing property to store entity names when serializing them in a JSON-LD @index container.
Domain includestd:InteractionAffordance
Range includesschema:Text
+

4.3.12 title

IRI: https://www.w3.org/2019/wot/td#title

title of the TD element (Thing, interaction affordance or data schema)
Domain includesjsonschema:DataSchema
td:InteractionAffordance
td:Thing
Range includesschema:Text
+

4.3.13 titleInLanguage

IRI: https://www.w3.org/2019/wot/td#titleInLanguage

title of the TD element (Thing, interaction affordance or data schema) with language tag. By convention, a language tag must be added to the object of 'titleInLanguage' triples. Otherwise, use 'title'.
Domain includesjsonschema:DataSchema
td:InteractionAffordance
td:Thing
Range includesschema:Text

4.4 Annotation Properties

4.4.1 supportContact

IRI: https://www.w3.org/2019/wot/td#supportContact

Provides information about the TD maintainer as URI scheme (e.g., mailto [RFC6068], tel [RFC3966], https[RFC9112]).
+

4.4.2 versionInfo

IRI: https://www.w3.org/2019/wot/td#versionInfo

Provides version information.

4.5 Named Individuals

4.5.1 cancelAction

IRI: https://www.w3.org/2019/wot/td#cancelAction

Operation type of forms used to cancel an action
Instance oftd:OperationType
+

4.5.2 invokeAction

IRI: https://www.w3.org/2019/wot/td#invokeAction

Operation type of forms used to read a property value
Instance oftd:OperationType
+

4.5.3 observeAllProperties

IRI: https://www.w3.org/2019/wot/td#observeAllProperties

Operation type of forms used to observe all property values
Instance oftd:OperationType
+

4.5.4 observeProperty

IRI: https://www.w3.org/2019/wot/td#observeProperty

Operation type of forms used to observe a property value
Instance oftd:OperationType
+

4.5.5 queryAction

IRI: https://www.w3.org/2019/wot/td#queryAction

Operation type of forms used to query the status of an action
Instance oftd:OperationType
+

4.5.6 queryAllActions

IRI: https://www.w3.org/2019/wot/td#queryAllActions

Operation type of forms used to query the status of all actions
Instance oftd:OperationType
+

4.5.7 readAllProperties

IRI: https://www.w3.org/2019/wot/td#readAllProperties

Operation type of forms used to read all property values
Instance oftd:OperationType
+

4.5.8 readMultipleProperties

IRI: https://www.w3.org/2019/wot/td#readMultipleProperties

Operation type of forms used to read a property value
Instance oftd:OperationType
+

4.5.9 readProperty

IRI: https://www.w3.org/2019/wot/td#readProperty

Operation type of forms used to read a property value
Instance oftd:OperationType
+

4.5.10 subscribeAllEvents

IRI: https://www.w3.org/2019/wot/td#subscribeAllEvents

Operation type of forms used to subscribe to all event types
Instance oftd:OperationType
+

4.5.11 subscribeEvent

IRI: https://www.w3.org/2019/wot/td#subscribeEvent

Operation type of forms used to read a property value
Instance oftd:OperationType
+

4.5.12 unobserveAllProperties

IRI: https://www.w3.org/2019/wot/td#unobserveAllProperties

Operation type of forms used to unobserve all property value
Instance oftd:OperationType
+

4.5.13 unobserveProperty

IRI: https://www.w3.org/2019/wot/td#unobserveProperty

Operation type of forms used to unobserve a property value
Instance oftd:OperationType
+

4.5.14 unsubscribeAllEvents

IRI: https://www.w3.org/2019/wot/td#unsubscribeAllEvents

Operation type of forms used to unsubscribe from all event types
Instance oftd:OperationType
+

4.5.15 unsubscribeEvent

IRI: https://www.w3.org/2019/wot/td#unsubscribeEvent

Operation type of forms used to read a property value
Instance oftd:OperationType
+

4.5.16 writeAllProperties

IRI: https://www.w3.org/2019/wot/td#writeAllProperties

Operation type of forms used to read a property value
Instance oftd:OperationType
+

4.5.17 writeMultipleProperties

IRI: https://www.w3.org/2019/wot/td#writeMultipleProperties

Operation type of forms used to write a property value
Instance oftd:OperationType
+

4.5.18 writeProperty

IRI: https://www.w3.org/2019/wot/td#writeProperty

Operation type of forms used to write a property value
Instance oftd:OperationType
+ +

5. Alignments

+ + +

+ The TD ontology shares commonalities with other WoT-related vocabularies, in particular + with SOSA [vocab-ssn] and schema.org. + Alignments between these vocabularies are provided in a human-readable way in the following. +

+ +

5.1 SOSA

+ + +

+ All alignments with SOSA are also available here in OWL: + td-sosa.ttl. +

+ +

+ Alignment of td:Thing with SOSA: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Sub-ClassSuper-Class
+ td:Thing + + sosa:Sensor or
+ sosa:Actuator or
+ sosa:Platform or
+ sosa:FeatureOfInterest +
+ td:Thing and
+ sosa:FeatureOfInterest + 		+ ssn:hasProperty some (
+ (sosa:isObservedBy some sosa:Sensor) or
+ (sosa:isActedOnBy some sosa:Actuator)
+ ) +
+ td:Thing and
+ sosa:Sensor + 		+ sosa:observes some
+ sosa:ObservableProperty +
+ td:Thing and
+ sosa:Actuator + 		+ sosa:actsOnProperty some
+ sosa:ActuatableProperty +
+ td:Thing and
+ sosa:Platform + 		+ sosa:hosts some (
+ (
+ sosa:Sensor and
+ sosa:observes some
+ sosa:ObservableProperty
+ ) or (
+ sosa:Actuator and
+ sosa:actsOnProperty some
+ sosa:ActuatableProperty
+ )
+ ) +
+ +

Alignment of td:InteractionAffordance with SOSA:

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Sub-ClassSuper-Class
+ td:PropertyAffordance and
+ td:hasForm some
+ hctl:hasOperationType value
+ td:readProperty + 		+ ssn:forProperty some sosa:ObservableProperty +
+ td:PropertyAffordance and
+ td:hasForm some
+ hctl:hasOperationType value
+ td:writeProperty + 		+ ssn:forProperty some sosa:ActuatableProperty +
+ td:ActionAffordance + + ssn:forProperty some
+ sosa:ActuatableProperty +
+ td:EventAffordance + + ssn:forProperty some
+ sosa:ObservableProperty +
+
+ +

5.2 Schema.org

+ + +

+ The alignments with schema.org's actions are also available here in OWL: + td-sdo.ttl. +

+ + + + + + + + + + + + + + +
Sub-ClassSuper-Class
+ td:InteractionAffordance + + schema:Action and
+ schema:actionStatus value + schema:PotentialActionStatus
+
+ + + + + + + + + + + + + + +
Sub-PropertySuper-Property
+ td:hasInteractionAffordance + + schema:potentialAction +
+
+
+ +

6. Usage Examples

+ + +

6.1 Thing Description JSON-LD 1.1 Instance to RDF Dataset

+ + +

+ The following example shows a TD instance from Example 1 Thing Description + specification [WOT-THING-DESCRIPTION] in JSON-LD 1.1 (JSON-LD 1.1 tab) and in a RDF dataset (RDF tab). +

+ + + + + +

+ The RDF dataset contains the corresponding Thing Description IRIs as defined in this document. This IRI mapping is provided by the Thing Description + context file https://www.w3.org/2019/wot/td/v1. For instance, the field actions is transformed to <https://www.w3.org/2019/wot/td#hasActionAffordance>. + +

+ + +
+ +

6.2 Merging Thing Descriptions

+ + +

+ The following example includes two TD documents in the standard TD JSON + representation format [WOT-THING-DESCRIPTION], identified by a unique + electronic product code [RFC5134]. +

+ +

+ If these two documents are being merged together with contextual information + in the form of an RDF graph that uses the same identifiers, it is possible + to retrieve form metadata of these TDs depending on the relations that + exist between Things. Here, the two Things share information on room 101 + of some example building. +

+ + +
+ +

6.3 Internal State of a Thing

+ + +

+ It is possible for affordances of different kinds to have the same effect. + For instance, an affordance to a writable property may be equivalent to + an affordance to invoke an action that changes the property value. + Similarly, for every observable property, there may be an equivalent + affordance to subscribe to an event that occurs at every property value change. +

+ +

+ WoT clients can avoid having to deal with these discrepancies by + using the generic td:hasInteractionAffordance predicate. + They can then decide to perform an action based solely on the operation type + of the form embedded in the affordance object. +

+ + +
+ +

6.4 Specifying Affordances by Device Classes

+ + +

+ It is possible to use the TD ontology to extend the definition of + well-known subclasses of Thing by defining expected + affordances that Things of such types should present. The + following example specifies that every temperature sensor presents + an affordance to a temperature property (expressed in the SAREF + vocabulary [smartM2M]). +

+ + +
+
+ + + + +

A. References

A.1 Normative references

+ +
[RFC3966]
+ The tel URI for Telephone Numbers. H. Schulzrinne. IETF. December 2004. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3966 +
[RFC5134]
+ A Uniform Resource Name Namespace for the EPCglobal Electronic Product Code (EPC) and Related Standards. M. Mealling. IETF. January 2008. Informational. URL: https://www.rfc-editor.org/rfc/rfc5134 +
[RFC6068]
+ The 'mailto' URI Scheme. M. Duerst; L. Masinter; J. Zawinski. IETF. October 2010. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6068 +
[RFC6570]
+ URI Template. J. Gregorio; R. Fielding; M. Hadley; M. Nottingham; D. Orchard. IETF. March 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6570 +
[RFC9112]
+ HTTP/1.1. R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.. IETF. June 2022. Internet Standard. URL: https://httpwg.org/specs/rfc9112.html +
[shacl]
+ Shapes Constraint Language (SHACL). Holger Knublauch; Dimitris Kontokostas. W3C. 20 July 2017. W3C Recommendation. URL: https://www.w3.org/TR/shacl/ +
[smartM2M]
+ ETSI TS 103 264 V2.1.1 (2017-03): SmartM2M; Smart Appliances; Reference Ontology and oneM2M Mapping. ETSI. March 2017. Published. URL: http://www.etsi.org/deliver/etsi_ts/103200_103299/103264/02.01.01_60/ts_103264v020101p.pdf +
[vocab-ssn]
+ Semantic Sensor Network Ontology. Armin Haller; Krzysztof Janowicz; Simon Cox; Danh Le Phuoc; Kerry Taylor; Maxime Lefrançois. W3C. 19 October 2017. W3C Recommendation. URL: https://www.w3.org/TR/vocab-ssn/ +
[WOT-ARCHITECTURE]
+ Web of Things (WoT) Architecture. Matthias Kovatsch; Ryuichi Matsukura; Michael Lagally; Toru Kawaguchi; Kunihiko Toumura; Kazuo Kajimoto. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-architecture/ +
[WOT-THING-DESCRIPTION]
+ Web of Things (WoT) Thing Description. Sebastian Käbisch; Takuki Kamiya; Michael McCool; Victor Charpenay; Matthias Kovatsch. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-thing-description/ +
+
\ No newline at end of file diff --git a/publication/ver11/7-resources/ontology/staticFiles/wotsec.html b/publication/ver11/7-resources/ontology/staticFiles/wotsec.html new file mode 100644 index 000000000..85f720613 --- /dev/null +++ b/publication/ver11/7-resources/ontology/staticFiles/wotsec.html @@ -0,0 +1,811 @@ + + + + + + + + +Web of Things (WoT) Security Ontology + + + + + + + + + + +
+

+

Web of Things (WoT) Security Ontology

+

W3C Editor's Draft

+
+ More details about this document +
+
This version:
+ https://www.w3.org/2019/wot/security +
+
Latest published version:
+ none +
+
Latest editor's draft:
https://www.w3.org/2019/wot/security
+ + + + + + +
Editors:
+ Victor Charpenay +
+ Michael McCool +
+ + + + +
Ontology in RDF
+ Web of Things (WoT) Security Ontology in RDF +
+
+
+ + +

+ Copyright + © + 2023 + + World Wide Web Consortium. + W3C® + liability, + trademark and + permissive document license rules apply. +

+
+
+

Abstract

+

+ This document introduces an RDF vocabulary for the security metadata definitions. + This vocabulary provides a stable namespace IRI for security keywords, as well as simple axioms, defined against schema.org's meta-model. + Examples on how to use the vocabulary are also introduced. +

+
+

Status of This Document

This section describes the status of this + document at the time of its publication. A list of current W3C + publications and the latest revision of this technical report can be found + in the W3C technical reports index at + https://www.w3.org/TR/.

+

+ This document was published by the Web of Things Working Group as + an Editor's Draft. +

Publication as an Editor's Draft does not + imply endorsement by W3C and its Members.

+ This is a draft document and may be updated, replaced or obsoleted by other + documents at any time. It is inappropriate to cite this document as other + than work in progress. + +

+ + This document was produced by a group + operating under the + W3C Patent + Policy. + + + W3C maintains a + public list of any patent disclosures + made in connection with the deliverables of + the group; that page also includes + instructions for disclosing a patent. An individual who has actual + knowledge of a patent which the individual believes contains + Essential Claim(s) + must disclose the information in accordance with + section 6 of the W3C Patent Policy. + +

+ This document is governed by the + 03 November 2023 W3C Process Document. +

+

1. Introduction

+ +

+ This documents provides an ontology of 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]). + However while the HTTP security schemes, Vocabulary, and syntax given in this specification share many similarities with OpenAPI, they are not compatible. +

+
+ +

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

+ The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT in this document + are to be interpreted as described in + BCP 14 + [RFC2119] [RFC8174] + when, and only when, they appear in all capitals, as shown here. +

+ +

3. Terminology

+ + +

The fundamental WoT terminology such as + Thing, + Consumer, + Thing Description (TD), + Interaction Model, + Interaction Affordance, + Property, + Action, + Event, + Protocol Binding, + Servient, + etc. is defined in Section 3 + of the WoT Architecture specification [WOT-ARCHITECTURE]. +

+ +

+ The Thing Description terminology such as + TD Information Model, + TD Document, + Term (Vocabulary Term), TD Context Extension + etc. is defined in Section 3 + of the WoT Thing Description specification [WOT-THING-DESCRIPTION]. +

+ +
+ + +

4. Axiomatization

4.1 Classes

4.1.1 APIKeySecurityScheme

IRI: https://www.w3.org/2019/wot/security#APIKeySecurityScheme

API key authentication security configuration identified by the term apikey (i.e., "scheme": "apikey"). This scheme is to be used when the access token is opaque, for example when a key in a 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 of service requests using the mechanism indicated by the "in" field.
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:in
wotsec:name
+

4.1.2 AutoSecurityScheme

IRI: https://www.w3.org/2019/wot/security#AutoSecurityScheme

An automatic authentication security configuration identified by the term auto (i.e., "scheme": "auto"). This scheme indicates that the security parameters are going to be negotiated by the underlying protocols at runtime, subject to the respective specifications for the protocol (e.g. [RFC8288] for Basic Authentication when using HTTP).
Sub-class ofwotsec:SecurityScheme
+

4.1.3 BasicSecurityScheme

IRI: https://www.w3.org/2019/wot/security#BasicSecurityScheme

Basic authentication security configuration identified by the term basic (i.e., "scheme": "basic"), using an unencrypted username and password.
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:in
wotsec:name
+

4.1.4 BearerSecurityScheme

IRI: https://www.w3.org/2019/wot/security#BearerSecurityScheme

Bearer token authentication security configuration identified by the term bearer (i.e., "scheme": "bearer"). This scheme is intended for situations where bearer tokens are used independently of OAuth2. If the oauth2 scheme is specified it is not generally necessary to specify this scheme as well as it is implied. For format, the value jwt indicates conformance with RFC7519, jws indicates conformance with RFC7797, cwt indicates conformance with RFC8392, and jwe indicates conformance with !RFC7516, with values for alg interpreted consistently with those standards. Other formats and algorithms for bearer tokens MAY be specified in vocabulary extensions.
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:alg
wotsec:authorization
wotsec:format
wotsec:in
wotsec:name
+

4.1.5 ComboSecurityScheme

IRI: https://www.w3.org/2019/wot/security#ComboSecurityScheme

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.

Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:allOf
wotsec:oneOf
+

4.1.6 DigestSecurityScheme

IRI: https://www.w3.org/2019/wot/security#DigestSecurityScheme

Digest authentication security configuration identified by the term digest (i.e., "scheme": "digest"). This scheme is similar to basic authentication but with added features to avoid man-in-the-middle attacks.
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:in
wotsec:name
wotsec:qop
+

4.1.7 NoSecurityScheme

IRI: https://www.w3.org/2019/wot/security#NoSecurityScheme

A security configuration corresponding to identified by the term nosec (i.e., "scheme": "nosec"), indicating there is no authentication or other mechanism required to access the resource.
Sub-class ofwotsec:SecurityScheme
+

4.1.8 OAuth2SecurityScheme

IRI: https://www.w3.org/2019/wot/security#OAuth2SecurityScheme

OAuth 2.0 authentication security configuration for systems conformant with [RFC6749] and [RFC8252], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). For the code flow both authorization and token MUST be included. For the client flow token MUST be included. For the client flow authorization MUST NOT be included. The mandatory elements for each flow are summarized in the following table:

Elementcodeclient
authorizationmandatoryomit
tokenmandatorymandatory
refreshoptionaloptional

Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:authorization
wotsec:flow
wotsec:refresh
wotsec:scopes
wotsec:token
+

4.1.9 PSKSecurityScheme

IRI: https://www.w3.org/2019/wot/security#PSKSecurityScheme

Pre-shared key authentication security configuration identified by the 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], and that the ciphersuite used for keys will be established during protocol negotiation.
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:identity
+

4.1.10 SecurityScheme

IRI: https://www.w3.org/2019/wot/security#SecurityScheme

Metadata describing the configuration of a security mechanism. The value assigned to the name scheme MUST be defined within a Vocabulary included in the Thing Description, either in the standard Vocabulary defined in § 5. TD Information Model or in a TD Context Extension.

For all security schemes, any keys, passwords, or other sensitive information directly providing access MUST NOT be stored in the TD and should instead be shared and stored out-of-band via other mechanisms. 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.

Each security scheme object used in a TD defines a set of requirements to be met before access can be granted. We say a security scheme is satisfied when all its requirements are met. In some cases requirements from multiple security schemes will have to be met before access can be granted.

Security schemes generally may require additional authentication parameters, such as a password or key. The location of this information is indicated by the value associated with the name in, often in combination with the value associated with name. The in name can take one of the following values:

header:
The parameter will be given 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 query parameter provided by name.
body:
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. 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. Since this value is not a fragment identifier, it also does not need to URL-encode special characters. The targeted element may or may not already exist at the specified location in the referenced data schema. If it does not, it will be inserted. This avoids having to duplicate definitions in the data schemas of every interaction. 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 be possible to insert the indicated element at the location indicated by the pointer.. For example, pointing to a key of a Map where that key does not exist in the corresponding Data Schema, the key and its value, which is the credential, would be inserted to the Map at the specified location during the operation execution. On the other hand, pointing to an Array's item with a number as the item index, that number should be outside the range of the Array's already specified items in order to not alter the strict sequence of items. The JSON pointer 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 body security information location 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 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 for in in a security scheme only if query is not applicable. The URIs provided in interactions where a security scheme using uri MUST be a URI template including the defined variable.
auto:
The location is determined as part of the protocol, or negotiated. If a value of auto is set for the in field of a SecurityScheme, then the name field SHOULD NOT be set. In this case, the application of the SecurityScheme is subject to the respective specification for the given protocol (e.g. [RFC8288] when using the BasicSecurityScheme with HTTP).
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 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 declared in the TD.

Super-class ofwotsec:APIKeySecurityScheme
wotsec:AutoSecurityScheme
wotsec:BasicSecurityScheme
wotsec:BearerSecurityScheme
wotsec:ComboSecurityScheme
wotsec:DigestSecurityScheme
wotsec:NoSecurityScheme
wotsec:OAuth2SecurityScheme
wotsec:PSKSecurityScheme
In the domain ofwotsec:proxy
td:description
td:descriptionInLanguage
td:hasConfigurationInstance

4.2 Object Properties

4.2.1 allOf

IRI: https://www.w3.org/2019/wot/security#allOf

Array of two or more strings identifying other named security scheme definitions, all of which must be satisfied for access.
Domain includeswotsec:ComboSecurityScheme
+

4.2.2 authorization

IRI: https://www.w3.org/2019/wot/security#authorization

URI of the authorization server.
Domain includeswotsec:BearerSecurityScheme
wotsec:OAuth2SecurityScheme
+

4.2.3 oneOf

IRI: https://www.w3.org/2019/wot/security#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.
Domain includeswotsec:ComboSecurityScheme
+

4.2.4 refresh

IRI: https://www.w3.org/2019/wot/security#refresh

URI of the refresh server.
Domain includeswotsec:OAuth2SecurityScheme
+

4.2.5 token

IRI: https://www.w3.org/2019/wot/security#token

URI of the token server.
Domain includeswotsec:OAuth2SecurityScheme

4.3 Datatype Properties

4.3.1 alg

IRI: https://www.w3.org/2019/wot/security#alg

Encoding, encryption, or digest algorithm.
Domain includeswotsec:BearerSecurityScheme
+

4.3.2 in

IRI: https://www.w3.org/2019/wot/security#apikeyIn

Specifies the location of security authentication information.
Domain includeswotsec:APIKeySecurityScheme
+

4.3.3 flow

IRI: https://www.w3.org/2019/wot/security#flow

Authorization flow.
Domain includeswotsec:OAuth2SecurityScheme
+

4.3.4 format

IRI: https://www.w3.org/2019/wot/security#format

Specifies format of security authentication information.
Domain includeswotsec:BearerSecurityScheme
+

4.3.5 identity

IRI: https://www.w3.org/2019/wot/security#identity

Identifier providing information which can be used for selection or confirmation.
Domain includeswotsec:PSKSecurityScheme
+

4.3.6 in

IRI: https://www.w3.org/2019/wot/security#in

Specifies the location of security authentication information.
Domain includeswotsec:BasicSecurityScheme
wotsec:BearerSecurityScheme
wotsec:DigestSecurityScheme
+

4.3.7 name

IRI: https://www.w3.org/2019/wot/security#name

Name for query, header, cookie, or uri parameters.
Domain includeswotsec:APIKeySecurityScheme
wotsec:BasicSecurityScheme
wotsec:BearerSecurityScheme
wotsec:DigestSecurityScheme
+

4.3.8 proxy

IRI: https://www.w3.org/2019/wot/security#proxy

URI of the proxy server this security configuration provides access to. If not given, the corresponding security configuration is for the endpoint.
This feature is at risk.
Domain includeswotsec:SecurityScheme
Range includes
+

4.3.9 qop

IRI: https://www.w3.org/2019/wot/security#qop

Quality of protection.
This feature is at risk.
Domain includeswotsec:DigestSecurityScheme
+

4.3.10 scopes

IRI: https://www.w3.org/2019/wot/security#scopes

Set of authorization scope identifiers provided as an array. These are provided in tokens returned by an authorization server and associated with forms in order to identify what resources a client may access and how. The values associated with a form should be chosen from those defined in an OAuth2SecurityScheme active on that form.
This feature is at risk.
Domain includeswotsec:OAuth2SecurityScheme

4.4 Annotation Properties

No AnnotationProperty found in the ontology.

+ +

5. Usage Examples

+ + +

5.1 Extended Configuration

+ + + +
+
+ + + + + +

A. References

A.1 Normative references

+ +
[RFC2119]
+ Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119 +
[rfc4279]
+ Pre-Shared Key Ciphersuites for Transport Layer Security (TLS). P. Eronen, Ed.; H. Tschofenig, Ed.. IETF. December 2005. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc4279 +
[RFC6749]
+ The OAuth 2.0 Authorization Framework. D. Hardt, Ed.. IETF. October 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6749 +
[RFC6901]
+ JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901 +
[RFC8174]
+ Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174 +
[RFC8252]
+ OAuth 2.0 for Native Apps. W. Denniss; J. Bradley. IETF. October 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8252 +
[RFC8288]
+ Web Linking. M. Nottingham. IETF. October 2017. Proposed Standard. URL: https://httpwg.org/specs/rfc8288.html +
[WOT-ARCHITECTURE]
+ Web of Things (WoT) Architecture. Matthias Kovatsch; Ryuichi Matsukura; Michael Lagally; Toru Kawaguchi; Kunihiko Toumura; Kazuo Kajimoto. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-architecture/ +
[WOT-THING-DESCRIPTION]
+ Web of Things (WoT) Thing Description. Sebastian Käbisch; Takuki Kamiya; Michael McCool; Victor Charpenay; Matthias Kovatsch. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-thing-description/ +
+

A.2 Informative references

+ +
[OPENAPI]
+ OpenAPI Specification. Darrell Miller; Jeremy Whitlock; Marsh Gardiner; Mike Ralphson; Ron Ratovsky; Uri Sarid; Tony Tam; Jason Harmon. OpenAPI Initiative. URL: https://www.openapis.org/ +
+
\ No newline at end of file From 395a454993c9f6f7b494597d37e297682442ae6d Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Tue, 9 Jan 2024 15:05:49 +0100 Subject: [PATCH 09/43] Delete PLANNING.md --- PLANNING.md | 24 ------------------------ 1 file changed, 24 deletions(-) delete mode 100644 PLANNING.md diff --git a/PLANNING.md b/PLANNING.md deleted file mode 100644 index 01b681b69..000000000 --- a/PLANNING.md +++ /dev/null @@ -1,24 +0,0 @@ -# TD.next Planning - -- [Presentation from Michael Koster](https://github.com/w3c/wot/blob/main/PRESENTATIONS/2023-31-05-tdnext.pdf) -- Charter Draft: [Working Document](https://github.com/w3c/wot-charter-drafts/blob/main/wot-wg-2023-draft.html) | [Rendered Document](https://w3c.github.io/wot-charter-drafts/wot-wg-2023-draft.html) -- Detailed Work Items: [Working Document](https://github.com/w3c/wot-charter-drafts/blob/main/wot-wg-2023-details.html) | [Rendered Document](https://w3c.github.io/wot-charter-drafts/wot-wg-2023-details.html) -- TD Work Items in the main WoT repository: https://github.com/w3c/wot/blob/main/planning/ThingDescription/work-items.md -- Pull Requests at https://github.com/w3c/wot-charter-drafts -- Possibly Discussion in Issues in this repository - -## Summary - -### Technical - -### Organizational - -## TD.next presentation - -To be extended - -## Backlog - -- Validation of TDs should be better, including extensions (protocols, security extensions) -- A validation process for external bindings is needed -- Governance of specific binding submissions, how to review, special meetings or not etc. From 211658b72e84e4305373c4d7a7c5e686c19d9539 Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Tue, 9 Jan 2024 15:57:53 +0100 Subject: [PATCH 10/43] add initial version --- VERSIONING.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 VERSIONING.md diff --git a/VERSIONING.md b/VERSIONING.md new file mode 100644 index 000000000..fb64d5e8a --- /dev/null +++ b/VERSIONING.md @@ -0,0 +1,33 @@ +# Versioning of TD Specification Resources + +In addition to the specifications, there are other resources that are managed in this repository. +This file documents the discussion on how the versioning should be. +Once there is an agreement, the rules will be moved to [wot-resources](https://github.com/w3c/wot-resources) repository. +The points below present a summary, but you can scroll to the bottom of the page to find the original input from the meetings. + +- With each REC, we publish the following files: + - Ontology files in form of TTL and HTML. These are TD, Security, hypermedia controls, JSON Schema, and soon the TM + - JSON-LD Context file + - JSON Schemas for TD and TM +- We do not publish different versions of these files until we see the need (e.g. a bug that also has breaking changes to current implementations). +- + +## Original Input + +Text copied from + +- What do we mean by versioning? + - Pointing to the most recent version but also older versions should be available + - Semver with Major, Minor, Patch at semver.org + - For TD.next, do we want to publish resources with each publication (WD, CR, PR etc) or not? +- Which changes are bugfixes, new features (TD 2.0 keywords) + - JSON Schemas + - Patch: English typos etc. Minor: Relaxing a constraint (longer strings, more oneof) so that more TDs can pass the schema. Major: Adding or restricting constraints + - JSON-LD Context + - Ontology files + - TTL + - HTML +- How much time to invest in maintaining 1.1 resources? +– Maintaining multiple files or not: xxx.v1.1.0.ttl xxx.v1.1.1.ttl +- Decision so far: Do not dig into 1.1 versioning until we have the need. +- TM resources (tm.ttl and tm.html) will not be versioned for the first changes since HTML doesn't exist and TTL is not usable. From 2fb8e85c14273e99ce6d30c2ab12956974de1ffd Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Tue, 9 Jan 2024 16:38:05 +0100 Subject: [PATCH 11/43] Update VERSIONING.md --- VERSIONING.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/VERSIONING.md b/VERSIONING.md index fb64d5e8a..c2b02c202 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -10,7 +10,14 @@ The points below present a summary, but you can scroll to the bottom of the page - JSON-LD Context file - JSON Schemas for TD and TM - We do not publish different versions of these files until we see the need (e.g. a bug that also has breaking changes to current implementations). -- +- Initial thoughts on versioning + - When a user wants to get a resource and does not specify the version, they get the latest version. + - We prefer semantic versioning with following rules (also see https://github.com/json-schema-org/website/issues/197#issuecomment-1883270213): + - Patch: English typos etc. + - Minor: Relaxing a constraint (longer strings, more oneof) so that more TDs can pass the schema. + - Major: Adding or restricting constraints + - ( @egekorkan ) The versioning rules do not apply to different versions of a specification, e.g. TD 1.1 schema should be treated like a new release, not a next iteration of the 1.0 schema + - We do not version anything until a REC release ## Original Input From 1a27e01c92b73f66d683e5c2a21316b3c325612b Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Wed, 10 Jan 2024 16:30:56 +0100 Subject: [PATCH 12/43] Update VERSIONING.md --- VERSIONING.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/VERSIONING.md b/VERSIONING.md index c2b02c202..7ece3503c 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -12,13 +12,18 @@ The points below present a summary, but you can scroll to the bottom of the page - We do not publish different versions of these files until we see the need (e.g. a bug that also has breaking changes to current implementations). - Initial thoughts on versioning - When a user wants to get a resource and does not specify the version, they get the latest version. - - We prefer semantic versioning with following rules (also see https://github.com/json-schema-org/website/issues/197#issuecomment-1883270213): + - We prefer semantic versioning with the following rules (also see https://github.com/json-schema-org/website/issues/197#issuecomment-1883270213): - Patch: English typos etc. - Minor: Relaxing a constraint (longer strings, more oneof) so that more TDs can pass the schema. - Major: Adding or restricting constraints - ( @egekorkan ) The versioning rules do not apply to different versions of a specification, e.g. TD 1.1 schema should be treated like a new release, not a next iteration of the 1.0 schema - - We do not version anything until a REC release - + - Do we version anything until a REC release + - ( @relu91 ) An unofficial version increment for WG members (not for outside): E.g. an alpha prefix and then a number. Beta etc. can be used when going into CR. Or we just tag/prefix/suffix with CR, PR or nightly + - ( @lu-zero ) A date afterward would be good "enough" for implementers. A release every month (in addition to semver) would be also good. We can also pipeline it and tag each resource exposed to github.io. + - ( @mjkoster ) Short commit hash would be fine. Monthly release may not make sense (unless there is a need) + - We need a policy (when to change a version for example. + - We need to be careful since each artifact has its own version, which will complicate CD pipeline. + ## Original Input Text copied from From 5c682dea6de035bd1c599b6030ca425b1b453013 Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Wed, 10 Jan 2024 17:17:07 +0100 Subject: [PATCH 13/43] fix indentation --- VERSIONING.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/VERSIONING.md b/VERSIONING.md index 7ece3503c..4c7aacf4f 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -6,13 +6,13 @@ Once there is an agreement, the rules will be moved to [wot-resources](https://g The points below present a summary, but you can scroll to the bottom of the page to find the original input from the meetings. - With each REC, we publish the following files: - - Ontology files in form of TTL and HTML. These are TD, Security, hypermedia controls, JSON Schema, and soon the TM - - JSON-LD Context file - - JSON Schemas for TD and TM -- We do not publish different versions of these files until we see the need (e.g. a bug that also has breaking changes to current implementations). -- Initial thoughts on versioning + - Ontology files in form of TTL and HTML. These are TD, Security, hypermedia controls, JSON Schema, and soon the TM + - JSON-LD Context file + - JSON Schemas for TD and TM +- We do not publish different versions of these files until we see the need (e.g. a bug that also has breaking changes to current implementations). +- Initial thoughts on versioning - When a user wants to get a resource and does not specify the version, they get the latest version. - - We prefer semantic versioning with the following rules (also see https://github.com/json-schema-org/website/issues/197#issuecomment-1883270213): + - We prefer semantic versioning with the following rules (also see ): - Patch: English typos etc. - Minor: Relaxing a constraint (longer strings, more oneof) so that more TDs can pass the schema. - Major: Adding or restricting constraints @@ -23,7 +23,7 @@ The points below present a summary, but you can scroll to the bottom of the page - ( @mjkoster ) Short commit hash would be fine. Monthly release may not make sense (unless there is a need) - We need a policy (when to change a version for example. - We need to be careful since each artifact has its own version, which will complicate CD pipeline. - + ## Original Input Text copied from From 53cde18ee7bc6b85d05f74670e339827d037576d Mon Sep 17 00:00:00 2001 From: Mahda Noura Date: Tue, 12 Dec 2023 14:23:54 +0100 Subject: [PATCH 14/43] templates modified to include a rule for the tm --- ontology/templates.sparql | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/ontology/templates.sparql b/ontology/templates.sparql index 93a871582..97829423e 100644 --- a/ontology/templates.sparql +++ b/ontology/templates.sparql @@ -11,7 +11,8 @@ template :main(?prefix) { if(?prefix = "td", st:call-template(:main-td, ?prefix), if(?prefix = "jsonschema", st:call-template(:main-jsonschema, ?prefix), if(?prefix = "wotsec", st:call-template(:main-wotsec, ?prefix), - if(?prefix = "hctl", st:call-template(:main-hctl, ?prefix), "")))) + if(?prefix = "tm", st:call-template(:main-tm, ?prefix), + if(?prefix = "hctl", st:call-template(:main-hctl, ?prefix), ""))))) } where {} template :main-td(?prefix) { @@ -35,6 +36,13 @@ template :main-wotsec(?prefix) { } } where {} +template :main-tm(?prefix) { + format { + + st:call-template(:axioms, ?prefix) + } +} where {} + template :main-hctl(?prefix) { format { From d160824c657ac2be472fab05894b8dbd18e4a80c Mon Sep 17 00:00:00 2001 From: Mahda Noura Date: Tue, 12 Dec 2023 14:24:26 +0100 Subject: [PATCH 15/43] first draft template for the TM ontology --- ontology/tm.template.html | 106 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 ontology/tm.template.html diff --git a/ontology/tm.template.html b/ontology/tm.template.html new file mode 100644 index 000000000..801811516 --- /dev/null +++ b/ontology/tm.template.html @@ -0,0 +1,106 @@ + + + + + + Thing Description (TD) Ontology + + + + + + +
+

+ The Thing Description (TD) ontology is an RDF axiomatization of the TD information model, + one of the building blocks of the Web of Things (WoT). Besides providing an alternative + to the standard JSON representation format for TD documents, the TD ontology can also + be used to process contextual information on Things and for alignments with other + WoT-related ontologies. +

+
+
+

+ Validation of the document by the Working Group is expected by the end of June 2019. +

+
+
+

Introduction

+ +

+ The TD ontology is an idiomatic RDF axiomatization of the TD information model [[WOT-THING-DESCRIPTION]], + which can be used to describe WoT things and their interaction affordances. The TD ontology imports + the hypermedia controls ontology. + However, although the TD information model also includes terms for data schemas and security + configurations, the TD ontology does not force the use of the corresponding + JSON schema and + WoT security vocabularies. Other schema languages + like SHACL [[shacl]] can thus be leveraged to describe WoT Things. +

+
+ +
+

Terminology

+ +

The fundamental WoT terminology such as + Thing, + Consumer, + Thing Description (TD), + Interaction Model, + Interaction Affordance, + Property, + Action, + Event, + Protocol Binding, + Servient, + etc. is defined in Section 3 + of the WoT Architecture specification [[WOT-ARCHITECTURE]]. +

+ +

+ The Thing Description terminology such as + TD Information Model, + TD Document, + Term (Vocabulary Term), + etc. is defined in Section 3 + of the WoT Thing Description specification [[WOT-THING-DESCRIPTION]]. + +

+ +
+ + + %s + + + + + \ No newline at end of file From efb17d6b4b0ee2bb0652e21b09b869bede8dab67 Mon Sep 17 00:00:00 2001 From: Mahda Noura Date: Tue, 12 Dec 2023 14:25:44 +0100 Subject: [PATCH 16/43] the tm documentation after the render script --- ontology/tm.html | 107 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) diff --git a/ontology/tm.html b/ontology/tm.html index e69de29bb..f9c1c56bb 100644 --- a/ontology/tm.html +++ b/ontology/tm.html @@ -0,0 +1,107 @@ + + + + + + Thing Description (TD) Ontology + + + + + + +
+

+ The Thing Description (TD) ontology is an RDF axiomatization of the TD information model, + one of the building blocks of the Web of Things (WoT). Besides providing an alternative + to the standard JSON representation format for TD documents, the TD ontology can also + be used to process contextual information on Things and for alignments with other + WoT-related ontologies. +

+
+
+

+ Validation of the document by the Working Group is expected by the end of June 2019. +

+
+
+

Introduction

+ +

+ The TD ontology is an idiomatic RDF axiomatization of the TD information model [[WOT-THING-DESCRIPTION]], + which can be used to describe WoT things and their interaction affordances. The TD ontology imports + the hypermedia controls ontology. + However, although the TD information model also includes terms for data schemas and security + configurations, the TD ontology does not force the use of the corresponding + JSON schema and + WoT security vocabularies. Other schema languages + like SHACL [[shacl]] can thus be leveraged to describe WoT Things. +

+
+ +
+

Terminology

+ +

The fundamental WoT terminology such as + Thing, + Consumer, + Thing Description (TD), + Interaction Model, + Interaction Affordance, + Property, + Action, + Event, + Protocol Binding, + Servient, + etc. is defined in Section 3 + of the WoT Architecture specification [[WOT-ARCHITECTURE]]. +

+ +

+ The Thing Description terminology such as + TD Information Model, + TD Document, + Term (Vocabulary Term), + etc. is defined in Section 3 + of the WoT Thing Description specification [[WOT-THING-DESCRIPTION]]. + +

+ +
+ + +

Axiomatization

Classes

ThingModel

IRI: https://www.w3.org/2019/wot/tm#ThingModel

A Thing Model is a description for a class of Things that have the same capabilities. It describes the Properties, Actions, and Events and common metadata that are shared for an entire group of Things. Compared to a Thing Description, a Thing Model does not contain enough information to identify or interact with a Thing instance.

Object Properties

No ObjectProperty found in the ontology.

Datatype Properties

No DatatypeProperty found in the ontology.

Annotation Properties

ref

IRI: https://www.w3.org/2019/wot/tm#ref

Provides a reference to an existing (external or local) definition that is copied into a newly defined definition. The reference value is based on three parts: an (optional) URI-reference (used for external reference), '#' sign, and JSON Pointer [RFC6901] value.
+

required

IRI: https://www.w3.org/2019/wot/tm#required

Constraint that provides references to declarations in the Thing Model that are mandatory and must be present when Thing Description instances are derived from this Thing Model. The reference value is a JSON Pointer [RFC6901].
+ + + + + \ No newline at end of file From 6309e82e56e623ac6d4072fc591c6b7c2a9b7739 Mon Sep 17 00:00:00 2001 From: Mahda Noura Date: Wed, 13 Dec 2023 10:35:17 +0100 Subject: [PATCH 17/43] isDefined were missing --- ontology/tm.ttl | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/ontology/tm.ttl b/ontology/tm.ttl index d942cf639..9dbe8c479 100644 --- a/ontology/tm.ttl +++ b/ontology/tm.ttl @@ -22,18 +22,19 @@ dcterms:author "Sebastian Kaebisch (Siemens)" ; dc:publisher [ a schema:Organization ; schema:name "W3C Web of Things Working Group" ; schema:url ] . + :ThingModel rdf:type rdfs:Class, owl:Class ; rdfs:label "ThingModel"@en ; rdfs:comment "A Thing Model is a description for a class of Things that have the same capabilities. It describes the Properties, Actions, and Events and common metadata that are shared for an entire group of Things. Compared to a Thing Description, a Thing Model does not contain enough information to identify or interact with a Thing instance."@en ; - rdfs:isDefinedBy : . + rdfs:isDefinedBy . :ref rdf:type owl:AnnotationProperty ; rdfs:label "ref" ; rdfs:comment "Provides a reference to an existing (external or local) definition that is copied into a newly defined definition. The reference value is based on three parts: an (optional) URI-reference (used for external reference), '#' sign, and JSON Pointer [RFC6901] value."@en ; rdfs:seeAlso schema:contactPoint ; - rdfs:isDefinedBy : . + rdfs:isDefinedBy . :required rdf:type owl:AnnotationProperty ; rdfs:label "required" ; rdfs:comment "Constraint that provides references to declarations in the Thing Model that are mandatory and must be present when Thing Description instances are derived from this Thing Model. The reference value is a JSON Pointer [RFC6901]."@en ; - rdfs:isDefinedBy : . \ No newline at end of file + rdfs:isDefinedBy . \ No newline at end of file From 3d66ca17f0dd22739c42eb9af96aa0a24eabafa3 Mon Sep 17 00:00:00 2001 From: Mahda Noura Date: Wed, 13 Dec 2023 10:35:52 +0100 Subject: [PATCH 18/43] removed the TD parts --- ontology/tm.template.html | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/ontology/tm.template.html b/ontology/tm.template.html index 801811516..0d1ae2b83 100644 --- a/ontology/tm.template.html +++ b/ontology/tm.template.html @@ -3,7 +3,7 @@ - Thing Description (TD) Ontology + Thing Model (TM) Ontology - - - - - - - - - - - - - - -
-

- This document describes a formal model and a common representation - for a Web of Things (WoT) Thing Description. - 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. - 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 - with a Thing Description. -

-
- -
-

- Implementers need to be aware that this specification is considered unstable. - Vendors interested in implementing this specification before it eventually - reaches the Candidate Recommendation phase should subscribe to the - repository - and take part in the discussions. -

- -

- Text and table entries highlighted with a yellow background - indicates a feature associated with an at-risk assertion for which - insufficient implementation experience exists. - When an entire section is at-risk the words - "This section is at risk." - will be placed at the start of the section and highlighted with a yellow background. -

- -
- -
-

Introduction

-

- The Thing Description (TD) model is a central building block in the W3C Web of - Things (WoT) and can be considered as the entry point of a Thing - (much like the index.html of a Web site). A TD instance has four main - components: textual metadata about the Thing itself, a collection of affordances - to interact with the Thing on the basis of WoT's high-level interaction paradigm - (involving the classes Property, Action, and Event), - schemas for the information exchanged with the Thing for machine-understandability, - and, finally, Web links to express any formal or informal relation to other Things. -

-

- Property affordances can be used for sensing and controlling parameters, - such as getting the current value or setting an operation state. - Action affordances model invocation of physical (and hence time-consuming) processes, - but can also be used to abstract RPC-like calls of existing platforms. - Event affordances are used for the push model of communication where notifications, - discrete events, or streams of values are sent asynchronously to the receiver. - In general, the TD provides metadata for different communication bindings - identified by URI schemes [[iana-uri-schemes]] (e.g., http, coap, etc.), - content types based on media types (e.g., "application/json", "application/xml", "application/cbor", - "application/exi" etc.) [[iana-media-types]], and security mechanisms (for authentication, - authorization, confidentiality, etc.). - Serialization of TD instances is based on JSON [[rfc8259]], where JSON keys refers to terms of - the TD core vocabulary, as defined in this specification document. In addition the JSON serialization of TDs - follows the syntax of JSON-LD 1.1 [[json-ld11]] to enable context extension and RDF processing. -

-

- Example 1 shows a TD instance with its different equivalent representation options (Simple, Full (JSON-LD 1.1), RDF) and - illustrates the TD model's Property, Action, - and Event classes by describing a lamp Thing with the name MyLampThing. -

- - - -

- Based on the content that can be seen in the Simple tab, - we know there exists one Property interaction resource - with the name status. - In addition, - information is provided to indicate that this Property is accessible via - (the secure form of) the HTTP protocol with a GET method - at the URI https://mylamp.example.com/status - (announced within the forms structure by the - href name), and will return a string-based status value. - The use of the GET method is not stated explicitly, - but is one of the default assumptions defined by this document and explained in [[wot-protocol-binding]]. -

-

- In a similar manner, an Action is specified to toggle the - switch status using the POST method applied to the - https://mylamp.example.com/toggle resource, - where POST is again a default assumption for invoking Actions. -

-

- The Event pattern enables a mechanism for asynchronous messages - to be sent by a Thing. - Here, a subscription to be notified upon a possible overheating event - of the lamp can be obtained by using the HTTP with its long polling - sub-protocol at https://mylamp.example.com/oh. -

- -

- This example also specifies the basic security scheme, - requiring a username and password for access. - Note that a security scheme is first given a name in a - securityDefinition and then activated by specifying - that name in a security section. - In combination with the use of the HTTP protocol this example - demonstrates the use of HTTP Basic Authentication. - Specification of at least one security scheme at the top level is mandatory, - and gives the default access requirements for every resource. - However, security schemes can also be specified per-form, - with configurations given at the form level overriding configurations given at the Thing level, - allowing for the specification of fine-grained access control. - It is also possible to use a special nosec security scheme to - indicate that no access control mechanisms are used. - Additional examples will be provided later. -

- -

- The TD in the Simple tab reflects some additional defined default assumptions - that are not explicitly described. - For example, the content type of the - exchange format of the interactions is assumed to be JSON - (=contentType). - Specifically, the TD specification defines vocabulary terms - (e.g., contentType, op, @contex) that have default values. - If one or more of these vocabulary terms are not explicitly used in a Thing Description - instance we will call it Simple and a Thing Description processor (e.g. based on a raw JSON parser) follows default - assumptions for interpretation as defined in this specification. - The Full (JSON-LD 1.1) tab shows the identical information of the - simple form of the Thing Description instance, but includes these mentioned implicit vocabulary terms with its default values. - A TD instance that contains all corresponding mandatory vocabulary terms, we will call this representation as Full - and can be passed, e.g, directly to a JSON-LD 1.1 processor for semantic interpretation. The RDF tab just shows - the RDF triples from the JSON-LD 1.1 representation (as defined in [[json-ld11]]). -

- -

- The Thing Description offers the possibility to add contextual definitions - in some namespace. This mechanism can be used to integrate additional semantics - to the content of the Thing Description instance, provided that formal knowledge, - e.g. logic rules for a specific domain of application, can be found under the - given namespace. Contextual information can also help specify some configurations and - behavior of the underlying communication protocols declared in the forms field. - Example 2 extends the TD sample from Example 1 by introducing a @context - key to declare the prefix htv as referring to the HTTP vocabulary namespace. - This namespace is used here to specify explicitly the HTTP methods for the property and - action within the forms. The declaration mechanism inside some - @context is specified by JSON-LD. A TD instance complies to version 1.1 of - this specification [[json-ld11]]. The TD instance can be also processed as an RDF - document (details are given in ). -

- - - -
- -
-

Terminology

-

Generic WoT terminology is defined in [[!WOT-ARCHITECTURE]]: - Thing, - Thing Description - (in short TD), - Web of Things (in short WoT), - WoT Interface etc. -

-
- -
-

Namespaces

-

- The namespace for the W3C Thing Description vocabulary as defined in - this document is http://www.w3.org/ns/td. -

-

- Using content negotiation, this namespace serves either the TD ontology file (Turtle) or the TD context file (JSON-LD). -

- - -
- -
-

Conformance

-

- As well as all sections marked as non-normative, - all authoring guidelines, diagrams, examples, and notes in this specification - are non-normative. - Everything else in this specification is normative. -

-

- The key words - MUST, - MUST NOT, - REQUIRED, - SHOULD, - SHOULD NOT, - RECOMMENDED, - MAY, - and OPTIONAL - in this specification are to be interpreted as described in [[!RFC2119]]. -

-

- A Thing Description instance complies with this specification if it follows - the normative statements in Section - - and Section - - regarding Thing Description serialization. -

-

- A JSON Schema [[?JSON-SCHEMA-VALIDATION]] is provided in Annex - - to validate Thing Description instances based on JSON serialization. -

- -

- In the future some information about RDF validation will be provided. -

- -
- - - -
-

Information Model

- -

This section introduces the Thing Description information model. - The Thing Description Information model serves as the conceptual basis - for the serialization and processing of Thing Description described - in later sections in this document.

- -

-

Overview

- -

- The W3C Thing Description provides a set of vocabulary for describing - physical and virtual Things. In general, the Thing Description vocabulary set is grouped in three modules: -

    -
  • the core Thing Description vocabulary reflecting WoT's paradigm of - Properties, Actions, and Events affordances (also see [[!WOT-ARCHITECTURE]])
    • -
  • the data schema vocabulary reflecting a subset of the terms defined in - JSON Schema [[?JSON-SCHEMA-VALIDATION]],
    • -
  • and the security vocabulary used to define security mechanism - configuration requirements.
    • -
- -

- - - -

- An overview of this vocabulary with its class context and class relation - is given by the following three figures. - Vocabulary terms identify members within the TD information model. - Both the terms shown on the left side of " : " (i.e. colon) in the boxes - representing classes and the terms labelling the arrows constitute - the vocabulary terms of Thing Description information model. - Please note that the figures reflect the vocabulary terms and structure - as they would be used in a Thing Description - instance (see Section ). - -

- - - -

- The following diagrams are automatically generated from the ontology files. The layout will be improved in one of the next TD updates. -

- - -
- TD core model figure -
TD core model (Click SVG file)
-
- -
- TD data schema model figure -
JSON schema model (Click SVG file)
-
- -
- TD security model figure -
WoT security model (Click SVG file)
-
- -
- Web linking model figure -
Web linking model (Click SVG file)
-
- - -

A detailed description of the vocabulary of the TD core model, - TD data schema model and TD security model is given in the following - sub-sections.

- -

- - All vocabulary restrictions noted in tables in Section , , and MUST be followed, - including mandatory items. - -

- -

- The section explains how to serialize these vocabulary terms to a Thing Description instance using a - JSON-based representation. It also defines default values for some mandatory vocabulary and explains the options how they can be serialized. -

- - -
-

Default Values for Vocabulary Terms

-

- - When values are not present for certain mandatory vocabulary terms in an instance of Thing Description information model, default values MUST be assumed as shown in the following table. - -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Vocabulary termDefault valueContext
- @context - "http://www.w3.org/ns/td"Thing
- contentType - application/json
- safe - false
- idempotent - false
- op - Array of strings with values readproperty followed by - writepropertyPropertyAffordance
- op - invokeactionActionAffordance
- op - subscribeeventEventAffordance
- in - headerBasicSecurityScheme
- DigestSecurityScheme
- BearerSecurityScheme
- PoPSecurityScheme
- in - queryAPIKeySecurityScheme
- qop - authDigestSecurityScheme
- alg - ES256BearerSecurityScheme
- PoPSecurityScheme
- format - jwtBearerSecurityScheme
- PoPSecurityScheme
- flow - implicitOAuth2SecurityScheme
-
- -
- -
-

Core Vocabulary Definition

-

In the following tables, - a type given as "map of X" should be interpreted as defining - an unordered collection of name-value pairs associating unique names - with values of type X. - Likewise a type given as "array of X" should be interpreted as defining an ordered - collection of instances of type X. -

- -

- Note that for now securityDefinitions are mandatory at the top level of a Thing - since there needs to be - at least one definition available for use in the top-level mandatory security - block. However, a future extension may allow in-place anonymous definitions - within security blocks in which case this requirement may be relaxed. -

- -

Thing

Describes a physical and/or virtual Thing (may represent one or more physical and/or virtual Things) in the Web of Things context.

When a concrete Thing is defined in a Thing Description, it is called a thing resource.

- - - - - - - - - - - - - -
Vocabulary termDescriptionMandatoryType
@contextKnown from JSON-LD [[!json-ld]], @context is used to define short-hand names called terms that are used throughout a TD document.yesstring or array
@typeKnown from JSON-LD [[!json-ld]], @type is used to state that a thing resource is an instance of a class.

Each string in the value array represents a class.		nostring or array of string
idunique identifier of the Thing (URI, e.g. custom URN).yesanyURI
nameName of the Thing.yesstring
descriptionProvides additional (human-readable) information based on a default language.nostring
descriptionsCan be used to support (human-readable) information in different languages.noMultiLanguage
versionProvides version information.noVersionInfo
createdProvides information when the TD instance was created.nostring
lastModifiedProvides information when the TD instance was last modified.nostring
supportProvides information about the TD maintainer (e.g., author, link or telephone number to get support, etc).nostring
baseDefine the base URI that is used for all relative URI references throughout a TD document. In TD instances, all relative URIs are resolved relative to the base URI using the algorithm defined in [[!RFC3986]].

base does not affect the URIs used in @context and the IRIs [[?RFC3987]] used within Linked Data [[?LINKED-DATA]] graphs that are relevant when semantic processing is applied to TD instances.		noanyURI
propertiesAll Property-based interaction affordance of the Thing.nomap of PropertyAffordance
actionsAll Action-based interaction affordance of the Thing.nomap of ActionAffordance
eventsAll Event-based interaction affordance of the Thing.nomap of EventAffordance
linksProvides Web links to arbitrary resources that relate to the specified Thing Description.noarray of Link
formsIndicates one or more endpoints at which operation(s) on this resource are accessible. In this version of TD, all operations that can be described at the Thing level are concerning how to interact with the Thing's Property interaction resources collectively at once.noarray of Form
securitySet of security definition names, chosen from those defined in securityDefinitions. These must all be satisfied for access to resources at or below the current level, if not overridden at a lower level.yesstring or array of string
securityDefinitionsSet of named security configurations (definitions only). Not actually applied unless names are used in a security section.yesSecurityScheme
-

- The mandatory - context definition of the string "http://www.w3.org/ns/td" MUST be - the first item in the @context array. - The mandatory - context definition MAY be followed by one or more context definitions as strings or - objects. -

-

- - As suggested in JSON-LD [[!json-ld]] specification, if a context definition is - a string, it SHOULD be a dereferenceable URL. - - - Likewise, if a context definition is an object, it SHOULD be a map of namespaces, - in which keys are namespace prefixes. - - Each optional - namespace specified in the @context array of a Thing MUST be bound - to an unique prefix. -

-

Similar to PropertyAffordance, - ActionAffordance and - EventAffordance classes, all of which are - subclasses of - InteractionAffordance, the definition of Thing class also contains - the forms term. - - When a forms term member is present in a Thing instance, - the value(s) in the op term member of the forms MUST be one or more of - readallproperties, writeallproperties, - readmultipleproperties or writemultipleproperties. - - (See an example for an usage of form in a thing resource.) -

-

- For readallproperties operation's output, - readmultipleproperties operation's output, - writeallproperties operation's input and writemultipleproperties - operation's input, payloads are assigned an object type schema with its - properties equal to the Thing's property resources. - For readmultipleproperties operation's input, payloads are - assigned a string array type schema with its items each equal to one of the names of - The Thing's property resources. -

-
-

InteractionAffordance

Three interaction affordance are defined as subclasses: Property-, Action- and Event-based affordances (also see [[!WOT-ARCHITECTURE]]). Interactions between Things can be as simple as one Thing accessing another Thing's data to get or (in the case the data is also writable) change the representation of data such as metadata, status or mode. A Thing may also be interested in getting asynchronously notified of future changes in another Thing, or may want to initiate a process served in another Thing that may take some time to complete and monitor the progress. Interactions between Things may involve exchanges of data between them. This data can be either given as input by the client Thing, returned as output by the server Thing or both.

When a concrete Property-, Action- or Event-based affordance is defined in a Thing Description, it is called an interaction resource.

- - - - -
Vocabulary termDescriptionMandatoryType
@typeKnown from JSON-LD [[!json-ld]], @type is used to state that an interaction resource is an instance of a class.

Each string in the value array represents a class.		nostring or array of string
titleProvides a human-readable title (e.g., display a text for UI representation) of the interaction pattern based on a default language.nostring
titlesProvides multi-language human-readable titles (e.g., display a text for UI representation in different languages) of the interaction pattern.noMultiLanguage
descriptionProvides additional (human-readable) information based on a default language.nostring
descriptionsCan be used to support (human-readable) information in different languages.noMultiLanguage
formsIndicates one or more endpoints at which operation(s) on this resource are accessible.yesarray of Form
uriVariablesDefine URI template variables as collection based on DataSchema declarations.nomap of DataSchema

The class InteractionAffordance has the following subclasses:

-

- - Each instance of a Property, Action, - and Event class MUST have an identifier that is - unique within the context of a Thing Description document. - - -

- -

PropertyAffordance

Properties expose internal state of a Thing that can be directly retrieved (get) and optionally modified (set). In addition, Things can also choose to make Properties observable by pushing the new state (not an event) after a change; this must follow eventual consistency.

Vocabulary termDescriptionMandatoryType
observableA hint that indicates whether a remote client can subscribe to ("observe") the Property, to receive change notifications or periodic updates (true/false).noboolean
-

Property class is a subclass of the class InteractionAffordance. - - When a forms term member is present in a Property instance, - the value(s) in the op term member of the forms MUST be one or more of - readproperty, writeproperty, observeproperty or unobserveproperty. - -

-

- Property instances are also instances of the class - DataSchema. Therefore, - it can contain the type, unit, - readOnly and writeOnly members, among - others. -

-

- - When the value of readOnly member is true in an instance of PropertyAffordance, - the value(s) in the op term member of the forms - MUST NOT contain writeproperty. - - Similarly, - - when the value of writeOnly member is true in an instance of PropertyAffordance, - the value(s) in the op term member of the forms - MUST NOT contain readproperty. - -

-
-

ActionAffordance

Actions offer functions of the Thing. These functions may manipulate the internal state of a Thing in a way that is not possible through setting Properties. Examples are changing internal state that is not exposed as a Property, changing multiple Properties, changing Properties over time or with a process that should not be disclosed. Actions may also be pure functions, that is, they may not use any internal state at all, and may simply process input data and return a result that directly depends only on the input given.

- - -
Vocabulary termDescriptionMandatoryType
inputUsed to define the input data schema of the action.noDataSchema
outputUsed to define the output data schema of the action.noDataSchema
safeSignals if the action is safe (=true) or not. Used to signal if there is no internal state (cf. resource state) is changed when invoking an Action. In that case responses can be cached as example.yesboolean
idempotentIndicates whether the action is idempotent (=true) or not. Informs whether the action can be called repeatedly with the same result, if present, based on the same input.yesboolean
-

Action class is a subclass of the class InteractionAffordance. - - When a forms term member is present in an Action instance, - the value in the op term member of the forms MUST be - invokeaction. - -

-
-

EventAffordance

The Event Interaction Pattern describes event sources that asynchronously push messages. Here not state, but state transitions (events) are communicated (e.g., "clicked"). Events may be triggered by internal state changes that are not exposed as Properties. Events usually follow strong consistency, where messages need to be queued to ensure eventual delivery of all events that have occurred.

- -
Vocabulary termDescriptionMandatoryType
subscriptionDefines data that needs to be passed upon subscription, e.g., filters or message format for setting up Webhooks.noDataSchema
dataDefines the data schema of the Event instance messages pushed by the Thing.noDataSchema
cancellationDefines any data that needs to be passed to cancel a subscription, e.g., a specific message to remove a Webhook.noDataSchema
-

Event class is a subclass of the class InteractionAffordance. - - When a forms term member is present in an Event instance, - the value(s) in the op term member of the forms MUST be either or both of - subscribeevent or/and unsubscribeevent. - -

-
-

Form

Communication metadata indicating where a service can be accessed by a client application. An interaction might have more than one form.

- - - - - -
Vocabulary termDescriptionMandatoryType
hrefURI of the endpoint where an interaction pattern is provided.yesanyURI
contentTypeAssign a content type based on a media type [[!IANA-MEDIA-TYPES]] (e.g., 'application/json) and (optional) parameters (e.g., 'charset=utf-8').yesstring
responseThis optional term can be used if, e.g., the output communication metadata differ from input metdata (e.g., output contentType differ from the - input contentType). The response name contains metadata that is only valid for the reponse messages.noExpectedResponse
opIndicates the semantic intention of performing the operation(s) described by the form. - -For example, the Property interaction allows get and set operations. -The protocol binding may contain a form for the get operation and a different form for the set operation. -The op attribute indicates which form is for which and allows the client to select 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.yesstring or array of string (one of readproperty, writeproperty, observeproperty, unobserveproperty, invokeaction, subscribeevent, unsubscribeevent, readallproperties, writeallproperties, readmultipleproperties, or writemultipleproperties)
subprotocolIndicates the exact mechanism by which an interaction will be accomplished for a given protocol when there are multiple options. - -For example, for HTTP and Events, it indicates which of several available mechanisms should be used for asynchronous notifications such as long polling, websub (also see https://www.w3.org/TR/websub/), or server sent events (also see https://www.w3.org/TR/eventsource/). Please note that there is no restriction on the sub-protocol selection and other mechanisms can also be announced by this subprotocol term.nostring (e.g. longpoll, websub, or sse)
securitySet of security definition names, chosen from those defined in securityDefinitions. These must all be satisfied for access to resources at or below the current level, if not overridden at a lower level.nostring or array of string
scopesSet of authorization scope identifiers, provided as an array. These are provided in tokens returned by an authorization server and associated with forms in order to identify what resources a client may access and how.nostring or array of string
-

VersionInfo

Carries version information about the TD instance. If required, additional version information such as firmware and hardware version (term definitions outside of the TD namespace) can be extended here.

Vocabulary termDescriptionMandatoryType
instanceProvides a version identicator of this TD instance.yesstring
-

ExpectedResponse

Communication metadata for response messages (e.g., contentType of the response).

Vocabulary termDescriptionMandatoryType
contentTypeAssign a content type based on a media type [[!IANA-MEDIA-TYPES]] (e.g., 'application/json) and (optional) parameters (e.g., 'charset=utf-8').yesstring
-

MultiLanguage

Container to provide human-readable text in different languages using language tags described in [[!BCP47]]. Each used language tags code MUST be decleared as vocabulary term member of this container (e.g., en, de, ja, zh-Hans, zh-Hant). See for example usages of this container in a Thing Description instance.

-

- -Note that in protocols such as HTTP that have an ability to negotiate content based on languages, -those terms (e.g. description and title) intended for carrying texts in a default language SHOULD be used instead of MultiLanguage container -when the texts are served as a result such negotiation. - -

-
- -
- -
-

Data Schema Vocabulary Definition

-

- The data schema definition reflecting a very common subset of the terms defined in JSON Schema [[?JSON-SCHEMA-VALIDATION]]. It is noted - that data schema definitions within Thing Description instances are not limited to this defined subset and MAY use additional terms you - find in JSON Schema. It that case it is recommended to use context association for that additional terms as described in - , otherwise these terms are semantically ignored (also see ). -

- -

DataSchema

A JSON specification.

- - - - - - - - - - -
Vocabulary termDescriptionMandatoryType
@typeKnown from JSON-LD [[!json-ld]], @type is used to state that values described by the DataSchema are instances of a class.

Each string in the value array represents a class.		nostring or array of string
titleProvides a human-readable title (e.g., display a text for UI representation) of the interaction pattern based on a default language.nostring
titlesProvides multi-language human-readable titles (e.g., display a text for UI representation in different languages) of the interaction pattern.noMultiLanguage
descriptionProvides additional (human-readable) information based on a default language.nostring
descriptionsCan be used to support (human-readable) information in different languages.noMultiLanguage
typeAssignment of JSON-based data types compatible with JSON Schema (one of boolean, integer, number, string, object, array, or null).nostring (one of object, array, string, number, integer, boolean, or null)
constProvides a constant value.noany type
unitProvides unit information that is used, e.g., in international science, engineering, and business.nostring
oneOfUsed to ensure that the data is valid against one of the specified schemas in the array.noarray of DataSchema
enumRestricted set of values provided as an array.noarray of any type
readOnlyBoolean value that is a hint to indicate whether a property interaction / value is read only (=true) or not (=false).noboolean
writeOnlyBoolean value that is a hint to indicate whether a property interaction / value is write only (=true) or not (=false).noboolean
formatDefines format pattern validation on certain kinds of string values. It is open to use pattern values that may originate from JSON schema presets (e.g., date/time, email, URL) or other (custom-based) definitions.nostring

The class DataSchema has the following subclasses:

-

- The mandatory - context definition of the string "http://www.w3.org/ns/json-schema" MUST be - the first item in the @context array. - The mandatory - context definition MAY be followed by one or more context definitions as strings or - objects. -

-

- - As suggested in JSON-LD [[!json-ld]] specification, if a context definition is - a string, it SHOULD be a dereferenceable URL. - - - Likewise, if a context definition is an object, it SHOULD be a map of namespaces, - in which keys are namespace prefixes. - - Each optional - namespace specified in the @context array of a DataSchema MUST be bound - to an unique prefix. -

-
-

ArraySchema

A JSON array specification ("type": "array").

- -
Vocabulary termDescriptionMandatoryType
itemsUsed to define the characteristics of an array.noDataSchema or array of DataSchema
minItemsDefines the minimum number of items that have to be in the array.nounsignedInt
maxItemsDefines the maximum number of items that have to be in the array.nounsignedInt
-

BooleanSchema

A JSON boolean value specification ("type": "boolean").

-

NumberSchema

A JSON number value specification ("type": "number").

-
Vocabulary termDescriptionMandatoryType
minimumSpecifies a minimum numeric value. Only applicable for associated number or integer types.nodouble
maximumSpecifies a maximum numeric value. Only applicable for associated number or integer types.nodouble
-

IntegerSchema

A JSON integer value specification, that is, numbers without a fractional part ("type": "integer").

-
Vocabulary termDescriptionMandatoryType
minimumSpecifies a minimum numeric value. Only applicable for associated number or integer types.nointeger
maximumSpecifies a maximum numeric value. Only applicable for associated number or integer types.nointeger
-

ObjectSchema

A JSON object specification ("type": "object").

-
Vocabulary termDescriptionMandatoryType
propertiesData schema nested definitions.nomap of DataSchema
requiredDefines which members of the object type are mandatory.noarray of string
-

StringSchema

A JSON string value specification ("type": "string").

-

NullSchema

A JSON null value specification ("type": "null"). If the type of null then it has only one acceptable value, namely null. E.g., it can be used as part of oneOf declaration, where it is used to indicate, that a data schema can also be null.

-
- -
-

Security Vocabulary Definition

- -

- For the core TD vocabulary only well-established security - mechanisms are supported, such as those built into protocols supported by WoT - or already in wide use with those protocols. - The current set of HTTP security schemes is partly based on - OpenAPI 3.0.1 (see also [[?OPENAPI]]). - Note however that while the HTTP security schemes, - vocabulary and syntax given in this specification share many similarities - with OpenAPI they are not fully compatible. - Also, since OpenAPI primarily targets web services built around HTTP, it does not - cover the full set of use cases required for the IoT. - Security schemes appropriate - for IoT-centered protocols such as CoAP [[?RFC7252]] and MQTT [[?MQTT]] are therefore also included. -

- -

- The vocabulary extension mechanism of the - WoT Thing Description allows for additional security schemes if needed. - However, for more information about what additional security schemes - or modifications are under discussion for the core WoT vocabulary - (and to file issues if you have a request) please visit the - WoT Security TF repository. -

- -

SecurityScheme

- - -
Vocabulary termDescriptionMandatoryType
@typeKnown from JSON-LD [[!json-ld]], @type is used to state that a security mechanism configured by the SecurityScheme is an instance of a class.

Each string in the value array represents a class.		nostring or array of string
schemeIdentification of security mechanism being configured.yesstring (one of nosec, basic, cert, digest, bearer, pop, psk, public, oauth2, or apikey)
descriptionProvides additional (human-readable) information based on a default language.nostring
descriptionsCan be used to support (human-readable) information in different languages.noMultiLanguage
proxyURI of the proxy server this security configuration provides access to. If not given, the corresponding security configuration is for the endpoint.noanyURI

The class SecurityScheme has the following subclasses:

-

- The mandatory - context definition of the string "http://www.w3.org/ns/wot-security" MUST be - the first item in the @context array. - The mandatory - context definition MAY be followed by one or more context definitions as strings or - objects. -

-

- - As suggested in JSON-LD [[!json-ld]] specification, if a context definition is - a string, it SHOULD be a dereferenceable URL. - - - Likewise, if a context definition is an object, it SHOULD be a map of namespaces, - in which keys are namespace prefixes. - - Each optional - namespace specified in the @context array of a SecurityScheme MUST be bound - to an unique prefix. -

-
-

NoSecurityScheme

A security configuration corresponding to ("scheme": "nosec"), indicating there is no authentication or other mechanism required to access the resource.

-

BasicSecurityScheme

Basic authentication security configuration ("scheme": "basic"), using an unencrypted username and password. This scheme should be used with some other security mechanism providing confidentiality, for example, TLS.

-
Vocabulary termDescriptionMandatoryType
inSpecifies the location of security authentication information (one of header, query, body, or cookie).yesstring
nameName for query, header, or cookie parameters.nostring
-

DigestSecurityScheme

Digest authentication security configuration ("scheme": "digest"). This scheme is similar to basic authentication but with added features to avoid man-in-the-middle attacks.

- -
Vocabulary termDescriptionMandatoryType
qopQuality of protection (one of auth or auth-int).yesstring
inSpecifies the location of security authentication information (one of header, query, body, or cookie).yesstring
nameName for query, header, or cookie parameters.nostring
-

APIKeySecurityScheme

This section is at risk.

API key authentication security configuration ("scheme": "apikey"). This is for the case where the access token is opaque and is not using a standard token format.

-
Vocabulary termDescriptionMandatoryType
inSpecifies the location of security authentication information (one of header, query, body, or cookie).yesstring
nameName for query, header, or cookie parameters.nostring
-

BearerSecurityScheme

Bearer token authentication security configuration ("scheme": "bearer"). This scheme is intended for situations where bearer tokens are used independently of OAuth2. If the oauth2 scheme is specified it is not generally necessary to specify this scheme as well as it is implied.

- - - -
Vocabulary termDescriptionMandatoryType
authorizationURI of the authorization server.noanyURI
algEncoding, encryption, or digest algorithm (one of MD5, ES256, or ES512-256).yesstring
formatSpecifies format of security authentication information (one of jwt, jwe, or jws).yesstring
inSpecifies the location of security authentication information (one of header, query, body, or cookie).yesstring
nameName for query, header, or cookie parameters.nostring
-

CertSecurityScheme

This section is at risk.

Certificate-base asymmetric key security configuration ("scheme": "cert").

Vocabulary termDescriptionMandatoryType
identityPre-shared key identity.nostring
-

PSKSecurityScheme

This section is at risk.

Pre-shared key authentication security configuration ("scheme": "psk").

Vocabulary termDescriptionMandatoryType
identityPre-shared key identity.nostring
-

PublicSecurityScheme

This section is at risk.

Raw public key asymmetric key security configuration ("scheme": "public").

Vocabulary termDescriptionMandatoryType
identityPre-shared key identity.nostring
-

PoPSecurityScheme

This section is at risk.

Proof-of-possession token authentication security configuration ("scheme": "pop").

- - - -
Vocabulary termDescriptionMandatoryType
authorizationURI of the authorization server.noanyURI
algEncoding, encryption, or digest algorithm (one of MD5, ES256, or ES512-256).yesstring
formatSpecifies format of security authentication information (one of jwt, jwe, or jws).yesstring
inSpecifies the location of security authentication information (one of header, query, body, or cookie).yesstring
nameName for query, header, or cookie parameters.nostring
-

OAuth2SecurityScheme

This section is at risk.

OAuth2 authentication security configuration ("scheme": "oauth2"). For the implicit flow the authorization and scopes are required. For the password and client flows both token and scopes are required. For the code flow authorization, token, and scopes are required.

- - - -
Vocabulary termDescriptionMandatoryType
authorizationURI of the authorization server.noanyURI
tokenURI of the token server.noanyURI
refreshURI of the refresh server.noanyURI
scopesSet of authorization scope identifiers, provided as an array. These are provided in tokens returned by an authorization server and associated with forms in order to identify what resources a client may access and how.nostring or array of string
flowAuthorization flow (one of implicit, password, client, or code).yesstring
-
- -
-

Web Linking Vocabulary Definition

-

- The present model provides a representation for (typed) Web links exposed by - a Thing. It is designed after the CoRE Link format [[RFC6690]]. -

- -

Link

A link can be viewed as a statement of the form "link context has a link relation type resource at link target, which has target attributes".

- - -
Vocabulary termDescriptionMandatoryType
hrefEach link-value conveys one target IRI as a URI-Reference (after conversion to one, if necessary; see RFC3987, Section 3.1) inside angle brackets ("<>").yesanyURI
typeTarget attribute providing a hint indicating what the media type [IANA-MEDIA-TYPES] of the result of dereferencing the link should be.nostring
relA link relation type identifies the semantics of a link.nostring
anchorBy default, the context, or anchor, of a link conveyed in the Link header field is the URL of the representation it is associated with, as defined in RFC7231, Section 3.1.4.1, and is serialized as a URI.noanyURI
-
- -
- -
-

Thing Description Serialization

- -

- Thing Description instances are modeled and structured based on Section - . - -

- -

- The JSON serialization of TDs follows the syntax of JSON-LD 1.1 [[json-ld11]] in order to streamline semantic evaluation. - Hence, serializations can be parsed either as raw JSON or with a JSON-LD 1.1 processor. -

- -
-

Basic Representation Format Assumptions

- - -

- As a fundamental basis, - all vocabulary terms defined in Section - - will have a JSON name representation. -

- - -

- The data types of the vocabulary as defined in Section - - will be transformed to JSON-based types. - The following rules are used for vocabulary terms based on some simple type - definitions: -

-
    -
  • - Vocabulary terms that use simple types string and anyURI - MUST be serialized as JSON string. -
    • -
  • - Vocabulary terms that use simple type integer - MUST be serialized as JSON number without a fraction or exponent part. -
    • -
  • - Vocabulary terms that use simple type double - MUST be serialized as JSON number. -
    • -
- - - - - - - - -

- In addition, - Thing Description instances MAY contain additional JSON-LD [[json-ld11]] keywords such as - @context and @type. With these the Thing Description can - be easily extended. You can find additional details in the Section . - - - - - In the case of @type usage in the Thing Description instance, the @type MUST be serialized as JSON String or as JSON array of strings when multiple values are assigned to @type. - -

- -

- - A Thing Description instance serialization MAY omit one ore more vocabulary terms that are mandatory () AND have default values assumed based on the table in . - - In this specification, this form is referred to as Simple Thing Description representation. - The interpretation of such Simple Thing Descriptions (e.g. via a raw JSON parser) MUST always follow the - default value assumptions of the omitted vocabulary terms. - If a Thing Description instance contains all mandatory vocabulary, we will call this representation as - Full Thing Description and can be passed directly to a JSON-LD 1.1 processor for interpretation or - RDF semantic processing. -

- - - -

- All vocabulary terms in Section - - associated with more complex class-based types are defined separately for - structured JSON type transformation in the following subsections. -

- -
-

Thing as a whole

- -

- The root object of a Thing Description instance MAY include the - @context name known from JSON-LD [[json-ld11]] with the value URI of - the Thing description context file http://www.w3.org/ns/td. -

- -
-{  
-    "@context": "http://www.w3.org/ns/td",
-    ...
-}
-
- -

- http://www.w3.org/ns/td uses content negotiation to return the - context file. Thus, it must be fetched with an Accept header set - to application/ld+json. -

- -

- When a single Thing Description instance involves several contexts, - additional namespaces with prefixes MUST be appended to the - @context array structure. - This option proves relevant if one wants to extend the existing - Thing Description context without modifying it. For instance: -

-
-{
-    "@context": ["http://www.w3.org/ns/td",
-                {"iot": "http://example.org/iot"}],
-    ...
-}
-
- -

- Each mandatory and optional member name - as defined in the class Thing - MUST be serialized as a JSON name - in the root object of the Thing Description instance. -

- - -

- The type of the members properties, actions, - events, version, and securityDefinitions MUST be a JSON object. -

- -

- The type of the members forms, links, - scopes, and security - MUST be a JSON array. -

- -

- A TD snippet based on the defined members of the class - Thing - without the optional member @context is given below: -

-
-{
-    "id": "urn:dev:wot:com:example:servient:myThing",
-    "name": "MyThing",
-    "description": "Human readable information.",
-    "descriptions": {...},
-    "support": "mailto:support@example.com",
-    "securityDefinitions": {...},
-    "security": [...],
-    "base": "https://servient.example.com/",
-    "lastModified" : "2018-11-15T09:12:43.124Z",
-    "created" : "2018-11-14T19:10:23.824Z",
-    "version" : {...},
-    "properties": {...},
-    "actions": {...},
-    "events": {...},
-    "links": [...],
-    "forms": [...]
-}
-
- -

Alternatively, the same example can be written instead to - explicitly include the (semantic) names used by JSON-LD [[json-ld11]], namely @context and @type: -

-
-{
-    "@context": "http://www.w3.org/ns/td",
-    "@type": "Thing",
-    "id": "urn:dev:wot:com:example:servient:myThing",
-    "name": "MyThing",
-    "description": "Human readable information.",
-    "descriptions": {...},
-    "support": "mailto:support@example.com",
-    "securityDefinitions": {...},
-    "security": [...],
-    "base": "https://servient.example.com/",
-    "lastModified" : "2018-11-15T09:12:43.124Z",
-    "created" : "2018-11-14T19:10:23.824Z",
-    "version" : {...},
-    "properties": {...},
-    "actions": {...},
-    "events": {...},
-    "links": [...],
-    "forms": [...]
-}
-
- -

In that case the content can be directly associated as Thing Description based on the namespace http://www.w3.org/ns/td provided - in the @context. The "@type": "Thing" associates an instantiations of the Thing class as defined in Section . - -

- -
- -
-

properties

- -

- Properties (and sub-properties) offered by a Thing MUST be collected - in the JSON-object based properties member - with (unique) Property names as JSON names. -

- -

- - Each mandatory and optional vocabulary term - as defined in the class Property, - as well as its two superclasses - InteractionAffordance - and DataSchema, - MUST be serialized as a JSON name within a Property object. This means that at the level of an interaction property instance, the vocabulary terms - of InteractionAffordance - and DataSchema can be presented at the same time. -

- -

- The type of the member forms - MUST be serialized as a JSON array. -

- -

- A TD snippet based on the defined members is given below: -

- - - - - - - - - - - - - -
- -
-

actions

- -

- Actions offered by a Thing MUST be collected - in the JSON-object based actions member - with (unique) Action names as JSON names. -

- -

- - Each optional vocabulary term - as defined in the class Action - and its superclass - InteractionAffordance - MUST be serialized as a JSON name within an Action object. -

- -

- The type of the members input and output - MUST be serialized as a JSON object. -

- -

The names input and output - rely on the the class DataSchema and will follow the serialization introduction provided in . -

- -

- The type of the member forms - MUST be serialized as a JSON array. -

- -

- A TD snippet based on the defined members is given below: -

- - - - -
- -
-

events

- -

- Events offered by a Thing MUST be collected - in the JSON-object based events member - with (unique) Event names as JSON names. -

- -

- - Each optional vocabulary term - as defined in the class Event, - as well as its two superclasses - InteractionAffordance - and DataSchema, - MUST be serialized as a JSON name within an Event object. -

- -

- The type of the members subscription, data, and cancellation - MUST be serialized as a JSON object. -

- -

The JSON names of subscription, data, and cancellation - rely on the the class DataSchema and will follow the serialization introduction provided in . -

- -

- The type of the member forms - MUST be serialized as a JSON array. -

- -

- A TD snippet based on the defined members is given below: -

- - - -Please note that the definition of the event affordance is flexibly defined in order to adopt existing (e.g. WebSub) or customer-oriented event mechanisms. -For this reason, subscription and cancellation can be defined according to the desired mechanism. Please find further details in [[!WOT-PROTOCOL-BINDING]]. -Example provides a Thing-to-Thing (T2T) use case that offers an event and uses subscription and cancellation. -

- -
- -
-

forms

- -

- Each mandatory and optional vocabulary term - as defined in the class Form, - MUST be serialized as a JSON name. -

- -

- If required, the type of the member response - MUST be serialized as a JSON object. - -

- -

- If required, forms - MAY be supplemented with protocol-specific vocabulary terms - identified with a prefix. - - See also . -

- - -

A TD snippet based on the defined members is given below:

-
-{
-  "@context": ["http://www.w3.org/ns/td",
-    {"htv": "http://www.w3.org/2011/http#"}],
-  ...
-  "securityDefinitions": {
-      "basic_sc": {"scheme":"basic", "in":"header"}
-  },
-    ...
-    "forms": [{
-        "href" : "http://mytemp.example.com:5683/temp",
-        "contentType": "application/json",
-        "htv:methodName": "POST",
-        "op": ["writeproperty"],
-        "security": ["basic_sc"]
-    }]
-    ...
-}
-
- -

href may also carry an URI that contains dynamic variables such as p and d in http://192.168.1.25/left?p=2&d=1. In that case the URI can be defined as template as defined in [[!RFC6570]]: http://192.168.1.25/left{?p,d}

- -

- In such a case these variables in the URI MUST be collected - in the JSON-object based uriVariables member - with the associated (unique) variables names as JSON names. -

- -

- Each defined JSON name of the uriVariables collection MUST - rely on the the class DataSchema. -

- - - - -

A TD snippet using URI template and uriVariables is given below:

- - 
-        "@context": ["http://www.w3.org/ns/td",
-            {"htv": "http://www.w3.org/2011/http#"},
-            {"eg": "http://www.example.org/iot"}],
-        ...
-        "actions": {
-            "LeftDown": {
-              "uriVariables": {
-                "p" : { "type": "integer", "minimum": 0, "maximum": 16, "@type": "eg:SomeKindOfAngle" },
-                "d" : { "type": "integer", "minimum": 0, "maximum": 1, "@type": "eg:Direction" }
-                }
-              },
-              "forms": [{
-                "htv:method": "GET",
-                "href" : "http://192.168.1.25/left{?p,d}"
-              }]
-            }
-        ...
-
- - -

The contentType is used to assign a media types [[!IANA-MEDIA-TYPES]] and MAY contain one or more parameters as - attribute-value pair separated by a ; character. Example:

- - 
-    ...
-    "contentType" : "text/plain; charset=utf-8"
-    ...
-
- -

In some use cases, the form metadata of the interaction affordance must be distinguished between request and response based messages. E.g., an action 'takePhoto' -defines an input to submit parameter settings of a camera (aperture priority, timer,..) using json as content type (="contentType":"application/json"). -The output of this action is the photo taken, which is available in jpeg format, for example. In such cases, the response can be used to provide a - response content type (e.g., "contentType":"image/jpeg"). -

- -

- If the response member is used in forms, it MUST contain the contentType as - defined in class ExpectedResponse. -

- -

A form snippet with the response member is listed below based on the use case of the action 'takePhoto' described above:

- -
-    "@context": ["http://www.w3.org/ns/td",
-        {"htv": "http://www.w3.org/2011/http#"}],
-    ...
-    "forms": [
-        {
-          "href": "http://upsq1c.local:9191/api/frame/crop",
-          "contentType": "application/json",
-          "op": ["invokeaction"],
-          "htv:methodName": "POST",
-          "response": {
-            "contentType": "image/jpeg"
-          }
-        }
-      ]
-    ...
-
- -

When forms is present at the top level, it can be used to describe meta interactions supported by a Thing instance. For example, operations "readallproperties" and "writeallproperties" are meta interactions by which clients can read and write all properties of the thing at once. In the example below, forms is used at the top level, and the clients can access end point (i.e. https://mylamp.example.com/allproperties) both to read or write all properties (i.e. "on", "brightness" and "timer" property) of the thing in a single interaction.

- -
-{
-    "@context": ["http://www.w3.org/ns/td",
-        {"htv": "http://www.w3.org/2011/http#"}],
-    "id": "urn:dev:wot:com:example:servient:lamp",
-    ...
-    "forms": [
-        {
-          "href": "https://mylamp.example.com/allproperties",
-          "contentType": "application/json",
-          "op": ["readallproperties"],
-          "htv:methodName": "GET"
-        },
-        {
-          "href": "https://mylamp.example.com/allproperties",
-          "contentType": "application/json",
-          "op": ["writeallproperties"],
-          "htv:methodName": "PUT"
-        }
-    ],
-    ...
-    "properties": {
-        "on": {
-          "type": "boolean",
-          "forms": [...]
-        },
-        "brightness": {
-          "type": "number",
-          "forms": [...]
-        },
-        "timer": {
-          "type": "integer",
-          "forms": [...]
-        }
-    },
-    ...
-}
-
- - -
- - - -
-

securityDefinitions and security

- -

- Each mandatory and optional vocabulary term - as defined in the class - SecurityScheme, - MUST be serialized as a JSON name. -

- -

- The following TD snippet shows a simple security configuration specifying - basic username/password authentication in the header. - The value of in given is actually the default value of - header. - First, a named security configuration must be given - in a securityDefinitions block. - Second, that definition must be activated in a security - block. -

-
-   ...
-   "securityDefinitions": {
-       "basic_sc": {
-           "scheme": "basic",
-           "in": "header"
-       }
-   },
-   ...
-   "security": ["basic_sc"]
-   ...
-
- -

- Here is a more complex example: a TD snippet showing digest - authentication on a proxy combined with bearer token authentication - on an endpoint. - Here the default - value of in in the digest scheme, - header, is implied. -

-
-    ...
-    "securityDefinitions": {
-        "basic_sc": {
-           "scheme": "digest",
-           "proxy": "https://portal.example.com/"
-        },
-        "bearer_sc": {
-           "in":"header",
-           "scheme": "bearer",
-           "format": "jwt",
-           "alg": "ES256",
-           "authorization": "https://servient.example.com:8443/"
-        }
-    },
-    ...
-    "security": ["basic_sc","bearer_sc"],
-    ...
-
- -

- Security configuration is mandatory. - - Every Thing MUST have at least one security scheme specified at the top level. - - - Security schemes MAY also be specified at the form level. - In this case, definitions at the form level override (completely replace) - all definitions given at the top level. - -

-

- The nosec security scheme is provided for the case that - no security is needed. - The minimal security configuration for a Thing is configuration - of the nosec security scheme - at the top level, as in the following example: -

-
-{
-    "id": "urn:dev:wot:com:example:servient:myThing",
-    "name": "MyThing",
-    "description": "Human readable information.",
-    "support": "https://servient.example.com/contact",
-    "securityDefinitions": {"nosec_sc": {"scheme": "nosec"}},
-    "security": ["nosec_sc"],
-    "properties": {...},
-    "actions": {...},
-    "events": {...},
-    "links": [...]
-}
-
- -

- To give a more complex example, - suppose we have a Thing where all interactions - require basic authentication except for one interaction for which - no authentication is required. - In the following, the nosec scheme for - the security configuration in the overheating event - to indicate no authentication is required. - For the status property and the toggle - action, however, basic authentication is required as defined - at the top level of the Thing. -

-
-{
-    ...
-    "securityDefinitions": {
-        "nosec_sc": {"scheme": "nosec"},
-        "basic_sc": {"scheme": "basic"}
-    },
-    "security": ["basic_sc"],
-    ...
-    "properties": {
-        "status": {
-            ...
-            "forms": [{
-                "href": "https://mylamp.example.com/status",
-                "contentType": "application/json",
-            }]
-        }
-    },
-    "actions": {
-        "toggle": {
-            ...
-            "forms": [{
-                "href": "https://mylamp.example.com/toggle",
-                "contentType": "application/json"
-            }]
-        }
-    },
-    "events": {
-        "overheating": {
-            ...
-            "forms": [{
-                "href": "https://mylamp.example.com/oh",
-                "contentType": "application/json",
-                "security": ["nosec_sc"] 
-            }]
-        }
-    }
-}
-
- -

- Security configurations can also can be specified for different forms - within the same interaction. This may be required for devices that support - multiple protocols, for example CoAP [[?RFC7252]] and HTTP, with support for different - security mechanisms. This is also useful when alternative authentication - mechanisms are allowed. Here is a TD snippet demonstrating three possible - ways to access a resource: via HTTPS with basic authentication, via HTTPS - via digest authentication, or via CoAPS with an API key. - In other words, - the use of multiple security configurations at the same level - provides a way to combine security mechanisms an in "OR" fashion. - In contrast, putting multiple security configurations in the same - security member combines them in an "AND" fashion, - since in that case - they would all need to be satisfied to allow access to the resource. - Note that a security declaration is still mandatory at the - Thing level. Here we use a nosec scheme for symmetry - but could also have used any one of the other ones as it will be - overridden in each form. -

-
-    "securityDefinitions": {
-        "nosec_sc": {"scheme": "nosec"},
-        "basic_sc": {"scheme": "basic"},
-        "digest_sc": {"scheme": "digest","qop":"auth","in":"header"},
-        "apikey_sc": {"scheme": "apikey","in":"header"}
-    },
-    "security": ["nosec_sc"]
-    ...
-    "properties": {
-        "status": {
-            ...
-            "forms": [
-                {
-                    "href": "https://mylamp.example.com/status",
-                    "contentType": "application/json",
-                    "security": ["basic_sc"]
-                },
-                {
-                    "href": "https://mylamp.example.com/status",
-                    "contentType": "application/json",
-                    "security": ["digest_sc"]
-                },
-                {
-                    "href": "coaps://mylamp.example.com:5683/status",
-                    "contentType": "application/json",
-                    "security": ["apikey_sc"]
-                }
-            ]
-        }
-    },
-    ...
-
-

As another more complex example, OAuth2 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. - For example, in the following, the "status" property can be - read by users using bearer tokens containing the scope "limited" - but the "configure" action can only be - used when the interaction is invoked 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 can perform "special" interactions. - 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. -

-
-    ...
-    "securityDefinitions": {
-        "oauth2_sc": {
-            "scheme": "oauth2",
-            ...
-            "scopes": ["limited","special"]
-        }
-    },
-    "security": ["oauth2_sc"],
-    "properties": {
-        "status": {
-            ...
-            "forms": [
-                {
-                    "href": "https://scopes.example.com/status",
-                    "contentType": "application/json",
-                    "scopes": ["limited"]
-                }
-            ]
-        }
-    },
-    "action": {
-        "configure": {
-            ...
-            "forms": [
-                {
-                    "href": "https://scopes.example.com/configure",
-                    "contentType": "application/json",
-                    "scopes": ["special"]
-                }
-            ]
-        }
-    },
-    ...
-
- -
-
-

version

- -

- The mandatory vocabulary term - as defined in the class VersionInfo, - MUST be serialized as a JSON name. -

- -

The recommended version identification pattern value is to rely on the semantic versioning policy: [[?SemVer]]

- -

A TD snippet based on the defined members is given below:

- 
-        ...
-        "version": {"instance":"1.2.1"}
-        ...
-
- -

- The version container MAY be used to provide additional application and/or device specific version information based on terms from non-TD namespaces. -

- -

A TD snippet based on such additional version metadata from a v context is given below:

- 
-        "@context": ["http://www.w3.org/ns/td",
-                    {"v": "http://www.example.org/versioningTerms#"}],
-        ...
-        "version": {"instance":"1.2.1", "v:firmware": "0.9.1", "v:hardware": "1.0"}
-        ...
-
- -
- -
-

Data Schema Representation

-

The data schema concept within the Thing Description is based on a subset of JSON schema terms. The data schema concept is applied - to the properties interaction declaration, input and output within actions - interaction declaration, subscription, data and cancellation within events interaction declaration, - and uriVariables that can be used within the forms container. -

- -

- - Each mandatory and optional vocabulary term as defined in the class - DataSchema, - MUST be serialized as a JSON name. - -

- - - -

- The type of the members properties and items - MUST be serialized as a JSON object. -

- -

- The type of the member enum, required, and oneOf MUST be serialized as a JSON array. -

- - -

- A TD snippet based on the defined members is given below: -

- 
-        ...
-        "type": "object",
-        "properties": {
-            "status": {
-                "title": "Status",
-                "type": "string",
-                "enum": ["On", "Off", "Error"]
-            },
-            "brightness": {
-                "title": "Brightness value",
-                "type": "number",
-                "minimum": 0.0,
-                "maximum": 100.0
-            },
-            "rgb": {
-                "title": "RGB color value",
-                "type": "array",
-                "items" : {
-                    "type" : "number",
-                    "minimum": 0,
-                    "maximum": 255
-                },
-                "minItems": 3,
-                "maxItems": 3
-            }
-        },
-        ...
-
- -

The terms readOnly and writeOnly MAY be used as hints to signalize which data members are - exchanged for a read request (e.g., read an interaction property) and which one for a write process - (e.g. write an interaction property). -

- -

- An TD snippet with the usage of readOnly and writeOnly is given below: -

-
-    ...
-        "properties": {
-            "status": {
-              "description": "Read or write On/Off status.",
-              "type": "object",
-              "properties": {
-                "latestStatus": {
-                  "type": "string",
-                  "enum": ["On", "Off"],
-                  "readOnly": true
-                },
-                "newStatusValue": {
-                  "type": "string",
-                  "enum": ["On", "Off"],
-                  "writeOnly": true
-                }
-              },
-              forms:[...]
-            }
-          }
-    ...
-
-

If the interaction property status is read, the status data is returned using latestStatus in the payload. - To manipulate the status of the interaction property, the new value must be provided by assigning newStatusValue in - the payload. -

- -

As an additional feature, a Thing Description instance allows the usage of the term unit within data schema definitions. - This can be used to associates some - unit information to some data members. The unit values can be - free selected, however, it is recommended to select units based on existing definitions by integrating - the corresponding namespace context (e.g., from Smart Appliances REFerence (SAREF) ontology or Ontology of units of Measure (OM)). -

- -
-    {
-    "@context": ["http://www.w3.org/ns/td",
-                {"om": "http://www.wurvoc.org/vocabularies/om-1.8/"}],
-    ...
-    "properties": {
-        "latestValues": {
-            "description": "Provides all current values of the weather station.",
-            "type": "object",
-            "properties": {
-            "temperature": {
-                "type": "number",
-                "minimum" : -32.5,
-                "maximum" : -55.2,
-                "unit": "om:degree_Celsius"
-            },
-            "humidity": {
-                "type": "number",
-                "minimum" : 0,
-                "maximum" : 100,
-                "unit": "om:percent"
-            }
-            },
-            forms:[...]
-        }
-    }
-    ...
-
- - - - -
- - -
-

titles and descriptions

- -

The vocabulary terms titles and descriptions enables human-readable text description in multi-languages using - language tags described in [[!BCP47]]. - - Whenever the vocabulary terms titles and descriptions can be used, both MUST be serialized as JSON Object. The member names of the JSON Object MUST be - the language tags as defined in [[!BCP47]] (e.g., "en", "de", "ja", "zh-Hans", "zh-Hant"). The value of each member MUST be serialized as JSON string. - -

- -

A TD snippet using titles and descriptions in different levels is given below:

- - 
-                    {
-                        "name": "MyThing",
-                        "descriptions": {
-                            "en":"Human readable information.",
-                            "de": "Menschenlesbare Informationen.",
-                            "ja" : "人間が読むことができる情報",
-                            "zh-Hans" : "人们可阅读的信息", 
-                            "zh-Hant" : "人們可閱讀的資訊"
-                        },
-                        ...
-                        "properties": {
-                            "on": {
-                                "titles": {
-                                    "en": "On/Off",
-                                    "de": "An/Aus",
-                                    "ja": "オンオフ",
-                                    "zh-Hans": "开关",
-                                    "zh-Hant": "開關" },
-                                "type": "boolean",
-                                "forms": [...]
-                            },
-                            "status": {
-                                "titles": {
-                                    "en": "Status",
-                                    "de": "Zustand",
-                                    "ja": "状態",
-                                    "zh-Hans": "状态",
-                                    "zh-Hant": "狀態" },
-                                "type": "object",
-                                ...
-                    }
-
- -

TD instances may also additional use title and description beside of titles and descriptions. - - If title and titles description and descriptions are defined at the same time at the JSON level, - title and description MAY be seen as default text. - - -

- - 
-            {
-                "name": "MyThing",
-                "description": "Menschenlesbare Informationen.",
-                "descriptions": {
-                    "en":"Human readable information.",
-                    "de": "Menschenlesbare Informationen.",
-                    "ja" : "人間が読むことができる情報",
-                    "zh-Hans" : "人们可阅读的信息", 
-                    "zh-Hant" : "人們可閱讀的資訊"
-                },
-                ...
-                "properties": {
-                    "on": {
-                        "title" : "An/Aus",
-                        "titles": {
-                            "en": "On/Off",
-                            "de": "An/Aus",
-                            "ja": "オンオフ",
-                            "zh-Hans": "开关",
-                            "zh-Hant": "開關" },
-                        "type": "boolean",
-                        "forms": [...]
-                    },
-                    "status": {
-                        "title" : "Zustand",
-                        "titles": {
-                            "en": "Status",
-                            "de": "Zustand",
-                            "ja": "状態",
-                            "zh-Hans": "状态",
-                            "zh-Hant": "狀態" },
-                        "type": "object",
-                        ...
-            }
-
- - -
- - -
- -
-

Context Extension

-

In addition to the standard vocabulary definitions as defined in Section , the Thing Description offers the possibility to add - context knowledge from different namespaces. This mechanism can be used to enrich the content of the Thing Description instances with additional - (e.g., domain specific) semantics. In addition, it can also be used to specify some configurations and behaviors of the underlying communication - protocols announced in the forms field. -

- For this extension the Thing Description uses the @context mechanism known from JSON-LD [[json-ld11]]. The usage and serialization of the @context - within the Thing Description is specified in Section . -

- -

-When adding additional vocabulary to a Thing Description instance, it is recommended that these vocabulary be linked to a namespace context that is within -the JSON name @context container is specified. -

- -

-If included namespaces are based on class definitions such as those provided by the RDF Schema or OWL, the Things Description also allows the use of - @type known from JSON-LD [[json-ld11]] to associate the affiliation to a class. -

- - -
-        {
-            "@context": [
-                "http://www.w3.org/ns/td",
-                {"om": "http://www.wurvoc.org/vocabularies/om-1.8/"},
-                {"saref": "https://w3id.org/saref#"}
-            ],
-            "@type": "Thing",
-            ...
-            "properties": {
-                "Temperature": {
-                    "@type": "saref:Temperature",
-                    "description": "Temperature value of the weather station",
-                    "om:unit_of_measure": "om:degree_Celsius",
-                    "readOnly": true,
-                    "observable": true,
-                    "writeOnly": false,
-                    "type": "number",
-                    "forms" : [...]
-                },
-                ...
-            }
-        }
-
- -

- With the context extension in the Thing Description, communication metadata can be supplemented or specified in the declarations forms. - This is useful when default assumptions as defined in [[[!WOT-PROTOCOL-BINDING]]] need to be overwritten.

- -

The following example shows - a property "brightness" that offers a read, write, and observe operation within the forms declaration. -

- - - -

For the read operation, the corresponding form declaration follows the default assumption to execute an HTTP GET as defined - in [[[!WOT-PROTOCOL-BINDING]]]. The write operation overwrites the default assumption (= HTTP PUT) and - declares with the context extension the HTTP POST method to be used for this operation. In order to observe this property, the - context extension is used here to announce that an HTTP GET is always running to follow the long poll mechanism. -

- -
- -
-

Media Type

- -

- The JSON-based serialization of the TD is identified by - the media type [[!IANA-MEDIA-TYPES]] application/td+json. -

- -

- CoAP-based WoT implementations can use the experimental Content-Format - 65100 until a proper identifier has been registered. -

- -

- The media type application/td+json - MUST be also associated with the JSON-LD context - http://www.w3.org/ns/td. - - That means that this media type can also be used for contextual - identification of the vocabulary within a (simplified) TD instance - that may omit the @context name term. -

- -

- Neither the application/td+json content type nor - a CoAP Content-Format identifier have been registered with IANA yet. -

- -
- -
- -
-

Behavioral Constraints

-

- 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 must in particular may be used to describe pre-existing network interfaces. - In these cases, assertions cannot be made that constrain the behaviour of such - pre-existing interfaces. Instead, the assertions must be interpreted as - constraints on the TD to accurately represent such interfaces. -

-
-

Security Behavior

-

- To enable secure interoperation, - security configurations must accurately reflect the requirements of the Thing: -

    -
  • - - If a Thing requires a specific access mechanism for a resource, that - mechanism MUST be specified in the Thing Description's security scheme configuration - for that resource. - -
    • -
  • - - If a Thing does not require a specific access mechanism for a resource, that - mechanism MUST NOT be specified in the Thing Description's security scheme configuration - for that resource. - -
    • -
- 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 - then the Thing Description is to be considered invalid. -

-
-
-

Data Constraints

-

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, clients should -follow the data schemas strictly, not generating anything not given -in the WoT Thing Description, but should accept additional data from -the server not given explicitly in the WoT Thing Decription for that -server. In general, servers are described by WoT Thing Descriptions, -but clients are constrained to follow WoT Thing Descriptions when -interacting with servers. -

    -
  • - -A WoT Thing acting as a client when interacting with another target Thing -described in a WoT Thing Description MUST generate data -organized according to the data schemas given in the corresponding -interactions. - -
    • -
  • - -A WoT Thing Description describing a server MUST accurately describe the -data returned and accepted by each interaction. - -
    • -
  • - -A WoT Thing acting as a server MAY return additional data from an interaction -even when such data is -not described in the data schemas given in the target Thing's WoT Thing Description. - -
    • -
  • - -A WoT Thing acting as a client when interacting with another Thing MUST accept without -error any additional data -not described in the data schemas given in the target Thing's WoT Thing Description. - -
    • -
  • - -A WoT Thing acting as a client when interacting with another Thing MUST NOT generate data -not described in the data schemas given in that Thing's WoT Thing Description. - -
    • -
  • - -A WoT Thing acting as a client when interacting with another Thing MUST generate URIs -according to the URI templates, base URLs, and form href parameters -given in the target Thing's WoT Thing Description. - -
    • -
  • - -URI templates, base URLs, and form href parameters -in a WoT Thing Description MUST accurately describe URIs -returned by a target Thing acting as a server. - -
    • -
-

-
-
- -
-

Example Thing Description Instances

- -
-

MyLampThing Example with CoAP Binding

- -

Feature list of the Thing:

- -
    -
  • Name: MyLampThing
    • -
  • Context extension: none
    • -
  • Offered interactions: 1 property, 1 action, 1 event
    • -
  • Security: PSKSecurityScheme
    • -
  • Protocol binding: CoAP [[?RFC7252]] over TLS
    • -
  • Serializiation: default (JSON)
    • -
  • Comment: none
    • - -
- -
-{
-    "id": "urn:dev:wot:com:example:servient:lamp",
-    "name": "MyLampThing",
-    "description" : "MyLampThing uses JSON serialization",
-    "securityDefinitions": {"psk_sc":{"scheme": "psk"}},
-    "security": ["psk_sc"],
-    "properties": {
-        "status": {
-            "description" : "Shows the current status of the lamp",
-            "type": "string",
-            "forms": [{
-                "href": "coaps://mylamp.example.com/status"
-            }]
-        }
-    },
-    "actions": {
-        "toggle": {
-            "description" : "Turn on or off the lamp",
-            "forms": [{
-                "href": "coaps://mylamp.example.com/toggle"
-            }]
-        }
-    },
-    "events": {
-        "overheating": {
-            "description" : "Lamp reaches a critical temperature (overheating)",
-            "data": {"type": "string"},
-            "forms": [{
-                "href": "coaps://mylamp.example.com/oh"
-            }]
-        }
-    }
-}
-
-
- -
-

MyLightSensor Example with MQTT Binding

- -

Feature list of the Thing:

- -
    -
  • Name: MyLightSensor
    • -
  • Context extension: none
    • -
  • Offered interactions: 1 event
    • -
  • Security: none
    • -
  • Protocol binding: MQTT [[?MQTT]]
    • -
  • Serializiation: text
    • -
  • Comment: An MQTT client frequently publishes the light sensor data (number is serialized in text format) to - the topic /lightSensor by the MQTT broker running behind the address 192.168.1.187:1883.
    • -
- -
-        {
-            "name": "MyLightSensor",
-            "id": "urn:dev:wot:com:example:servient:lightsensor",
-            "securityDefinitions": {"nosec_sc": {"scheme": "nosec"}},
-            "security": ["nosec_sc"],
-            "events": {
-                "lightSensor": {
-                    "data":{"type": "integer"},
-                    "forms": [
-                        {
-                            "href": "mqtt://192.168.1.187:1883/lightSensor",
-                            "contentType" : "text/plain"
-                        }
-                    ]
-                }
-            } 
-        }
-
-
- - -
-

Thing-2-Thing (T2T) Event Example

- -

Feature list of the Thing:

- -
    -
  • Name: TemperatureForT2T
    • -
  • Context extension: include HTTP (by htv prefix) vocabulary set
    • -
  • Offered interactions: 1 event
    • -
  • Security: none
    • -
  • Protocol binding: HTTP
    • -
  • Serializiation: default (JSON)
    • -
  • Comment: TemperatureForT2T Thing provides an event temperatureValueForT2T, with which an instruction can be passed, to which other Thing the periodically provided temperature values are to be sent. - Doing this, the subscription container defines an input to which target URL the temperature value (defined within the data container) - has to be sent. To submit such information, a client must call the resource http://192.168.0.124:8080/events/TempForT2T/subscribe (via the POST method) and - provide the target URL information in the payload (JSON serialization). As defined in the output container, - the TemperatureForT2T Thing would response with a subscription ID that can be used, e.g., for cancellation the subscription (as defined in the cancellation - container). -
    • -
- - 
-        {
-            "@context": [
-                "http://www.w3.org/ns/td",
-                {"htv": "http://www.w3.org/2011/http#"}],
-            "id": "urn:dev:wot:org:eclipse:thingweb:event-example",
-            "name": "TemperatureForT2T",
-            "description": "Event with subscription / cancellation (Thing-2-Thing use case).",
-            "securityDefinitions": {"nosec_sc": {"scheme": "nosec"}},
-            "security": ["nosec_sc"],
-            "events": {
-                "temperatureValueForT2T": {
-                    "description": "Provides periodic temperature values as event affordance.",
-                    "subscription": {
-                        "input": {
-                            "targetURL": {
-                                "type": "string",
-                                "format": "uri",
-                                "description": "Requester provides target URL to initate T2T."
-                        }},
-                        "output": {
-                            "subscriptionID": {
-                                "type": "integer",
-                                "description": "Responses an unique subscription ID."
-                        }}
-                    },
-                    "data": {
-                        "type": "number",
-                        "description": "Actual temperature value that is sent to the target URL. "
-                    },
-                    "cancellation": {
-                        "input": {
-                            "subscriptionID": {
-                                "type": "integer",
-                                "writeOnly": true,
-                                "description": "Provide subscription ID that have to be cancelled."
-                    }}},
-                    "forms": [
-                        {
-                            "href": "http://192.168.0.124:8080/events/TempForT2T/subscribe",
-                            "op": ["subscribeevent"],
-                            "htv:methodName": "POST",
-                            "contentType": "application/json"
-                        },
-                        {
-                            "href": "http://192.168.0.124:8080/events/TempForT2T/unsubscribeevent",
-                            "op": ["unsubscribeevent"],
-                            "htv:methodName": "PUT",
-                            "contentType": "application/json"
-                        }
-                    ]
-            }}
-        }
-
-
- -
- -
-

Security and Privacy Considerations

- -

- In general the security measures taken to protect a WoT - system will depend on the threats and attackers that system - may face and the value of the assets needs to protect. - A detailed discussion of security and privacy considerations for the Web of Things, - including a threat model that can be adapted to various circumstances, is - presented in the informative document [[!WOT-SECURITY-CONSIDERATIONS]]. - This section discusses only security and privacy risks - and possible mitigations directly relevant to the WoT Thing Description. -

-

A WoT Thing Description can describe both secure and - insecure network interfaces. When a Thing Description is - retro-fitted to an existing network interface, no change in the - security status of the network interface is to be expected. -

-

- When designing new devices and services for use with the WoT, - we have documented a suggested set of best practices - in [[!WOT-SECURITY-BEST-PRACTICES]] to improve security. - This best-practices document may be updated as security measures evolve. - Following these practices does not guarantee security, - but it at least will help to avoid common known vulnerabilities. -

-

The use of a WoT Thing Description introduces - the security and privacy risks given in the following sections. - After each risk, we suggest some possible mitigations. -

-
-
Context Dereferencing Privacy Risk
-

Deferencing the vocabulary files given in the @context - member of any JSON-LD [[json-ld11]] document can be a privacy risk. - In the case of the WoT, an attacker can observe the network - traffic produced by such deferences and can use the metadata - of the dereference, such as the destination IP address, - to infer information about the device especially if domain-specific - vocabularies are used. This is a risk even if the connection - is encrypted, and is related to DNS privacy leaks. -

-
Mitigation:
- Avoid actual dereferencing of vocabulary files. - Vocabulary files should be cached whenever possible. - Ideally they would be made immutable, built into the interpreting device, - and not derefenced at all, - with the URI in the @context member serving only as - an identifier of the (known) vocabulary. - This requires the use of strict version control, as updates - should use a new URI to ensure that existing URIs can refer to - immutable data. - Use well-known standard vocabulary files whenever possible to - improve the chances that the context file will be available locally - to systems interpreting the metadata in a Thing Description. -
-
-
-
Immutable Identifiers Privacy Risk
-

The fact that a Thing Description contains a unique - identifier means that should it be associated with - a person it can be used to track that person and - therefore pose a risk to privacy. -

-
Mitigation:
- All identifiers should be mutable, - and there should be a mechanism to update the id - of a Thing. - Specifically, - the id of a Thing should not be fixed in hardware. - This does, however, conflict with the Linked Data ideal that - identifiers are fixed URIs. In many circumstances it - will be acceptable to only allow updates to identifiers if - a Thing is reinitialized. In this case as a software entity the - old Thing ceases to exist and a new Thing is created. - This can be sufficient to break a tracking chain when, for - example, a device is sold to a new owner. - Alternatively, if more frequent changes are desired during - the operational phase of a device, - a mechanism can be put into place to notify only authorized users - of the change in identifier when a change is made. - Note however that some classes of devices, e.g. medical devices, - may require immutable IDs by law in some jurisdictions. - In this case extra attention should be paid to secure - access to files, such as Thing Descriptions, containing such - immutable identifiers. -
-

-
-
-
Fingerprinting 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 a person, through fingerprinting. -

-
Mitigation:
- Only authorized users should be provided access - to the Thing Description for a Thing. - If the TD is only distributed to authorized users - through secure and confidential channels, for - example through a directory service that requires authentication, - the risk can be minimized. -
-
-
-
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 - intermediary that can capture or manipulate data. -

-
Mitigation:
- Obtain Thing Descriptions only through - mutually authenticated channels. - This ensures that the client and the server are both sure of the - identity of the other party to the communication. - This is also necessary in order to deliver TDs only to authorized users. -
-
-
-
Context Interception and Tampering Security Risk
-

Intercepting and tampering with context files can be used to facilitate attacks - 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, - and dereferencing is avoided whenever possible, then this risk can be reduced. -
-
-
-
Inferencing of Personally Identifiable Information Privacy Risk
-

In many locales, in order to protect the privacy of users, - there are legal requirements for the handling of - personally identifiable information, - that is, - information that can be associated with a particular person. - Such information can of course be generated by IoT devices directly. - However, - the existence and metadata of IoT devices - (the kind of data stored in a Thing Description) - can also contain or be used to infer personally identifiable information. - This information can be as simple as the fact that a certain person owns a certain - type of device, - which can lead to additional inferences about that person. -

-
Mitigation:
- 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. - 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 - 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's Thing Description. - As a second example, if we consider a TD to contain personally - identifiable information, then it should not be retained indefinitely - or used for purposes other than those for which consent was given. -
-
- -
- -
-

JSON Schema for TD Instance Validation

-

Below are two JSON Schema [[?JSON-SCHEMA-VALIDATION]] documents (one for the Simple and Full TD representation form) for syntactically validating Thing Description instances serialized in - JSON based format. -

-

The Thing Description defined by this document allows for - adding external vocabularies by using @context mechanism - known from JSON-LD [[json-ld11]], and the terms in those external vocabularies can be - used in addition to the terms defined in Section . - For this reason, the below JSON schema is intentionally non-strict in that - regard. You can replace the value of additionalProperties schema - property true with false in different scopes/levels in - order to perform a stricter validation in case no external vocabularies are used. -

- -
-

JSON Schema for Simple TD Validation

-

- JSON Schema for validating TD instances in Simple form - (checks, if all manditory terms without default values from the TD model are present; also see ). -

- 
-    {
-    "title": "WoT TD Schema - March 2019",
-    "description": "JSON Schema representation of the TD serialisation format. This schema validates a plain JSON TD which doesn't have to contain vocabulary terms defined in 5.1.1",
-    "$schema ": "http://json-schema.org/draft-06/schema#",
-    "type": "object",
-    "properties": {
-        "id": {
-            "type": "string",
-            "format": "uri"
-        },
-        "name": {
-            "type": "string"
-        },
-        "properties": {
-            "type": "object",
-            "additionalProperties": {
-                "$ref": "#/definitions/property_element"
-            }
-        },
-        "actions": {
-            "type": "object",
-            "additionalProperties": {
-                "$ref": "#/definitions/action_element"
-            }
-        },
-        "events": {
-            "type": "object",
-            "additionalProperties": {
-                "$ref": "#/definitions/event_element"
-            }
-        },
-        "description": {
-            "$ref": "#/definitions/description"
-        },
-        "descriptions": {
-            "$ref": "#/definitions/descriptions"
-        },
-        "version": {
-            "type": "object",
-            "properties": {
-                "instance": {
-                    "type": "string"
-                }
-            },
-            "required": [
-                "instance"
-            ]
-        },
-        "links": {
-            "type": "array",
-            "items": {
-                "$ref": "#/definitions/link_element"
-            }
-        },
-        "forms": {
-            "type": "array",
-            "minItems": 1,
-            "items": {
-                "$ref": "#/definitions/form_element_root"
-            }
-        },
-        "base": {
-            "$ref": "#/definitions/url"
-        },
-        "securityDefinitions": {
-            "type": "object",
-            "minProperties": 1,
-            "additionalProperties": {
-                "$ref": "#/definitions/securityScheme"
-            }
-        },
-        "support": {
-            "type": "string"
-        },
-        "created": {
-            "type": "string"
-        },
-        "lastModified": {
-            "type": "string"
-        },
-        "security": {
-            "type": "array",
-            "minItems": 1,
-            "items": {
-                "type": "string"
-            }
-        },
-        "@type": {
-            "$ref": "#/definitions/type_declaration"
-        },
-        "@context": {
-            "$ref": "#/definitions/thing-context"
-        }
-    },
-    "required": [
-        "name",
-        "id",
-        "security",
-        "securityDefinitions"
-    ],
-    "additionalProperties": true,
-    "definitions": {
-        "thing-context": {
-            "oneOf": [{
-                    "type": "array",
-                    "items": {
-                        "anyOf": [{
-                                "$ref": "#/definitions/url"
-                            },
-                            {
-                                "type": "object"
-                            }
-                        ]
-                    },
-                    "contains": {
-                        "type": "string",
-                        "enum": [
-                            "http://www.w3.org/ns/td", "http://w3.org/ns/td"
-                        ]
-                    }
-                },
-                {
-                    "type": "string",
-                    "enum": [
-                        "http://www.w3.org/ns/td", "http://w3.org/ns/td"
-                    ]
-                }
-            ]
-        },
-        "security-context": {
-            "oneOf": [{
-                    "type": "array",
-                    "items": {
-                        "anyOf": [{
-                                "$ref": "#/definitions/url"
-                            },
-                            {
-                                "type": "object"
-                            }
-                        ]
-                    },
-                    "contains": {
-                        "type": "string",
-                        "enum": [
-                            "https://www.w3.org/ns/wot-security", "https://w3.org/ns/wot-security"
-                        ]
-                    }
-                },
-                {
-                    "type": "string",
-                    "enum": [
-                        "https://www.w3.org/ns/wot-security", "https://w3.org/ns/wot-security"
-                    ]
-                }
-            ]
-        },
-        "data-context": {
-            "oneOf": [{
-                    "type": "array",
-                    "items": {
-                        "anyOf": [{
-                                "$ref": "#/definitions/url"
-                            },
-                            {
-                                "type": "object"
-                            }
-                        ]
-                    },
-                    "contains": {
-                        "type": "string",
-                        "enum": [
-                            "https://www.w3.org/ns/json-schema", "https://w3.org/ns/json-schema"
-                        ]
-                    }
-                },
-                {
-                    "type": "string",
-                    "enum": [
-                        "https://www.w3.org/ns/json-schema", "https://w3.org/ns/json-schema"
-                    ]
-                }
-            ]
-        },
-        "type_declaration": {
-            "oneOf": [{
-                    "type": "string"
-                },
-                {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                }
-            ]
-        },
-        "property_element": {
-            "type": "object",
-            "properties": {
-                "@context": {
-                    "$ref": "#/definitions/data-context"
-                },
-                "@type": {
-                    "$ref": "#/definitions/type_declaration"
-                },
-                "description": {
-                    "$ref": "#/definitions/description"
-                },
-                "title": {
-                    "$ref": "#/definitions/title"
-                },
-                "descriptions": {
-                    "$ref": "#/definitions/descriptions"
-                },
-                "titles": {
-                    "$ref": "#/definitions/titles"
-                },
-                "uriVariables": {
-                    "type": "object",
-                    "additionalProperties": {
-                        "$ref": "#/definitions/dataSchema"
-                    }
-                },
-                "forms": {
-                    "type": "array",
-                    "minItems": 1,
-                    "items": {
-                        "$ref": "#/definitions/form_element_property"
-                    }
-                },
-                "observable": {
-                    "type": "boolean"
-                },
-                "writeOnly": {
-                    "type": "boolean"
-                },
-                "readOnly": {
-                    "type": "boolean"
-                },
-                "oneOf": {
-                    "type": "array",
-                    "items": {
-                        "$ref": "#/definitions/dataSchema"
-                    }
-                },
-                "unit": {
-                    "type": "string"
-                },
-                "enum": {
-                    "type": "array",
-                    "minItems": 1,
-                    "uniqueItems": true
-                },
-                "format": {
-                    "type": "string"
-                },
-                "const": {},
-                "type": {
-                    "type": "string",
-                    "enum": [
-                        "boolean",
-                        "integer",
-                        "number",
-                        "string",
-                        "object",
-                        "array",
-                        "null"
-                    ]
-                },
-                "items": {
-                    "oneOf": [{
-                            "$ref": "#/definitions/dataSchema"
-                        },
-                        {
-                            "type": "array",
-                            "items": {
-                                "$ref": "#/definitions/dataSchema"
-                            }
-                        }
-                    ]
-                },
-                "maxItems": {
-                    "type": "integer",
-                    "minimum": 0
-                },
-                "minItems": {
-                    "type": "integer",
-                    "minimum": 0
-                },
-                "minimum": {
-                    "type": "number"
-                },
-                "maximum": {
-                    "type": "number"
-                },
-                "properties": {
-                    "additionalProperties": {
-                        "$ref": "#/definitions/dataSchema"
-                    }
-                },
-                "required": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                }
-            },
-            "required": [
-                "forms"
-            ],
-            "additionalProperties": true
-        },
-        "action_element": {
-            "type": "object",
-            "properties": {
-                "description": {
-                    "type": "string"
-                },
-                "descriptions": {
-                    "$ref": "#/definitions/descriptions"
-                },
-                "title": {
-                    "type": "string"
-                },
-                "titles": {
-                    "$ref": "#/definitions/titles"
-                },
-                "uriVariables": {
-                    "type": "object",
-                    "additionalProperties": {
-                        "$ref": "#/definitions/dataSchema"
-                    }
-                },
-                "@type": {
-                    "$ref": "#/definitions/type_declaration"
-                },
-                "forms": {
-                    "type": "array",
-                    "minItems": 1,
-                    "items": {
-                        "$ref": "#/definitions/form_element_action"
-                    }
-                },
-                "input": {
-                    "$ref": "#/definitions/dataSchema"
-                },
-                "output": {
-                    "$ref": "#/definitions/dataSchema"
-                },
-                "safe": {
-                    "type": "boolean"
-                },
-                "idempotent": {
-                    "type": "boolean"
-                }
-            },
-            "required": [
-                "forms"
-            ],
-            "additionalProperties": true
-        },
-        "event_element": {
-            "type": "object",
-            "properties": {
-                "description": {
-                    "type": "string"
-                },
-                "title": {
-                    "type": "string"
-                },
-                "descriptions": {
-                    "$ref": "#/definitions/descriptions"
-                },
-                "titles": {
-                    "$ref": "#/definitions/titles"
-                },
-                "uriVariables": {
-                    "type": "object",
-                    "additionalProperties": {
-                        "$ref": "#/definitions/dataSchema"
-                    }
-                },
-                "@type": {
-                    "$ref": "#/definitions/type_declaration"
-                },
-                "forms": {
-                    "type": "array",
-                    "minItems": 1,
-                    "items": {
-                        "$ref": "#/definitions/form_element_event"
-                    }
-                },
-                "subscription": {
-                    "$ref": "#/definitions/dataSchema"
-                },
-                "data": {
-                    "$ref": "#/definitions/dataSchema"
-                },
-                "cancellation": {
-                    "$ref": "#/definitions/dataSchema"
-                },
-                "type": {
-                    "not": {}
-                },
-                "enum": {
-                    "not": {}
-                },
-                "const": {
-                    "not": {}
-                }
-            },
-            "required": [
-                "forms"
-            ],
-            "additionalProperties": true
-        },
-        "form_element_property": {
-            "type": "object",
-            "properties": {
-                "href": {
-                    "$ref": "#/definitions/url"
-                },
-                "op": {
-                    "oneOf": [{
-                            "type": "string",
-                            "enum": [
-                                "readproperty",
-                                "writeproperty",
-                                "observeproperty",
-                                "unobserveproperty"
-                            ]
-                        },
-                        {
-                            "type": "array",
-                            "items": {
-                                "type": "string",
-                                "enum": [
-                                    "readproperty",
-                                    "writeproperty",
-                                    "observeproperty",
-                                    "unobserveproperty"
-                                ]
-                            }
-                        }
-                    ]
-                },
-                "contentType": {
-                    "type": "string"
-                },
-                "security": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                },
-                "scopes": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                },
-                "subProtocol": {
-                    "type": "string",
-                    "enum": [
-                        "longpoll",
-                        "websub",
-                        "sse"
-                    ]
-                },
-                "response": {
-                    "type": "object",
-                    "properties": {
-                        "contentType": {
-                            "type": "string"
-                        }
-                    }
-                }
-            },
-            "required": [
-                "href"
-            ],
-            "additionalProperties": true
-        },
-        "form_element_action": {
-            "type": "object",
-            "properties": {
-                "href": {
-                    "$ref": "#/definitions/url"
-                },
-                "op": {
-                    "oneOf": [{
-                            "type": "string",
-                            "enum": [
-                                "invokeaction"
-                            ]
-                        },
-                        {
-                            "type": "array",
-                            "items": {
-                                "type": "string",
-                                "enum": [
-                                    "invokeaction"
-                                ]
-                            }
-                        }
-                    ]
-                },
-                "contentType": {
-                    "type": "string"
-                },
-                "security": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                },
-                "scopes": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                },
-                "subProtocol": {
-                    "type": "string",
-                    "enum": [
-                        "longpoll",
-                        "websub",
-                        "sse"
-                    ]
-                },
-                "response": {
-                    "type": "object",
-                    "properties": {
-                        "contentType": {
-                            "type": "string"
-                        }
-                    }
-                }
-            },
-            "required": [
-                "href"
-            ],
-            "additionalProperties": true
-        },
-        "form_element_event": {
-            "type": "object",
-            "properties": {
-                "href": {
-                    "$ref": "#/definitions/url"
-                },
-                "op": {
-                    "oneOf": [{
-                            "type": "string",
-                            "enum": [
-                                "subscribeevent",
-                                "unsubscribeevent"
-                            ]
-                        },
-                        {
-                            "type": "array",
-                            "items": {
-                                "type": "string",
-                                "enum": [
-                                    "subscribeevent",
-                                    "unsubscribeevent"
-                                ]
-                            }
-                        }
-                    ]
-                },
-                "contentType": {
-                    "type": "string"
-                },
-                "security": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                },
-                "scopes": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                },
-                "subProtocol": {
-                    "type": "string",
-                    "enum": [
-                        "longpoll",
-                        "websub",
-                        "sse"
-                    ]
-                },
-                "response": {
-                    "type": "object",
-                    "properties": {
-                        "contentType": {
-                            "type": "string"
-                        }
-                    }
-                }
-            },
-            "required": [
-                "href"
-            ],
-            "additionalProperties": true
-        },
-        "form_element_root": {
-            "type": "object",
-            "properties": {
-                "href": {
-                    "$ref": "#/definitions/url"
-                },
-                "op": {
-                    "oneOf": [{
-                            "type": "string",
-                            "enum": [
-                                "readallproperties",
-                                "writeallproperties",
-                                "readmultipleproperties",
-                                "writemultipleproperties"
-                            ]
-                        },
-                        {
-                            "type": "array",
-                            "items": {
-                                "type": "string",
-                                "enum": [
-                                    "readallproperties",
-                                    "writeallproperties",
-                                    "readmultipleproperties",
-                                    "writemultipleproperties"
-                                ]
-                            }
-                        }
-                    ]
-                },
-                "contentType": {
-                    "type": "string"
-                },
-                "security": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                },
-                "scopes": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                },
-                "subProtocol": {
-                    "type": "string",
-                    "enum": [
-                        "longpoll",
-                        "websub",
-                        "sse"
-                    ]
-                },
-                "response": {
-                    "type": "object",
-                    "properties": {
-                        "contentType": {
-                            "type": "string"
-                        }
-                    }
-                }
-            },
-            "required": [
-                "href"
-            ],
-            "additionalProperties": true
-        },
-        "description": {
-            "type": "string"
-        },
-        "title": {
-            "type": "string"
-        },
-        "descriptions": {
-            "type": "object"
-        },
-        "titles": {
-            "type": "object"
-        },
-        "dataSchema": {
-            "type": "object",
-            "properties": {
-                "@type": {
-                    "$ref": "#/definitions/type_declaration"
-                },
-                "description": {
-                    "$ref": "#/definitions/description"
-                },
-                "title": {
-                    "$ref": "#/definitions/title"
-                },
-                "descriptions": {
-                    "$ref": "#/definitions/descriptions"
-                },
-                "titles": {
-                    "$ref": "#/definitions/titles"
-                },
-                "writeOnly": {
-                    "type": "boolean"
-                },
-                "readOnly": {
-                    "type": "boolean"
-                },
-                "oneOf": {
-                    "type": "array",
-                    "items": {
-                        "$ref": "#/definitions/dataSchema"
-                    }
-                },
-                "unit": {
-                    "type": "string"
-                },
-                "enum": {
-                    "type": "array",
-                    "minItems": 1,
-                    "uniqueItems": true
-                },
-                "format": {
-                    "type": "string"
-                },
-                "const": {},
-                "type": {
-                    "type": "string",
-                    "enum": [
-                        "boolean",
-                        "integer",
-                        "number",
-                        "string",
-                        "object",
-                        "array",
-                        "null"
-                    ]
-                },
-                "items": {
-                    "oneOf": [{
-                            "$ref": "#/definitions/dataSchema"
-                        },
-                        {
-                            "type": "array",
-                            "items": {
-                                "$ref": "#/definitions/dataSchema"
-                            }
-                        }
-                    ]
-                },
-                "maxItems": {
-                    "type": "integer",
-                    "minimum": 0
-                },
-                "minItems": {
-                    "type": "integer",
-                    "minimum": 0
-                },
-                "minimum": {
-                    "type": "number"
-                },
-                "maximum": {
-                    "type": "number"
-                },
-                "properties": {
-                    "additionalProperties": {
-                        "$ref": "#/definitions/dataSchema"
-                    }
-                },
-                "required": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                }
-            }
-        },
-        "link_element": {
-            "type": "object",
-            "properties": {
-                "anchor": {
-                    "$ref": "#/definitions/url"
-                },
-                "href": {
-                    "$ref": "#/definitions/url"
-                },
-                "rel": {
-                    "type": "string"
-                },
-                "type": {
-                    "type": "string"
-                }
-            },
-            "required": [
-                "href"
-            ],
-            "additionalProperties": true
-        },
-        "securityScheme": {
-            "oneOf": [{
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "nosec"
-                            ]
-                        }
-                    },
-                    "required": [
-                        "scheme"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "basic"
-                            ]
-                        },
-                        "in": {
-                            "type": "string",
-                            "enum": ["header", "query", "body", "cookie"]
-                        },
-                        "name": {
-                            "type": "string"
-                        }
-                    },
-                    "required": [
-                        "scheme"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "cert"
-                            ]
-                        },
-                        "identity": {
-                            "type": "string"
-                        }
-                    },
-                    "required": [
-                        "scheme"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "digest"
-                            ]
-                        },
-                        "qop": {
-                            "type": "string",
-                            "enum": ["auth", "auth-int"]
-                        },
-                        "in": {
-                            "type": "string",
-                            "enum": ["header", "query", "body", "cookie"]
-                        },
-                        "name": {
-                            "type": "string"
-                        }
-                    },
-                    "required": [
-                        "scheme"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "bearer"
-                            ]
-                        },
-                        "authorization": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "alg": {
-                            "type": "string",
-                            "enum": ["MD5", "ES256", "ES512-256"]
-                        },
-                        "format": {
-                            "type": "string",
-                            "enum": ["jwt", "jwe", "jws"]
-                        },
-                        "in": {
-                            "type": "string",
-                            "enum": ["header", "query", "body", "cookie"]
-                        },
-                        "name": {
-                            "type": "string"
-                        }
-                    },
-                    "required": [
-                        "scheme"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "psk"
-                            ]
-                        },
-                        "identity": {
-                            "type": "string"
-                        }
-                    },
-                    "required": [
-                        "scheme"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "public"
-                            ]
-                        },
-                        "identity": {
-                            "type": "string"
-                        }
-                    },
-                    "required": [
-                        "scheme"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "oauth2"
-                            ]
-                        },
-                        "authorization": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "token": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "refresh": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scopes": {
-                            "type": "array",
-                            "items": {
-                                "type": "string"
-                            }
-                        },
-                        "flow": {
-                            "type": "string",
-                            "enum": ["implicit", "password", "client", "code"]
-                        }
-                    },
-                    "required": [
-                        "scheme"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "apikey"
-                            ]
-                        },
-                        "in": {
-                            "type": "string",
-                            "enum": ["header", "query", "body", "cookie"]
-                        },
-                        "name": {
-                            "type": "string"
-                        }
-                    },
-                    "required": [
-                        "scheme"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "pop"
-                            ]
-                        },
-                        "authorization": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "format": {
-                            "type": "string",
-                            "enum": ["jwt", "jwe", "jws"]
-                        },
-                        "alg": {
-                            "type": "string",
-                            "enum": ["MD5", "ES256", "ES512-256"]
-                        },
-                        "in": {
-                            "type": "string",
-                            "enum": ["header", "query", "body", "cookie"]
-                        },
-                        "name": {
-                            "type": "string"
-                        }
-                    },
-                    "required": [
-                        "scheme"
-                    ]
-                }
-            ]
-        },
-        "url": {
-            "type": "string",
-            "format": "uri-reference"
-        }
-    }
-}
-
-
-
- -
-

JSON Schema for Full TD Validation

-

- JSON Schema for validating TD instances in Full form (checks, if all manditory terms from the TD model are present; also see ). -

- 
-        {
-    "title": "WoT TD Schema - March 2019",
-    "description": "JSON Schema representation of the TD serialisation in JSON-LD format. For a TD to validate this schema it must contain all the term defined in section 5.1.1",
-    "$schema ": "http://json-schema.org/draft-06/schema#",
-    "type": "object",
-    "properties": {
-        "id": {
-            "type": "string",
-            "format": "uri"
-        },
-        "name": {
-            "type": "string"
-        },
-        "properties": {
-            "type": "object",
-            "additionalProperties": {
-                "$ref": "#/definitions/property_element"
-            }
-        },
-        "actions": {
-            "type": "object",
-            "additionalProperties": {
-                "$ref": "#/definitions/action_element"
-            }
-        },
-        "events": {
-            "type": "object",
-            "additionalProperties": {
-                "$ref": "#/definitions/event_element"
-            }
-        },
-        "description": {
-            "$ref": "#/definitions/description"
-        },
-        "descriptions": {
-            "$ref": "#/definitions/descriptions"
-        },
-        "version": {
-            "type": "object",
-            "properties": {
-                "instance": {
-                    "type": "string"
-                }
-            },
-            "required": [
-                "instance"
-            ]
-        },
-        "links": {
-            "type": "array",
-            "items": {
-                "$ref": "#/definitions/link_element"
-            }
-        },
-        "forms": {
-            "type": "array",
-            "minItems": 1,
-            "items": {
-                "$ref": "#/definitions/form_element_root"
-            }
-        },
-        "base": {
-            "$ref": "#/definitions/url"
-        },
-        "securityDefinitions": {
-            "type": "object",
-            "minProperties": 1,
-            "additionalProperties": {
-                "$ref": "#/definitions/securityScheme"
-            }
-        },
-        "support": {
-            "type": "string"
-        },
-        "created": {
-            "type": "string"
-        },
-        "lastModified": {
-            "type": "string"
-        },
-        "security": {
-            "type": "array",
-            "minItems": 1,
-            "items": {
-                "type": "string"
-            }
-        },
-        "@type": {
-            "$ref": "#/definitions/type_declaration"
-        },
-        "@context": {
-            "$ref": "#/definitions/thing-context"
-        }
-    },
-    "required": [
-        "name",
-        "id",
-        "security",
-        "securityDefinitions",
-        "@context"
-    ],
-    "additionalProperties": true,
-    "definitions": {
-        "thing-context": {
-            "oneOf": [{
-                    "type": "array",
-                    "items": {
-                        "anyOf": [{
-                                "$ref": "#/definitions/url"
-                            },
-                            {
-                                "type": "object"
-                            }
-                        ]
-                    },
-                    "contains": {
-                        "type": "string",
-                        "enum": [
-                            "http://www.w3.org/ns/td", "http://w3.org/ns/td"
-                        ]
-                    }
-                },
-                {
-                    "type": "string",
-                    "enum": [
-                        "http://www.w3.org/ns/td", "http://w3.org/ns/td"
-                    ]
-                }
-            ]
-        },
-        "security-context": {
-            "oneOf": [{
-                    "type": "array",
-                    "items": {
-                        "anyOf": [{
-                                "$ref": "#/definitions/url"
-                            },
-                            {
-                                "type": "object"
-                            }
-                        ]
-                    },
-                    "contains": {
-                        "type": "string",
-                        "enum": [
-                            "https://www.w3.org/ns/wot-security", "https://w3.org/ns/wot-security"
-                        ]
-                    }
-                },
-                {
-                    "type": "string",
-                    "enum": [
-                        "https://www.w3.org/ns/wot-security", "https://w3.org/ns/wot-security"
-                    ]
-                }
-            ]
-        },
-        "data-context": {
-            "oneOf": [{
-                    "type": "array",
-                    "items": {
-                        "anyOf": [{
-                                "$ref": "#/definitions/url"
-                            },
-                            {
-                                "type": "object"
-                            }
-                        ]
-                    },
-                    "contains": {
-                        "type": "string",
-                        "enum": [
-                            "https://www.w3.org/ns/json-schema", "https://w3.org/ns/json-schema"
-                        ]
-                    }
-                },
-                {
-                    "type": "string",
-                    "enum": [
-                        "https://www.w3.org/ns/json-schema", "https://w3.org/ns/json-schema"
-                    ]
-                }
-            ]
-        },
-        "type_declaration": {
-            "oneOf": [{
-                    "type": "string"
-                },
-                {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                }
-            ]
-        },
-        "property_element": {
-            "type": "object",
-            "properties": {
-                "@context": {
-                    "$ref": "#/definitions/data-context"
-                },
-                "@type": {
-                    "$ref": "#/definitions/type_declaration"
-                },
-                "description": {
-                    "$ref": "#/definitions/description"
-                },
-                "title": {
-                    "$ref": "#/definitions/title"
-                },
-                "descriptions": {
-                    "$ref": "#/definitions/descriptions"
-                },
-                "titles": {
-                    "$ref": "#/definitions/titles"
-                },
-                "uriVariables": {
-                    "type": "object",
-                    "additionalProperties": {
-                        "$ref": "#/definitions/dataSchema"
-                    }
-                },
-                "forms": {
-                    "type": "array",
-                    "minItems": 1,
-                    "items": {
-                        "$ref": "#/definitions/form_element_property"
-                    }
-                },
-                "observable": {
-                    "type": "boolean"
-                },
-                "writeOnly": {
-                    "type": "boolean"
-                },
-                "readOnly": {
-                    "type": "boolean"
-                },
-                "oneOf": {
-                    "type": "array",
-                    "items": {
-                        "$ref": "#/definitions/dataSchema"
-                    }
-                },
-                "unit": {
-                    "type": "string"
-                },
-                "enum": {
-                    "type": "array",
-                    "minItems": 1,
-                    "uniqueItems": true
-                },
-                "format": {
-                    "type": "string"
-                },
-                "const": {},
-                "type": {
-                    "type": "string",
-                    "enum": [
-                        "boolean",
-                        "integer",
-                        "number",
-                        "string",
-                        "object",
-                        "array",
-                        "null"
-                    ]
-                },
-                "items": {
-                    "oneOf": [{
-                            "$ref": "#/definitions/dataSchema"
-                        },
-                        {
-                            "type": "array",
-                            "items": {
-                                "$ref": "#/definitions/dataSchema"
-                            }
-                        }
-                    ]
-                },
-                "maxItems": {
-                    "type": "integer",
-                    "minimum": 0
-                },
-                "minItems": {
-                    "type": "integer",
-                    "minimum": 0
-                },
-                "minimum": {
-                    "type": "number"
-                },
-                "maximum": {
-                    "type": "number"
-                },
-                "properties": {
-                    "additionalProperties": {
-                        "$ref": "#/definitions/dataSchema"
-                    }
-                },
-                "required": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                }
-            },
-            "required": [
-                "forms",
-                "observable",
-                "writeOnly",
-                "readOnly"
-            ],
-            "additionalProperties": true
-        },
-        "action_element": {
-            "type": "object",
-            "properties": {
-                "description": {
-                    "type": "string"
-                },
-                "descriptions": {
-                    "$ref": "#/definitions/descriptions"
-                },
-                "title": {
-                    "type": "string"
-                },
-                "titles": {
-                    "$ref": "#/definitions/titles"
-                },
-                "uriVariables": {
-                    "type": "object",
-                    "additionalProperties": {
-                        "$ref": "#/definitions/dataSchema"
-                    }
-                },
-                "@type": {
-                    "$ref": "#/definitions/type_declaration"
-                },
-                "forms": {
-                    "type": "array",
-                    "minItems": 1,
-                    "items": {
-                        "$ref": "#/definitions/form_element_action"
-                    }
-                },
-                "input": {
-                    "$ref": "#/definitions/dataSchema"
-                },
-                "output": {
-                    "$ref": "#/definitions/dataSchema"
-                },
-                "safe": {
-                    "type": "boolean"
-                },
-                "idempotent": {
-                    "type": "boolean"
-                }
-            },
-            "required": [
-                "forms", "safe", "idempotent"
-            ],
-            "additionalProperties": true
-        },
-        "event_element": {
-            "type": "object",
-            "properties": {
-                "description": {
-                    "type": "string"
-                },
-                "title": {
-                    "type": "string"
-                },
-                "descriptions": {
-                    "$ref": "#/definitions/descriptions"
-                },
-                "titles": {
-                    "$ref": "#/definitions/titles"
-                },
-                "uriVariables": {
-                    "type": "object",
-                    "additionalProperties": {
-                        "$ref": "#/definitions/dataSchema"
-                    }
-                },
-                "@type": {
-                    "$ref": "#/definitions/type_declaration"
-                },
-                "forms": {
-                    "type": "array",
-                    "minItems": 1,
-                    "items": {
-                        "$ref": "#/definitions/form_element_event"
-                    }
-                },
-                "subscription": {
-                    "$ref": "#/definitions/dataSchema"
-                },
-                "data": {
-                    "$ref": "#/definitions/dataSchema"
-                },
-                "cancellation": {
-                    "$ref": "#/definitions/dataSchema"
-                },
-                "type": {
-                    "not": {}
-                },
-                "enum": {
-                    "not": {}
-                },
-                "const": {
-                    "not": {}
-                }
-            },
-            "required": [
-                "forms"
-            ],
-            "additionalProperties": true
-        },
-        "form_element_property": {
-            "type": "object",
-            "properties": {
-                "href": {
-                    "$ref": "#/definitions/url"
-                },
-                "op": {
-                    "oneOf": [{
-                            "type": "string",
-                            "enum": [
-                                "readproperty",
-                                "writeproperty",
-                                "observeproperty",
-                                "unobserveproperty"
-                            ]
-                        },
-                        {
-                            "type": "array",
-                            "items": {
-                                "type": "string",
-                                "enum": [
-                                    "readproperty",
-                                    "writeproperty",
-                                    "observeproperty",
-                                    "unobserveproperty"
-                                ]
-                            }
-                        }
-                    ]
-                },
-                "contentType": {
-                    "type": "string"
-                },
-                "security": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                },
-                "scopes": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                },
-                "subProtocol": {
-                    "type": "string",
-                    "enum": [
-                        "longpoll",
-                        "websub",
-                        "sse"
-                    ]
-                },
-                "response": {
-                    "type": "object",
-                    "properties": {
-                        "contentType": {
-                            "type": "string"
-                        }
-                    }
-                }
-            },
-            "required": [
-                "href", "contentType"
-            ],
-            "additionalProperties": true
-        },
-        "form_element_action": {
-            "type": "object",
-            "properties": {
-                "href": {
-                    "$ref": "#/definitions/url"
-                },
-                "op": {
-                    "oneOf": [{
-                            "type": "string",
-                            "enum": [
-                                "invokeaction"
-                            ]
-                        },
-                        {
-                            "type": "array",
-                            "items": {
-                                "type": "string",
-                                "enum": [
-                                    "invokeaction"
-                                ]
-                            }
-                        }
-                    ]
-                },
-                "contentType": {
-                    "type": "string"
-                },
-                "security": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                },
-                "scopes": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                },
-                "subProtocol": {
-                    "type": "string",
-                    "enum": [
-                        "longpoll",
-                        "websub",
-                        "sse"
-                    ]
-                },
-                "response": {
-                    "type": "object",
-                    "properties": {
-                        "contentType": {
-                            "type": "string"
-                        }
-                    }
-                }
-            },
-            "required": [
-                "href", "contentType"
-            ],
-            "additionalProperties": true
-        },
-        "form_element_event": {
-            "type": "object",
-            "properties": {
-                "href": {
-                    "$ref": "#/definitions/url"
-                },
-                "op": {
-                    "oneOf": [{
-                            "type": "string",
-                            "enum": [
-                                "subscribeevent",
-                                "unsubscribeevent"
-                            ]
-                        },
-                        {
-                            "type": "array",
-                            "items": {
-                                "type": "string",
-                                "enum": [
-                                    "subscribeevent",
-                                    "unsubscribeevent"
-                                ]
-                            }
-                        }
-                    ]
-                },
-                "contentType": {
-                    "type": "string"
-                },
-                "security": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                },
-                "scopes": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                },
-                "subProtocol": {
-                    "type": "string",
-                    "enum": [
-                        "longpoll",
-                        "websub",
-                        "sse"
-                    ]
-                },
-                "response": {
-                    "type": "object",
-                    "properties": {
-                        "contentType": {
-                            "type": "string"
-                        }
-                    }
-                }
-            },
-            "required": [
-                "href", "contentType"
-            ],
-            "additionalProperties": true
-        },
-        "form_element_root": {
-            "type": "object",
-            "properties": {
-                "href": {
-                    "$ref": "#/definitions/url"
-                },
-                "op": {
-                    "oneOf": [{
-                            "type": "string",
-                            "enum": [
-                                "readallproperties",
-                                "writeallproperties",
-                                "readmultipleproperties",
-                                "writemultipleproperties"
-                            ]
-                        },
-                        {
-                            "type": "array",
-                            "items": {
-                                "type": "string",
-                                "enum": [
-                                    "readallproperties",
-                                    "writeallproperties",
-                                    "readmultipleproperties",
-                                    "writemultipleproperties"
-                                ]
-                            }
-                        }
-                    ]
-                },
-                "contentType": {
-                    "type": "string"
-                },
-                "security": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                },
-                "scopes": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                },
-                "subProtocol": {
-                    "type": "string",
-                    "enum": [
-                        "longpoll",
-                        "websub",
-                        "sse"
-                    ]
-                },
-                "response": {
-                    "type": "object",
-                    "properties": {
-                        "contentType": {
-                            "type": "string"
-                        }
-                    }
-                }
-            },
-            "required": [
-                "href", "contentType"
-            ],
-            "additionalProperties": true
-        },
-        "description": {
-            "type": "string"
-        },
-        "title": {
-            "type": "string"
-        },
-        "descriptions": {
-            "type": "object"
-        },
-        "titles": {
-            "type": "object"
-        },
-        "dataSchema": {
-            "type": "object",
-            "properties": {
-                "@type": {
-                    "$ref": "#/definitions/type_declaration"
-                },
-                "description": {
-                    "$ref": "#/definitions/description"
-                },
-                "title": {
-                    "$ref": "#/definitions/title"
-                },
-                "descriptions": {
-                    "$ref": "#/definitions/descriptions"
-                },
-                "titles": {
-                    "$ref": "#/definitions/titles"
-                },
-                "writeOnly": {
-                    "type": "boolean"
-                },
-                "readOnly": {
-                    "type": "boolean"
-                },
-                "oneOf": {
-                    "type": "array",
-                    "items": {
-                        "$ref": "#/definitions/dataSchema"
-                    }
-                },
-                "unit": {
-                    "type": "string"
-                },
-                "enum": {
-                    "type": "array",
-                    "minItems": 1,
-                    "uniqueItems": true
-                },
-                "format": {
-                    "type": "string"
-                },
-                "const": {},
-                "type": {
-                    "type": "string",
-                    "enum": [
-                        "boolean",
-                        "integer",
-                        "number",
-                        "string",
-                        "object",
-                        "array",
-                        "null"
-                    ]
-                },
-                "items": {
-                    "oneOf": [{
-                            "$ref": "#/definitions/dataSchema"
-                        },
-                        {
-                            "type": "array",
-                            "items": {
-                                "$ref": "#/definitions/dataSchema"
-                            }
-                        }
-                    ]
-                },
-                "maxItems": {
-                    "type": "integer",
-                    "minimum": 0
-                },
-                "minItems": {
-                    "type": "integer",
-                    "minimum": 0
-                },
-                "minimum": {
-                    "type": "number"
-                },
-                "maximum": {
-                    "type": "number"
-                },
-                "properties": {
-                    "additionalProperties": {
-                        "$ref": "#/definitions/dataSchema"
-                    }
-                },
-                "required": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                }
-            }
-        },
-        "link_element": {
-            "type": "object",
-            "properties": {
-                "anchor": {
-                    "$ref": "#/definitions/url"
-                },
-                "href": {
-                    "$ref": "#/definitions/url"
-                },
-                "rel": {
-                    "type": "string"
-                },
-                "type": {
-                    "type": "string"
-                }
-            },
-            "required": [
-                "href"
-            ],
-            "additionalProperties": true
-        },
-        "securityScheme": {
-            "oneOf": [{
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "nosec"
-                            ]
-                        }
-                    },
-                    "required": [
-                        "scheme"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "basic"
-                            ]
-                        },
-                        "in": {
-                            "type": "string",
-                            "enum": ["header", "query", "body", "cookie"]
-                        },
-                        "name": {
-                            "type": "string"
-                        }
-                    },
-                    "required": [
-                        "scheme", "in"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "cert"
-                            ]
-                        },
-                        "identity": {
-                            "type": "string"
-                        }
-                    },
-                    "required": [
-                        "scheme"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "digest"
-                            ]
-                        },
-                        "qop": {
-                            "type": "string",
-                            "enum": ["auth", "auth-int"]
-                        },
-                        "in": {
-                            "type": "string",
-                            "enum": ["header", "query", "body", "cookie"]
-                        },
-                        "name": {
-                            "type": "string"
-                        }
-                    },
-                    "required": [
-                        "scheme", "qop", "in"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "bearer"
-                            ]
-                        },
-                        "authorization": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "alg": {
-                            "type": "string",
-                            "enum": ["MD5", "ES256", "ES512-256"]
-                        },
-                        "format": {
-                            "type": "string",
-                            "enum": ["jwt", "jwe", "jws"]
-                        },
-                        "in": {
-                            "type": "string",
-                            "enum": ["header", "query", "body", "cookie"]
-                        },
-                        "name": {
-                            "type": "string"
-                        }
-                    },
-                    "required": [
-                        "scheme", "in", "alg", "format"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "psk"
-                            ]
-                        },
-                        "identity": {
-                            "type": "string"
-                        }
-                    },
-                    "required": [
-                        "scheme"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "public"
-                            ]
-                        },
-                        "identity": {
-                            "type": "string"
-                        }
-                    },
-                    "required": [
-                        "scheme"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "oauth2"
-                            ]
-                        },
-                        "authorization": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "token": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "refresh": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scopes": {
-                            "type": "array",
-                            "items": {
-                                "type": "string"
-                            }
-                        },
-                        "flow": {
-                            "type": "string",
-                            "enum": ["implicit", "password", "client", "code"]
-                        }
-                    },
-                    "required": [
-                        "scheme", "format", "alg", "in"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "apikey"
-                            ]
-                        },
-                        "in": {
-                            "type": "string",
-                            "enum": ["header", "query", "body", "cookie"]
-                        },
-                        "name": {
-                            "type": "string"
-                        }
-                    },
-                    "required": [
-                        "scheme", "in"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "@context": {
-                            "$ref": "#/definitions/security-context"
-                        },
-                        "@type": {
-                            "$ref": "#/definitions/type_declaration"
-                        },
-                        "description": {
-                            "$ref": "#/definitions/description"
-                        },
-                        "descriptions": {
-                            "$ref": "#/definitions/descriptions"
-                        },
-                        "proxy": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "scheme": {
-                            "type": "string",
-                            "enum": [
-                                "pop"
-                            ]
-                        },
-                        "authorization": {
-                            "$ref": "#/definitions/url"
-                        },
-                        "format": {
-                            "type": "string",
-                            "enum": ["jwt", "jwe", "jws"]
-                        },
-                        "alg": {
-                            "type": "string",
-                            "enum": ["MD5", "ES256", "ES512-256"]
-                        },
-                        "in": {
-                            "type": "string",
-                            "enum": ["header", "query", "body", "cookie"]
-                        },
-                        "name": {
-                            "type": "string"
-                        }
-                    },
-                    "required": [
-                        "scheme"
-                    ]
-                }
-            ]
-        },
-        "url": {
-            "type": "string",
-            "format": "uri-reference"
-        }
-    }
-}
-
-
-
- -
- -
-

Thing Templates

- -

- A Thing Template is a description for a class of devices or things. - It describes the properties, actions, events and common metadata that are shared for an entire group of things, - to enable the common handling of thousands of devices by a cloud server, which is not practical on a per-thing basis. - The Thing Template uses the same core vocabulary and information model from section 5. -

-

- The Thing Template enables: -

    -
  • management of multiple things by a cloud service.
    • -
  • simulation of devices/things that have not yet been developed.
    • -
  • common applications across devices from different manufacturers that share a common thing model.
    • -
  • combining multiple models into a thing. -
-

-

- The Thing Template is a logical description of the interface and possible interaction with devices - (properties, actions and events), however it does not contain device-specific - information, such as a serial number, GPS location, security information or concrete protocol endpoints. -

- Since a Thing Template does not contain a protocol binding to specific endpoints and - does not define a specific security mechanism, the forms and securityDefinitions and - security keys must not be present. -

- The same Thing Template can be implemented by things from multiple vendors, - a thing can implement multiple thing templates, define additional metadata - (vendor, location, security) and define bindings to concrete protocols. - To avoid conflicts between properties, actions and events from different thing templates - that are combined into a common thing, all thse identifiers must be unique within a thing. -

- A common Thing Template for a class of devices enables writing applications across vendors and - creates a more attractive market for application developers. - A concrete Thing Description can implement multiple Thing Templates and - thus can aggregate function blocks into a combined device. -

- The business models of cloud vendors are typically built on managing thousands of identical devices. - All devices with the same Thing Template can be managed in the same way by cloud applications. - It is easy to create multiple simulated devices, if the interface and the instance are treated separately. -

- Since a Thing Template is a subset of the Thing Description in which some optional and mandatory vocabulary terms - does not exist, however, it can be serialized in the same way and in the same formats as a Thing Description. Note that Thing - Template instances cannot be validated in the same way as Thing Description instances due to missing mandatory terms. -

- -
-

Thing Template Examples

- - This section defines a Thing Template for a lamp and a Thing Template for a a buzzer. - The combined thing BuzzerLamp includes both thing templates. - -
-

Thing Template: Lamp

- - 
-    {
-        "@context": ["http://www.w3.org/ns/td"], 
-        "@type" : "ThingTemplate",
-        "id": "urn:dev:wot:com:example:servient:lamp:model",
-        "name": "Lamp Thing Template",
-        "description" : "Lamp Thing Template",
-        "properties": {
-            "status": {
-                "description" : "current status of the lamp (on|off)",
-                "type": "string",
-                "readOnly": true
-            }
-        },
-        "actions": {
-            "toggle": {
-                "description" : "Turn the lamp on or off"
-            }
-        },
-        "events": {
-            "overheating": {
-                "description" : "Lamp reaches a critical temperature (overheating)",
-                "data": {"type": "string"}
-            }
-        }
-    }
-
-
- -
-

Thing Template: Buzzer

- - 
-    {
-        "@context": ["http://www.w3.org/ns/td"], 
-        "@type" : "ThingTemplate",
-        "id": "urn:dev:wot:com:example:servient:buzzer:template",
-        "name": "Buzzer Thing Template",
-        "description" : "Thing template of a buzzer that makes noise for 10 seconds",
-         "actions": {
-            "buzz": {
-                "description" : "buzz for 10 seconds"
-            }
-         }
-    }
-
-
- -
-

Combined Thing: Lamp + Buzzer

-

- The following example illustrates how a combined thing can be defined using two different thing templates. -

- 
-    {
-       "@context": ["http://www.w3.org/ns/td",
-       		    { "thing-templates": "http://www.w3.org/ns/thing-templates"] }, 
-       "@type" : [
-            "Thing",
-            "urn:dev:wot:com:example:servient:lamp:template",
-            "urn:dev:wot:com:example:servient:buzzer:template"
-        ],
-        "id": "urn:dev:wot:com:example:servient:combinedBuzzerLamp1",
-        "name": "My Buzzing Lamp Thing",
-        "description" : "A lamp that can issue an alert",
-        "securityDefinitions": {"nosec_sc": {"scheme": "nosec"}},
-        "security": ["nosec_sc"],
-        "thing-templates:components": [{
-            "id": "urn:dev:wot:com:example:servient:lamp:template",
-            "name": "Lamp Thing Template",
-            "description" : "Thing Template for a lamp",
-            "properties": {
-                "status": {
-                    "description" : "current status of the lamp (on|off)",
-                    "type": "string",
-                    "readOnly": true,
-                    "forms": [{
-                    "href": "coaps://buzzlamp.example.com/status",
-                    "contentType": "application/json"
-                    }]
-                }
-            },
-            "actions": {
-                "toggle": {
-                    "description" : "Turn on or off the lamp",
-                    "forms": [{
-                        "href": "coaps://buzzlamp.example.com/toggle",
-                        "contentType": "application/json"
-                    }]
-                }
-            },
-            "events": {
-                "overheating": {
-                    "@type" : "iot:TemperatureAlarm",
-                    "description" : "Lamp reaches a critical temperature (overheating)",
-                    "data": {"type": "string"},
-                    "forms": [{
-                        "href": "coaps://buzzlamp.example.com/oh",
-                        "contentType": "application/json"
-                    }]
-                }
-            }
-        },
-        {
-            "id": "urn:dev:wot:com:example:servient:buzzer:template",
-            "name": "Buzzer Thing Template",
-            "description" : "Thing Template of a buzzer that makes noise for 10 seconds",
-             "actions": {
-                "buzz": {
-                    "description" : "buzz for 10 seconds",
-                    "forms": [{
-                        "href": "coaps://buzzlamp.example.com/buzz",
-                        "contentType": "application/json"
-                    }]
-                }
-             }
-        }]
-    }
-
-
-
-
computer keyboard have this Scroll Lock key that seems to serve no purpose whatsoever? In 15 years I don't remember ever pushing that button. I'm almost scared to touch it - -
-

Transformation to RDF

- -

- To integrate a Thing Description instance with external knowledge and - contextual information (like iot.schema.org annotations), the use of - JSON-LD 1.1 and its processing API [[json-ld-api]], as well as RDF-based - tools [[rdf11-concepts]] and libraries is highly recommended. -

- -

- TD classes and properties have RDF foundations, in the form of a Web - ontology [[wot-td-ontology]]. On this basis, it is possible to represent - a JSON TD document in RDF to then be uploaded to an RDF store for further - analytics. In terms of implementation, the JSON-LD API specifies the procedure - - toRDF - - to obtain an RDF representation of the JSON-serialized Thing Description instance. -

- -

- To make the transformation reversible, @index must be kept in RDF. - See Github issue w3c/json-ld-api#65. -

- -

- An experimental JSON-LD 1.1 context for the TD model is provided in the - repository: td-context-1.1.jsonld. Currently, it is not the - context served at http://www.w3.org/ns/td, though. -

- -
- -
-

Recent Specification Changes

-

Changes from Third Public Working Draft

-
    -
  • General
    • -
      -
    • The form of TD which does not depend on default value assumptions and can be passed directly to a JSON-LD 1.1 processor for semantic processing is now called Full Thing Description. A JSON Schema for validating TD instances in Full form is available.
      • -
    • InteractionPattern class was renamed as InteractionAffordance.
      • -
    • Security and Privacy Considerations section (Section ) was added.
      • -
    • Thing Templates were introduced for representing a class of devices or things.
      • -
    • A new section was introduced to describe behavioral constraints of a WoT system.
      • -
    • A new appendix section was added to describe how RDF representation of Thing Description can be obtained. At the same time, the Implementation Notes subsection (used to be in Thing Description Serialization section in the previously published draft) was removed.
      • -
    - -
  • Thing
    • -
      -
    • TD now supports meta interactions readallproperties, writeallproperties, readmultipleproperties and writemultipleproperties.
      • -
    • Thing class now has optional created and lastModified members to provide information as to when the TD instance was created (in the case of created) or was last modified (in the case of lastModified).
      • -
    • Thing class now has an optional version member for providing version information.
      • -
    • Members @context and @type were added to Thing class.
      • -
    -
  • InteractionAffordance
    • -
      -
    • Action class now has optional safe and idempotent members to provide information as to the safeness and idempotency of the action.
      • -
    • Property interactions are now both readable and writable by default. This can be overridden through readOnly and writeOnly member settings available in DataSchema class.
      • - -
    • Event class now has optional subscription and cancellation -members that define data that needs to be passed upon subscription and cancellation, respectively.
      • - - -
    • InteractionAffordance class's label member was renamed as title to be consistent with JSON Schema.
      • -
    • InteractionAffordance class now has an optional uriVariables member where URI template variables can be defined.
      • -
    • @type member was added to InteractionAffordance class.
      • -
    • Members scopes and security were removed from InteractionAffordance class.
      • -
    -
  • Form
    • -
      -
    • Form class's now contains response member that can be used to describe metadata for response messages.
      • -
    • Form class's mediaType member was renamed to contentType to reflect that it can assign not only a media type but also its parameter settings.
      • -
    • Form class's rel member was renamed as op, and unobserveproperty was added as one of the enumerated values. The op member has default values depending on the context in which it is used.
      • -
    -
  • DataSchema
    • -
      -
    • DataSchema class now has an optional unit member to provide unit informat
    • NullSchema class was added.
      • -
    • Terms "oneOf" and "format" were added in DataSchema class.
      • -
    • @type member was added to DataSchema class.
      • -
    -
  • Security Scheme
    • -
      -
    • Make it clear that the top-level security declaration is mandatory.
      • -
    • Add securityDefinitions, update examples using security to use defined names, not SecurityScheme objects.
      • -
    • Removed all "Url" postfixes in parameter names for security schemes.
      • -
    • @type member was added to SecurityScheme class.
      • -
    • Multi-language descriptions is allowed in SecurityScheme. -
    -
  • Miscellaneous
    • -
      -
    • Multi-language is supported for human-readable text such as descriptions and titles.
      • -
    • Link class's mediaType member was renamed to type, and the member was given an improved description.
      • -
    -
- -

Changes from Second Public Working Draft

-

Changes from Second Public Working Draft are described in the - Third Public Working Draft -

- -
- -
-

Acknowledgements

-

The editors would like to thank Dave Raggett, Matthias Kovatsch, Michael Koster, Kawaguchi Toru, Michael Lagally, Kazuyuki Ashimura, Ege Korkan, María Poveda, Daniel Peintner, Ben Francis for their contributions, comments, and guidance.

-
- - - From 5dbe2fdaec13e75f866e1385b61cdf42183a3157 Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Wed, 17 Jan 2024 16:19:46 +0100 Subject: [PATCH 40/43] copyover tm files --- .../ver11/7-resources/ontology/tm.html | 105 +++++++++++++ publication/ver11/7-resources/ontology/tm.ttl | 145 +++++++++++++++--- 2 files changed, 227 insertions(+), 23 deletions(-) diff --git a/publication/ver11/7-resources/ontology/tm.html b/publication/ver11/7-resources/ontology/tm.html index e69de29bb..16d7971ec 100644 --- a/publication/ver11/7-resources/ontology/tm.html +++ b/publication/ver11/7-resources/ontology/tm.html @@ -0,0 +1,105 @@ + + + + + + Web of Things (WoT) Thing Model (TM) Ontology + + + + + + +
+

+ The Thing Model (TM) ontology is an RDF axiomatization of the TM concepts, + one of the building blocks of the Web of Things (WoT). Besides providing an alternative + to the standard JSON representation format for TM documents, the TM ontology can also + be used to process contextual information on Things and for alignments with other + WoT-related ontologies. +

+
+
+
+
+

Introduction

+ +

+ The TM ontology is an idiomatic RDF axiomatization of the TM concepts + , which can be used as a template for instantiating Thing Descriptions (TD)s. The TM ontology imports + the TD ontology. +

+
+ +
+ +
+

Terminology

+ +

The fundamental WoT terminology such as + Thing, + Consumer, + Thing Description (TD), + Interaction Model, + Interaction Affordance, + Property, + Action, + Event, + Protocol Binding, + Servient, + etc. is defined in Section 3 + of the WoT Architecture specification [[WOT-ARCHITECTURE]]. +

+ +

+ The Thing Description terminology such as + TD Information Model, + TD Document, + Term (Vocabulary Term), + etc. is defined in Section 3 + of the WoT Thing Description specification [[WOT-THING-DESCRIPTION]]. +

+ +
+ + +

Axiomatization

Classes

ThingModel

IRI: https://www.w3.org/2019/wot/tm#ThingModel

A Thing Model is a description for a class of Things that have the same capabilities. It describes the Properties, Actions, and Events and common metadata that are shared for an entire group of Things. Compared to a Thing Description, a Thing Model does not contain enough information to identify or interact with a Thing instance.
In the domain oftd:description
td:hasLink
td:title
tm:hasVersion
tm:optional
tm:required
+

Version

IRI: https://www.w3.org/2019/wot/tm#Version

The Version is a container that provides versioning information for the Thing Model definition.
In the domain oftm:model
In the range oftm:hasVersion

Object Properties

hasVersion

IRI: https://www.w3.org/2019/wot/tm#hasVersion

Provides the relation between a Thing Model and its version.
Domain includestm:ThingModel
Range includestm:Version

Datatype Properties

model

IRI: https://www.w3.org/2019/wot/tm#model

Provides a version indicator of the underlying TM.
Domain includestm:Version
Range includesschema:Text
+

optional

IRI: https://www.w3.org/2019/wot/tm#optional

Constraint that provides references to declarations in the Thing Model that are optional and do not necessarily need to be implemented when Thing Description instances are derived from this Thing Model. The value of tm:optional MUST provide JSON Pointer [RFC6901] references to the required interaction model definitions.
Domain includestm:ThingModel
Range includesschema:Text
+

ref

IRI: https://www.w3.org/2019/wot/tm#ref

Provides a reference to an existing (external or local) definition that is copied into a newly defined definition. The reference value is based on three parts: an (optional) URI-reference (used for external reference), '#' sign, and JSON Pointer [RFC6901] value.
Domain includestd:InteractionAffordance
Range includesschema:Text
+

required

IRI: https://www.w3.org/2019/wot/tm#required

Constraint that provides references to declarations in the Thing Model that are mandatory and must be present when Thing Description instances are derived from this Thing Model. The reference value is a JSON Pointer [RFC6901].
Domain includestm:ThingModel
Range includesschema:Text

Annotation Properties

versionInfo

IRI: https://www.w3.org/2019/wot/tm#versionInfo

Provides version information of the TM ontology.
+ + + \ No newline at end of file diff --git a/publication/ver11/7-resources/ontology/tm.ttl b/publication/ver11/7-resources/ontology/tm.ttl index d942cf639..a583cf2fe 100644 --- a/publication/ver11/7-resources/ontology/tm.ttl +++ b/publication/ver11/7-resources/ontology/tm.ttl @@ -1,39 +1,138 @@ @prefix : . @prefix dc: . +@prefix td: . @prefix owl: . @prefix rdf: . @prefix xml: . @prefix xsd: . @prefix foaf: . +@prefix hctl: . @prefix rdfs: . @prefix vann: . -@prefix dcterms: . @prefix schema: . -@prefix hctl: . +@prefix dcterms: . +@prefix tm: . +@base . + -: rdf:type owl:Ontology ; + rdf:type owl:Ontology ; + dc:title "Thing Model Ontology"@en ; vann:preferredNamespacePrefix "tm" ; vann:preferredNamespaceUri "https://www.w3.org/2019/wot/tm#" ; - owl:versionInfo "0.1.0" ; - dc:title "Thing Model Ontology"@en ; - rdfs:comment "This ontology aims to model the Web of Things domain according to the W3C Working Group (https://www.w3.org/WoT/)"@en ; + owl:versionInfo "1.1.0" ; + rdfs:comment "This ontology aims to model the Web of Things Thing Model according to the W3C Working Group (https://www.w3.org/wot/)"@en ; dcterms:license ; dcterms:contributor ; + dcterms:author "Mahda Noura (Siemens)" ; dcterms:author "Sebastian Kaebisch (Siemens)" ; - dc:publisher [ a schema:Organization ; schema:name "W3C Web of Things Working Group" ; schema:url ] . - -:ThingModel rdf:type rdfs:Class, owl:Class ; - rdfs:label "ThingModel"@en ; - rdfs:comment "A Thing Model is a description for a class of Things that have the same capabilities. It describes the Properties, Actions, and Events and common metadata that are shared for an entire group of Things. Compared to a Thing Description, a Thing Model does not contain enough information to identify or interact with a Thing instance."@en ; - rdfs:isDefinedBy : . - -:ref rdf:type owl:AnnotationProperty ; - rdfs:label "ref" ; - rdfs:comment "Provides a reference to an existing (external or local) definition that is copied into a newly defined definition. The reference value is based on three parts: an (optional) URI-reference (used for external reference), '#' sign, and JSON Pointer [RFC6901] value."@en ; - rdfs:seeAlso schema:contactPoint ; - rdfs:isDefinedBy : . - -:required rdf:type owl:AnnotationProperty ; - rdfs:label "required" ; - rdfs:comment "Constraint that provides references to declarations in the Thing Model that are mandatory and must be present when Thing Description instances are derived from this Thing Model. The reference value is a JSON Pointer [RFC6901]."@en ; - rdfs:isDefinedBy : . \ No newline at end of file + dcterms:description "This ontology describes Thing Model concepts"@en ; + dc:publisher [ a schema:Organization ; schema:name "W3C Web of Things Working Group"@en ; + schema:url ] . + + +dc:title rdf:type owl:AnnotationProperty . +vann:preferredNamespacePrefix rdf:type owl:AnnotationProperty . +vann:preferredNamespaceUri rdf:type owl:AnnotationProperty . +dcterms:description rdf:type owl:AnnotationProperty . +dcterms:license rdf:type owl:AnnotationProperty . +dcterms:contributor rdf:type owl:AnnotationProperty . +dcterms:author rdf:type owl:AnnotationProperty . +dcterms:license rdf:type owl:AnnotationProperty . +dc:publisher rdf:type owl:AnnotationProperty . +schema:name rdf:type owl:AnnotationProperty . +schema:url rdf:type owl:AnnotationProperty . + + +:versionInfo rdf:type owl:AnnotationProperty ; + rdfs:comment "Provides version information of the TM ontology."@en ; + rdfs:isDefinedBy tm: ; + rdfs:label "versionInfo"@en ; + rdfs:seeAlso schema:version . + + +td:hasInteractionAffordance rdf:type owl:ObjectProperty ; + rdfs:domain :ThingModel ; + rdfs:range td:InteractionAffordance ; + rdfs:comment "Offers an affordance to interact with the Thing"@en ; + rdfs:isDefinedBy td: ; + rdfs:label "hasInteractionAffordance"@en . + + +td:hasLink rdf:type owl:ObjectProperty ; + schema:domainIncludes :ThingModel ; + schema:rangeIncludes hctl:Link ; + rdfs:comment "Provides links to existing resources specified in a Thing Model to extend another Thing Model ."@en ; + rdfs:isDefinedBy td: ; + rdfs:label "hasLink"@en . + + +:hasVersion rdf:type owl:ObjectProperty ; + schema:domainIncludes :ThingModel ; + schema:rangeIncludes :Version ; + rdfs:comment "Provides the relation between a Thing Model and its version."@en ; + rdfs:isDefinedBy tm: ; + rdfs:label "hasVersion"@en . + + + +td:description rdf:type owl:DatatypeProperty ; + rdfs:comment "Provides description of the Thing Model element."@en ; + rdfs:label "description"@en ; + schema:domainIncludes :ThingModel ; + schema:rangeIncludes schema:Text ; + rdfs:isDefinedBy td: . + + +:model rdf:type owl:DatatypeProperty ; + rdfs:label "model"@en ; + schema:domainIncludes :Version ; + schema:rangeIncludes schema:Text ; + rdfs:comment "Provides a version indicator of the underlying TM."@en ; + rdfs:isDefinedBy tm: . + + +:optional rdf:type owl:DatatypeProperty ; + schema:domainIncludes :ThingModel ; + schema:rangeIncludes schema:Text ; + rdfs:comment "Constraint that provides references to declarations in the Thing Model that are optional and do not necessarily need to be implemented when Thing Description instances are derived from this Thing Model. The value of tm:optional MUST provide JSON Pointer [RFC6901] references to the required interaction model definitions."@en ; + rdfs:label "optional"@en ; + rdfs:isDefinedBy tm: . + + +:ref rdf:type owl:DatatypeProperty ; + schema:domainIncludes td:InteractionAffordance ; + schema:rangeIncludes schema:Text ; + rdfs:comment "Provides a reference to an existing (external or local) definition that is copied into a newly defined definition. The reference value is based on three parts: an (optional) URI-reference (used for external reference), '#' sign, and JSON Pointer [RFC6901] value."@en ; + rdfs:label "ref"@en ; + rdfs:seeAlso schema:contactPoint ; + rdfs:isDefinedBy tm: . + + +:required rdf:type owl:DatatypeProperty ; + schema:domainIncludes :ThingModel ; + schema:rangeIncludes schema:Text ; + rdfs:comment "Constraint that provides references to declarations in the Thing Model that are mandatory and must be present when Thing Description instances are derived from this Thing Model. The reference value is a JSON Pointer [RFC6901]."@en ; + rdfs:label "required"@en ; + rdfs:isDefinedBy tm: . + + +td:title rdf:type owl:DatatypeProperty ; + rdfs:subPropertyOf dcterms:title ; + schema:domainIncludes :ThingModel ; + schema:rangeIncludes schema:Text ; + rdfs:comment "Provide the title of the Thing Model"@en ; + rdfs:isDefinedBy td: ; + rdfs:label "title"@en . + + +:ThingModel rdf:type owl:Class ; + rdfs:comment "A Thing Model is a description for a class of Things that have the same capabilities. It describes the Properties, Actions, and Events and common metadata that are shared for an entire group of Things. Compared to a Thing Description, a Thing Model does not contain enough information to identify or interact with a Thing instance."@en ; + rdfs:isDefinedBy tm: ; + rdfs:label "ThingModel"@en . + + +:Version rdf:type owl:Class ; + rdfs:comment "The Version is a container that provides versioning information for the Thing Model definition."@en ; + rdfs:isDefinedBy tm: ; + rdfs:label "Version"@en . + From d2f9d4d7ca527357a8283bd434c1186494f0b4de Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Wed, 17 Jan 2024 19:54:18 +0100 Subject: [PATCH 41/43] add static tm html --- .../7-resources/ontology/staticFiles/tm.html | 717 ++++++++++++++++++ 1 file changed, 717 insertions(+) create mode 100644 publication/ver11/7-resources/ontology/staticFiles/tm.html diff --git a/publication/ver11/7-resources/ontology/staticFiles/tm.html b/publication/ver11/7-resources/ontology/staticFiles/tm.html new file mode 100644 index 000000000..e59e60210 --- /dev/null +++ b/publication/ver11/7-resources/ontology/staticFiles/tm.html @@ -0,0 +1,717 @@ + + + + + + + +Web of Things (WoT) Thing Model (TM) Ontology + + + + + + + + + + + +
+

+

Web of Things (WoT) Thing Model (TM) Ontology

+

W3C Editor's Draft

+
+ More details about this document +
+
This version:
+ https://www.w3.org/2019/wot/td +
+
Latest published version:
+ none +
+
Latest editor's draft:
https://www.w3.org/2019/wot/td
+ + + + + + +
Editors:
+ Mahda Noura (Siemens AG) +
+ Sebastian Käbisch (Siemens AG) +
+ + + + +
Ontology in RDF
+ Web of Things (WoT) Thing Model (TM) Ontology in RDF +
+
+
+ + +

+ Copyright + © + 2023 + + World Wide Web Consortium. + W3C® + liability, + trademark and + permissive document license rules apply. +

+
+
+

Abstract

+

+ The Thing Model (TM) ontology is an RDF axiomatization of the TM concepts, + one of the building blocks of the Web of Things (WoT). Besides providing an alternative + to the standard JSON representation format for TM documents, the TM ontology can also + be used to process contextual information on Things and for alignments with other + WoT-related ontologies. +

+
+

Status of This Document

This section describes the status of this + document at the time of its publication. A list of current W3C + publications and the latest revision of this technical report can be found + in the W3C technical reports index at + https://www.w3.org/TR/.

+

+ This document was published by the Web of Things Working Group as + an Editor's Draft. +

Publication as an Editor's Draft does not + imply endorsement by W3C and its Members.

+ This is a draft document and may be updated, replaced or obsoleted by other + documents at any time. It is inappropriate to cite this document as other + than work in progress. + +

+ + This document was produced by a group + operating under the + W3C Patent + Policy. + + + W3C maintains a + public list of any patent disclosures + made in connection with the deliverables of + the group; that page also includes + instructions for disclosing a patent. An individual who has actual + knowledge of a patent which the individual believes contains + Essential Claim(s) + must disclose the information in accordance with + section 6 of the W3C Patent Policy. + +

+ This document is governed by the + 03 November 2023 W3C Process Document. +

+

1. Introduction

+ + +

+ The TM ontology is an idiomatic RDF axiomatization of the TM concepts + , which can be used as a template for instantiating Thing Descriptions (TD)s. The TM ontology imports + the TD ontology. +

+
+ +

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

+ The key word MUST in this document + is to be interpreted as described in + BCP 14 + [RFC2119] [RFC8174] + when, and only when, they appear in all capitals, as shown here. +

+ +

3. Terminology

+ + +

The fundamental WoT terminology such as + Thing, + Consumer, + Thing Description (TD), + Interaction Model, + Interaction Affordance, + Property, + Action, + Event, + Protocol Binding, + Servient, + etc. is defined in Section 3 + of the WoT Architecture specification [WOT-ARCHITECTURE]. +

+ +

+ The Thing Description terminology such as + TD Information Model, + TD Document, + Term (Vocabulary Term), + etc. is defined in Section 3 + of the WoT Thing Description specification [WOT-THING-DESCRIPTION]. +

+ +
+ + +

4. Axiomatization

4.1 Classes

4.1.1 ThingModel

IRI: https://www.w3.org/2019/wot/tm#ThingModel

A Thing Model is a description for a class of Things that have the same capabilities. It describes the Properties, Actions, and Events and common metadata that are shared for an entire group of Things. Compared to a Thing Description, a Thing Model does not contain enough information to identify or interact with a Thing instance.
In the domain oftd:description
td:hasLink
td:title
tm:hasVersion
tm:optional
tm:required
+

4.1.2 Version

IRI: https://www.w3.org/2019/wot/tm#Version

The Version is a container that provides versioning information for the Thing Model definition.
In the domain oftm:model
In the range oftm:hasVersion

4.2 Object Properties

4.2.1 hasVersion

IRI: https://www.w3.org/2019/wot/tm#hasVersion

Provides the relation between a Thing Model and its version.
Domain includestm:ThingModel
Range includestm:Version

4.3 Datatype Properties

4.3.1 model

IRI: https://www.w3.org/2019/wot/tm#model

Provides a version indicator of the underlying TM.
Domain includestm:Version
Range includesschema:Text
+

4.3.2 optional

IRI: https://www.w3.org/2019/wot/tm#optional

Constraint that provides references to declarations in the Thing Model that are optional and do not necessarily need to be implemented when Thing Description instances are derived from this Thing Model. The value of tm:optional MUST provide JSON Pointer [RFC6901] references to the required interaction model definitions.
Domain includestm:ThingModel
Range includesschema:Text
+

4.3.3 ref

IRI: https://www.w3.org/2019/wot/tm#ref

Provides a reference to an existing (external or local) definition that is copied into a newly defined definition. The reference value is based on three parts: an (optional) URI-reference (used for external reference), '#' sign, and JSON Pointer [RFC6901] value.
Domain includestd:InteractionAffordance
Range includesschema:Text
+

4.3.4 required

IRI: https://www.w3.org/2019/wot/tm#required

Constraint that provides references to declarations in the Thing Model that are mandatory and must be present when Thing Description instances are derived from this Thing Model. The reference value is a JSON Pointer [RFC6901].
Domain includestm:ThingModel
Range includesschema:Text

4.4 Annotation Properties

4.4.1 versionInfo

IRI: https://www.w3.org/2019/wot/tm#versionInfo

Provides version information of the TM ontology.
+ + + + +

A. References

A.1 Normative references

+ +
[RFC2119]
+ Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119 +
[RFC8174]
+ Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174 +
[WOT-ARCHITECTURE]
+ Web of Things (WoT) Architecture. Matthias Kovatsch; Ryuichi Matsukura; Michael Lagally; Toru Kawaguchi; Kunihiko Toumura; Kazuo Kajimoto. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-architecture/ +
[WOT-THING-DESCRIPTION]
+ Web of Things (WoT) Thing Description. Sebastian Käbisch; Takuki Kamiya; Michael McCool; Victor Charpenay; Matthias Kovatsch. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-thing-description/ +
+
\ No newline at end of file From 1d105a59c2d5cabc426c6dae6fcd6809d9e60609 Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Wed, 17 Jan 2024 19:54:28 +0100 Subject: [PATCH 42/43] add tidied ontology html files --- .../ontology/tidiedFiles/hctl.html | 1919 ++++++++++ .../ontology/tidiedFiles/jsonschema.html | 2676 ++++++++++++++ .../7-resources/ontology/tidiedFiles/td.html | 3278 +++++++++++++++++ .../7-resources/ontology/tidiedFiles/tm.html | 1208 ++++++ .../ontology/tidiedFiles/wotsec.html | 2149 +++++++++++ 5 files changed, 11230 insertions(+) create mode 100644 publication/ver11/7-resources/ontology/tidiedFiles/hctl.html create mode 100644 publication/ver11/7-resources/ontology/tidiedFiles/jsonschema.html create mode 100644 publication/ver11/7-resources/ontology/tidiedFiles/td.html create mode 100644 publication/ver11/7-resources/ontology/tidiedFiles/tm.html create mode 100644 publication/ver11/7-resources/ontology/tidiedFiles/wotsec.html diff --git a/publication/ver11/7-resources/ontology/tidiedFiles/hctl.html b/publication/ver11/7-resources/ontology/tidiedFiles/hctl.html new file mode 100644 index 000000000..165858cd1 --- /dev/null +++ b/publication/ver11/7-resources/ontology/tidiedFiles/hctl.html @@ -0,0 +1,1919 @@ + + + + + + + + + + Web of Things (WoT) Hypermedia Controls Ontology + + + + + + + + + +
+

+

Web of Things (WoT) Hypermedia + Controls Ontology

+

W3C Editor's Draft +

+
+ + More details about this document + +
+
This version:
+
+ https://www.w3.org/2019/wot/hypermedia +
+
Latest published version:
+
none
+
Latest editor's draft:
+
+ https://www.w3.org/2019/wot/hypermedia +
+
Editors:
+
Victor Charpenay
+
Matthias Kovatsch
+
Ontology in RDF
+
+ Web of Things (WoT) Hypermedia + Controls Ontology in RDF +
+
+
+

Copyright © 2023 + World Wide Web Consortium. + W3C® + liability, + trademark and + permissive + document license rules apply.

+
+
+
+

Abstract

+

This document introduces an ontology for links and forms, + the main hypermedia controls in use on the Web. This ontology + offers, among others, a means to reify RDF statements + interpreted as links between Web resources. It also provides a + versatile exchange format for links and forms in RESTful Web + applications.

+

Hypermedia controls are of importance in the fields of the + Web of Things and the Embedded Web, in particular in the + W3C Thing + Description model and the IETF Constrained RESTful Application + Language.

+
+
+

Status of This Document

+

This section describes the status of this document at + the time of its publication. A list of current W3C publications and the + latest revision of this technical report can be found in the + W3C technical reports + index at https://www.w3.org/TR/.

+

Validation of the document by the Working Group is expected + by the end of June 2019.

+

This document was published by the Web of Things Working + Group as an Editor's Draft.

+

Publication as an Editor's Draft does not imply endorsement + by W3C and its + Members.

+

This is a draft document and may be updated, replaced or + obsoleted by other documents at any time. It is inappropriate + to cite this document as other than work in progress.

+

This document was produced by a group operating under the + W3C Patent Policy. + W3C maintains a + public list of any + patent disclosures made in connection with the deliverables + of the group; that page also includes instructions for + disclosing a patent. An individual who has actual knowledge of + a patent which the individual believes contains Essential + Claim(s) must disclose the information in accordance with + section + 6 of the W3C + Patent Policy.

+

This document is governed by the 03 November 2023 + W3C Process + Document.

+
+ +
+
+

1. + Introduction

+
+

The concept of Representational State Transfer (REST) + [rest] + is at the core of most modern Web applications. The state of a + Web resources, exposed via a collection of Web resources, can + be browsed by clients by following links and acted + upon by submitting forms to servers.

+

Links and forms have always be present in Web technologies, + including HTML [html]. Web + linking [rfc8288] is a + fundamental principle of the Web architecture that can be + leveraged to drive applications, e.g. when a server returns a + link to a newly created resource as the result of a client's + request. Conversely, forms, are request templates that servers + can expose to clients for them to fill in with client-specific + information and send back to servers. Forms are similar in + spirit to operation desriptions as defined by the Open API + Specification [openapis] or by the Hydra + RDF vocabulary [hydra].

+

Links and forms are generically referred to as + hypermedia controls. They are of increasing importance + in the fields of the Web of Things and the Embedded Web, which + respectively led to the standardization of the Thing + Description (TD) model [wot-thing-description] + and the Constrained RESTful Application Language (CoRAL) + [coral]. + The present hypermedia controls ontology is an attempt to + formalize the concepts these two standards specify.

+
+
+
+

2. + Conformance

+
+

As well as sections marked as non-normative, all authoring + guidelines, diagrams, examples, and notes in this specification + are non-normative. Everything else in this specification is + normative.

+
+
+
+

3. + Terminology

+
+

The fundamental WoT terminology such as Thing, Consumer, Thing + Description (TD), Interaction Model, Interaction + Affordance, Property, Action, Event, Protocol Binding, Servient, etc. is defined in + Section + 3 of the WoT Architecture specification [WOT-ARCHITECTURE].

+

The Thing Description terminology such as TD Information + Model, TD + Document, Term (Vocabulary Term), etc. is defined in + Section + 3 of the WoT Thing Description specification + [WOT-THING-DESCRIPTION].

+
+
+
+

4. + Axiomatization

+
+
+
+

4.1 + Classes

+
+
+
+

4.1.1 + AdditionalExpectedResponse

+
+

IRI: + https://www.w3.org/2019/wot/hypermedia#AdditionalExpectedResponse

Communication + metadata describing the expected response message for + additional responses. + + + + + + + + + + + +
In the domain ofhctl:hasAdditionalOutputSchema
+ + hctl:isSuccess
In the range ofhctl:additionalReturns
+
+
+
+

4.1.2 ExpectedResponse

+
+

IRI: + https://www.w3.org/2019/wot/hypermedia#ExpectedResponse

Communication + metadata describing the expected response message for the + primary response. + + + + + + + +
In the range ofhctl:returns
+
+
+
+

4.1.3 + Form

+
+

IRI: + https://www.w3.org/2019/wot/hypermedia#Form

A + form can be viewed as a statement of "To perform an + operation type operation on form + context, make a request method + request to submission target" where the + optional form fields may further describe + the required request. In Thing Descriptions, the + form context is the surrounding Object, + such as Properties, Actions, and Events or the Thing itself + for meta-interactions. + + + + + + + + + + + +
In the domain ofhctl:additionalReturns
+ + hctl:forContentCoding
+ + hctl:forContentType
+ hctl:forSubProtocol
+ hctl:hasOperationType
+ + hctl:hasTarget
+ hctl:returns
+ + td:hasSecurityConfiguration
In the range oftd:hasForm
+
+ +
+
+
+

4.2 Object Properties

+
+
+
+

4.2.1 additionalReturns

+
+

IRI: + https://www.w3.org/2019/wot/hypermedia#additionalReturns

This + optional term can be used if additional expected responses + 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 response + code), and may also have its own data schema. + + + + + + + + + + + +
Domain includeshctl:Form
Range includeshctl:AdditionalExpectedResponse
+
+
+
+

4.2.2 + hasAdditionalOutputSchema

+
+

IRI: + https://www.w3.org/2019/wot/hypermedia#hasAdditionalOutputSchema

This + optional term can be used to define a data schema for an + additional response if it differs from the default output + data schema. Rather than a DataSchema object, + the name of a previous definition given in a + schemaDefinitions map must be used. + + + + + + + +
Domain includeshctl:AdditionalExpectedResponse
+
+
+
+

4.2.3 hasOperationType

+
+

IRI: + https://www.w3.org/2019/wot/hypermedia#hasOperationType

Indicates + the semantic intention of performing the operation(s) + described by the form. + + + + + + + +
Domain includeshctl:Form
+
+
+
+

4.2.4 + returns

+
+

IRI: + https://www.w3.org/2019/wot/hypermedia#returns

This + optional term can be used if, e.g., the output + communication metadata differ from input metadata (e.g., + output contentType differ from the input contentType). The + response name contains metadata that is only valid for the + reponse messages. + + + + + + + + + + + +
Domain includeshctl:Form
Range includeshctl:ExpectedResponse
+
+
+
+
+

4.3 Datatype Properties

+
+
+
+

4.3.1 forContentCoding

+
+

IRI: + https://www.w3.org/2019/wot/hypermedia#forContentCoding

Content + coding values indicate an encoding transformation that has + been or can be applied to a representation. Content codings + are primarily used to allow a representation to be + compressed or otherwise usefully transformed without losing + the identity of its underlying media type and without loss + of information. Examples of content coding include "gzip", + "deflate", etc. + + + + + + + + + + + +
Domain includeshctl:Form
Range includesschema:Text
+
+
+
+

4.3.2 forContentType

+
+

IRI: + https://www.w3.org/2019/wot/hypermedia#forContentType

Assign + a content type based on a media type [IANA-MEDIA-TYPES] (e.g., + 'text/plain') and potential parameters (e.g., + 'charset=utf-8') for the media type. + + + + + + + + + + + +
Domain includeshctl:Form
Range includesschema:Text
+
+
+
+

4.3.3 forSubProtocol

+
+

IRI: + https://www.w3.org/2019/wot/hypermedia#forSubProtocol

Indicates + the exact mechanism by which an interaction will be + accomplished for a given protocol when there are multiple + options. For example, for HTTP and Events, it indicates + which of several available mechanisms should be used for + asynchronous notifications such as long polling, websub + (also see https://www.w3.org/TR/websub/), or server sent + events (also see https://www.w3.org/TR/eventsource/). + Please note that there is no restriction on the + sub-protocol selection and other mechanisms can also be + announced by this subprotocol term. + + + + + + + + + + + +
Domain includeshctl:Form
Range includesschema:Text
+
+
+
+

4.3.4 + hasAnchor

+
+

IRI: + https://www.w3.org/2019/wot/hypermedia#hasAnchor

By + default, the context, or anchor, of a link conveyed in the + Link header field is the URL of the representation it is + associated with, as defined in RFC7231, Section 3.1.4.1, + and is serialized as a URI. + + + + + + + +
Domain includeshctl:Link
+
+
+
+

4.3.5 hasHreflang

+
+

IRI: + https://www.w3.org/2019/wot/hypermedia#hasHreflang

The + hreflang attribute specifies the language of a linked + document. The value of this must be a valid language tag + [BCP47]. + + + + + + + +
Domain includeshctl:Link
+
+
+
+

4.3.6 hasRelationType

+
+

IRI: + https://www.w3.org/2019/wot/hypermedia#hasRelationType

A + link relation type identifies the semantics of a + link. + + + + + + + +
Domain includeshctl:Link
+
+
+
+

4.3.7 + hasSizes

+
+

IRI: + https://www.w3.org/2019/wot/hypermedia#hasSizes

Target + attribute that specifies one or more sizes for the + referenced icon. Only applicable for relation type 'icon'. + The value pattern follows {Height}x{Width} (e.g., "16x16", + "16x16 32x32") + + + + + + + +
Domain includeshctl:Link
+
+
+
+

4.3.8 + hasTarget

+
+

IRI: + https://www.w3.org/2019/wot/hypermedia#hasTarget

target + IRI of a link or submission target of a form. + + + + + + + +
Domain includeshctl:Form
+ hctl:Link
+
+
+
+

4.3.9 hintsAtMediaType

+
+

IRI: + https://www.w3.org/2019/wot/hypermedia#hintsAtMediaType

Target + attribute providing a hint indicating what the media type + [IANA-MEDIA-TYPES] of the result of dereferencing the link + should be. + + + + + + + + + + + +
Domain includeshctl:Link
Range includesschema:Text
+
+
+
+

4.3.10 isSuccess

+
+

IRI: + https://www.w3.org/2019/wot/hypermedia#isSuccess

Signals + if the additional response should not be considered an + error. + + + + + + + + + + + +
Domain includeshctl:AdditionalExpectedResponse
Range includesschema:Boolean
+
+
+
+
+

4.4 Annotation Properties

+
+

No AnnotationProperty found in the ontology.

+
+
+
+
+

5. + Alignments

+
+
+
+

5.1 + Hydra

+
+

The following table gives alignment between the hypermedia + controls ontology and Hydra, an alternative + vocabulary for hypermedia-driven Web APIs. Each row + represents a close match between two classes. These + alignments are not to be understood as formal semantic + equivalences but rather as hints to Hydra users.

+ + + + + + + + + + + +
hctl:Linkhydra:Link
hctl:Formhydra:Operation
+
+
+
+
+

6. Usage + Examples

+
+ + +
+ +
+
+

A. + References

+
+
+
+

A.1 Normative references

+
+
+
[BCP47]
+
+ Tags for + Identifying Languages. A. Phillips, Ed.; M. + Davis, Ed.. IETF. September 2009. Best Current Practice. + URL: https://www.rfc-editor.org/rfc/rfc5646 +
+
[coral]
+
+ + The Constrained RESTful Application Language + (CoRAL). Klaus Hartke. IETF. March 2019. + Internet-Draft. URL: https://tools.ietf.org/html/draft-hartke-t2trg-coral +
+
[html]
+
+ HTML + Standard. Anne van Kesteren; Domenic Denicola; + Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. + Living Standard. URL: https://html.spec.whatwg.org/multipage/ +
+
[hydra]
+
+ Hydra + Core Vocabulary. Markus Lanthaler. Hydra W3C + Community Group. URL: https://www.hydra-cg.com/spec/latest/core/ +
+
[IANA-MEDIA-TYPES]
+
+ Media + Types. IANA. URL: https://www.iana.org/assignments/media-types/ +
+
[openapis]
+
+ OpenAPI + Specification. Darrell Miller; Jeremy + Whitlock; Marsh Gardiner; Mike Ralphson; Ron Ratovsky; + Uri Sarid; Tony Tam; Jason Harmon. OpenAPI Initiative. + URL: https://www.openapis.org/ +
+
[rest]
+
REST: Architectural Styles and the Design of + Network-based Software Architectures. University of + California, Irvine. 2000. PhD thesis.
+
[rfc8288]
+
+ Web + Linking. M. Nottingham. IETF. October 2017. + Proposed Standard. URL: https://httpwg.org/specs/rfc8288.html +
+
[WOT-ARCHITECTURE]
+
+ Web of + Things (WoT) Architecture. Matthias Kovatsch; + Ryuichi Matsukura; Michael Lagally; Toru Kawaguchi; + Kunihiko Toumura; Kazuo Kajimoto. W3C. 9 April 2020. W3C + Recommendation. URL: https://www.w3.org/TR/wot-architecture/ +
+
+ [wot-thing-description]
+
+ Web + of Things (WoT) Thing Description. Sebastian + Käbisch; Takuki Kamiya; Michael McCool; Victor Charpenay; + Matthias Kovatsch. W3C. 9 April 2020. W3C Recommendation. + URL: https://www.w3.org/TR/wot-thing-description/ +
+
+
+
+ + + + + + + + + + + + + + + + + + + + diff --git a/publication/ver11/7-resources/ontology/tidiedFiles/jsonschema.html b/publication/ver11/7-resources/ontology/tidiedFiles/jsonschema.html new file mode 100644 index 000000000..d3108211d --- /dev/null +++ b/publication/ver11/7-resources/ontology/tidiedFiles/jsonschema.html @@ -0,0 +1,2676 @@ + + + + + + + + + + + Web of Things (WoT) JSON Schema Ontology + + + + + + + + + +
+

+

Web of Things (WoT) JSON Schema + Ontology

+

W3C Editor's Draft +

+
+ + More details about this document + +
+
This version:
+
+ https://www.w3.org/2019/wot/json-schema +
+
Latest published version:
+
none
+
Latest editor's draft:
+
+ https://www.w3.org/2019/wot/json-schema +
+
Editors:
+
Victor Charpenay
+
Maxime Lefrançois
+
María Poveda Villalón
+
Ontology in RDF
+
+ Web of Things (WoT) JSON Schema + Ontology in RDF +
+
+
+

Copyright © 2023 + World Wide Web Consortium. + W3C® + liability, + trademark and + permissive + document license rules apply.

+
+
+
+

Abstract

+

This document introduces an RDF vocabulary for JSON schema + definitions. This vocabulary provides a stable namespace IRI + for JSON schema keywords, as well as simple axioms, defined + against schema.org's meta-model. Various examples on how to use + the vocabulary are also introduced, e.g. to annotate schemas + with JSON-LD metadata or to embed schema annotations inside RDF + graphs.

+
+
+

Status of This Document

+

This section describes the status of this document at + the time of its publication. A list of current W3C publications and the + latest revision of this technical report can be found in the + W3C technical reports + index at https://www.w3.org/TR/.

+

Validation of the document by the Working Group is expected + by the end of June 2019.

+

This document was published by the Web of Things Working + Group as an Editor's Draft.

+

Publication as an Editor's Draft does not imply endorsement + by W3C and its + Members.

+

This is a draft document and may be updated, replaced or + obsoleted by other documents at any time. It is inappropriate + to cite this document as other than work in progress.

+

This document was produced by a group operating under the + W3C Patent Policy. + W3C maintains a + public list of any + patent disclosures made in connection with the deliverables + of the group; that page also includes instructions for + disclosing a patent. An individual who has actual knowledge of + a patent which the individual believes contains Essential + Claim(s) must disclose the information in accordance with + section + 6 of the W3C + Patent Policy.

+

This document is governed by the 03 November 2023 + W3C Process + Document.

+
+ +
+
+

1. + Introduction

+
+

JSON schema is a popular schema language for JSON documents + [json-schema-validation]. + This vocabulary includes the main terms defined by JSON schema + in order to represent schema definitions in RDF. Besides + providing a stable namespace IRI for JSON schema terms, this + vocabulary also includes axioms based on schema.org's + meta-model. Its design favors simplicity of use over + completeness.

+

Representing JSON schema in RDF was originally intended to + be used as part of the W3C Web of Things (WoT) + framework and in particular in the Thing Description model + [wot-thing-description]. + However, processing JSON schema in RDF is not limited to WoT. + Other use cases include:

+
    +
  • Alignment of schema definitions with RDF vocabularies and + RDF shapes
    • +
  • Rule-based validation or transformation of JSON data
    • +
  • Integration of various forms of data specfications, + including JSON schema
    • +
+

incidentally, the RDF representation of JSON schema + definitions provides an alternative to the JSON hyper-schema + [json-hyper-schema] + for cross-references and linking. Examples are provided at the + end of the document.

+
+
+
+

2. + Conformance

+
+

As well as sections marked as non-normative, all authoring + guidelines, diagrams, examples, and notes in this specification + are non-normative. Everything else in this specification is + normative.

+
+
+
+

3. + Terminology

+
+

The fundamental WoT terminology such as Thing, Consumer, Thing + Description (TD), Interaction Model, Interaction + Affordance, Property, Action, Event, Protocol Binding, Servient, etc. is defined in + Section + 3 of the WoT Architecture specification [WOT-ARCHITECTURE].

+

The Thing Description terminology such as TD Information + Model, TD + Document, Term (Vocabulary Term), etc. is defined in + Section + 3 of the WoT Thing Description specification + [WOT-THING-DESCRIPTION].

+
+
+
+

4. + Axiomatization

+
+
+
+

4.1 + Classes

+
+
+
+

4.1.1 ArraySchema

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#ArraySchema

Metadata + describing data of type array. This subclass is indicated + by the value array assigned to + type in DataSchema + instances. + + + + + + + + + + + +
Sub-class ofjsonschema:DataSchema
In the domain ofjsonschema:items
+ jsonschema:maxItems
+ jsonschema:minItems
+
+
+
+

4.1.2 BooleanSchema

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#BooleanSchema

Metadata + describing data of type boolean. This subclass + is indicated by the value boolean assigned to + type in DataSchema + instances. + + + + + + + +
Sub-class ofjsonschema:DataSchema
+
+
+
+

4.1.3 + DataSchema

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#DataSchema

Metadata + that describes the data format used. It can be used for + validation. + + + + + + + + + + + + + + + +
Super-class ofjsonschema:ArraySchema
+ jsonschema:BooleanSchema
+ + jsonschema:IntegerSchema
+ + jsonschema:NullSchema
+ jsonschema:NumberSchema
+ + jsonschema:ObjectSchema
+ + jsonschema:StringSchema
In the domain ofjsonschema:allOf
+ jsonschema:anyOf
+ jsonschema:const
+ jsonschema:default
+ jsonschema:enum
+ jsonschema:oneOf
+ jsonschema:propertyName
+ + jsonschema:readOnly
+ jsonschema:writeOnly
+ td:description
+ + + td:descriptionInLanguage
+ td:title
+ + td:titleInLanguage
In the range ofjsonschema:allOf
+ jsonschema:anyOf
+ jsonschema:items
+ jsonschema:oneOf
+ jsonschema:properties
+
+
+
+

4.1.4 IntegerSchema

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#IntegerSchema

Metadata + describing data of type integer. This subclass + is indicated by the value integer assigned to + type in DataSchema + instances. + + + + + + + + + + + +
Sub-class ofjsonschema:DataSchema
In the domain ofjsonschema:exclusiveMaximum
+ + jsonschema:exclusiveMinimum
+ + jsonschema:maximum
+ jsonschema:minimum
+ jsonschema:multipleOf
+
+
+
+

4.1.5 + NullSchema

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#NullSchema

Metadata + describing data of type null. This subclass is + indicated by the value null assigned to + type in DataSchema instances. + This Subclass describes only one acceptable value, namely + null. It is important to note that + null does not mean the absence of a value. It + is analogous to null in JavaScript, + None in Python, null in Java and + nil in Ruby programming languages. It can be + used as part of a oneOf declaration, where it + is used to indicate, that the data can also be + null. + + + + + + + +
Sub-class ofjsonschema:DataSchema
+
+
+
+

4.1.6 NumberSchema

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#NumberSchema

Metadata + describing data of type number. This subclass + is indicated by the value number assigned to + type in DataSchema + instances. + + + + + + + + + + + +
Sub-class ofjsonschema:DataSchema
In the domain ofjsonschema:exclusiveMaximum
+ + jsonschema:exclusiveMinimum
+ + jsonschema:maximum
+ jsonschema:minimum
+ jsonschema:multipleOf
+
+
+
+

4.1.7 ObjectSchema

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#ObjectSchema

Metadata + describing data of type object. This subclass + is indicated by the value object assigned to + type in DataSchema + instances. + + + + + + + + + + + +
Sub-class ofjsonschema:DataSchema
In the domain ofjsonschema:properties
+ jsonschema:required
+
+
+
+

4.1.8 StringSchema

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#StringSchema

Metadata + describing data of type string. This subclass + is indicated by the value string assigned to + type in DataSchema + instances. + + + + + + + + + + + +
Sub-class ofjsonschema:DataSchema
In the domain ofjsonschema:contentEncoding
+ + jsonschema:contentMediaType
+ + jsonschema:format
+ jsonschema:maxLength
+ jsonschema:minLength
+ jsonschema:pattern
+
+
+
+
+

4.2 Object Properties

+
+
+
+

4.2.1 + allOf

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#allOf

Used + to ensure that the data is valid against all of the + specified schemas in the array. + + + + + + + + + + + +
Domain includesjsonschema:DataSchema
Range includesjsonschema:DataSchema
+
+
+
+

4.2.2 + anyOf

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#anyOf

Used + to ensure that the data is valid against any of the + specified schemas in the array. + + + + + + + + + + + +
Domain includesjsonschema:DataSchema
Range includesjsonschema:DataSchema
+
+
+
+

4.2.3 + items

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#items

Used + to define the characteristics of an array. + + + + + + + + + + + +
Domain includesjsonschema:ArraySchema
Range includesjsonschema:DataSchema
+
+
+
+

4.2.4 + oneOf

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#oneOf

Used + to ensure that the data is valid against exactly one of the + specified schemas in the array. + + + + + + + + + + + +
Domain includesjsonschema:DataSchema
Range includesjsonschema:DataSchema
+
+
+
+

4.2.5 + properties

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#properties

Data + schema nested definitions + + + + + + + + + + + +
Domain includesjsonschema:ObjectSchema
Range includesjsonschema:DataSchema
+
+
+
+
+

4.3 Datatype Properties

+
+
+
+

4.3.1 + const

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#const

Provides + a constant value. + + + + + + + +
Domain includesjsonschema:DataSchema
+
+
+
+

4.3.2 contentEncoding

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#contentEncoding

Specifies + the encoding used to store the contents, as specified in + RFC 2054. The values that are accepted: "7bit", "8bit", + "binary", "quoted-printable" and "base64". + + + + + + + +
Domain includesjsonschema:StringSchema
+
+
+
+

4.3.3 contentMediaType

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#contentMediaType

Specifies + the MIME type (e.g., image/png, audio/mpeg) of the contents + of a string value, as described in RFC 2046. + + + + + + + +
Domain includesjsonschema:StringSchema
+
+
+
+

4.3.4 + default

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#default

Supply + a default value. The value should validate against the data + schema in which it resides. + + + + + + + +
Domain includesjsonschema:DataSchema
+
+
+
+

4.3.5 + enum

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#enum

Restricted + set of values provided as an array. + + + + + + + +
Domain includesjsonschema:DataSchema
+
+
+
+

4.3.6 exclusiveMaximum

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#exclusiveMaximum

Specifies + a maximum numeric value, representing an exclusive upper + limit. Only applicable for associated number or integer + types. + + + + + + + +
Domain includesjsonschema:IntegerSchema
+ + jsonschema:NumberSchema
+
+
+
+

4.3.7 exclusiveMinimum

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#exclusiveMinimum

Specifies + a minimum numeric value, representing an exclusive lower + limit. Only applicable for associated number or integer + types. + + + + + + + +
Domain includesjsonschema:IntegerSchema
+ + jsonschema:NumberSchema
+
+
+
+

4.3.8 + format

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#format

Allows + validation based on a format pattern such as "date-time", + "email", "uri", etc. + + + + + + + +
Domain includesjsonschema:StringSchema
+
+
+
+

4.3.9 + maxItems

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#maxItems

Defines + the maximum number of items that have to be in the + array. + + + + + + + +
Domain includesjsonschema:ArraySchema
+
+
+
+

4.3.10 maxLength

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#maxLength

Specifies + the maximum length of a string. Only applicable for + associated string types. + + + + + + + +
Domain includesjsonschema:StringSchema
+
+
+
+

4.3.11 + maximum

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#maximum

Specifies + a maximum numeric value, representing an inclusive upper + limit. Only applicable for associated number or integer + types. + + + + + + + +
Domain includesjsonschema:IntegerSchema
+ + jsonschema:NumberSchema
+
+
+
+

4.3.12 + minItems

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#minItems

Defines + the minimum number of items that have to be in the + array. + + + + + + + +
Domain includesjsonschema:ArraySchema
+
+
+
+

4.3.13 minLength

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#minLength

Specifies + the minimum length of a string. Only applicable for + associated string types. + + + + + + + +
Domain includesjsonschema:StringSchema
+
+
+
+

4.3.14 + minimum

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#minimum

Specifies + a minimum numeric value, representing an inclusive lower + limit. Only applicable for associated number or integer + types. + + + + + + + +
Domain includesjsonschema:IntegerSchema
+ + jsonschema:NumberSchema
+
+
+
+

4.3.15 multipleOf

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#multipleOf

Specifies + the multipleOf value number. The value must strictly + greater than 0. Only applicable for associated number or + integer types. + + + + + + + +
Domain includesjsonschema:IntegerSchema
+ + jsonschema:NumberSchema
+
+
+
+

4.3.16 + pattern

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#pattern

Provides + a regular expression to express constraints of the string + value. The regular expression must follow the ECMA 262 + dialect. + + + + + + + +
Domain includesjsonschema:StringSchema
+
+
+
+

4.3.17 propertyName

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#propertyName

Used + to store the indexing name in the parent object when this + schema appears as a property of an object schema. + + + + + + + +
Domain includesjsonschema:DataSchema
+
+
+
+

4.3.18 + readOnly

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#readOnly

Boolean + value that is a hint to indicate whether a property + interaction / value is read only (=true) or not + (=false) + + + + + + + +
Domain includesjsonschema:DataSchema
+
+
+
+

4.3.19 + required

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#required

Defines + which members of the object type are mandatory, i.e. which + members are mandatory in the payload that is to be sent + (e.g. input of invokeaction, + writeproperty) and what members will be + definitely delivered in the payload that is being received + (e.g. output of invokeaction, + readproperty) + + + + + + + +
Domain includesjsonschema:ObjectSchema
+
+
+
+

4.3.20 writeOnly

+
+

IRI: + https://www.w3.org/2019/wot/json-schema#writeOnly

Boolean + value that is a hint to indicate whether a property + interaction / value is write only (=true) or not + (=false) + + + + + + + +
Domain includesjsonschema:DataSchema
+
+
+
+
+

4.4 Annotation Properties

+
+

No AnnotationProperty found in the ontology.

+
+
+
+
+

5. Usage + Examples

+
+
+
+

+ 5.1 Interpreting JSON Schema as + JSON-LD 1.1

+
+

The following JSON-LD context [json-ld11] can be added to JSON + schema definitions to obtain an RDF representation of these + definitions.

+ +

The two following examples show the equivalence between + the JSON and the Turtle representations of schema + definitions. These examples were taken from the collection of schemas managed + by the Open Connectivity Foundation (OCF).

+ + +
+
+ Note +
+

The value defined for the const + and enum terms is always interpreted as a raw + JSON value, even if it is an array or an object. In RDF, it + becomes a typed literal with datatype + rdf:JSON.

+
+
+
+ Note +
+

In its latest version, the JSON schema + items term can be interpreted in two different + ways: if the value is a single schema definition, all items + in the array must then be proper instance of that schema ; + if the value is an array of schema definitions, an item in + the instance array must be an instance of the schema at the + same index in the schema array. In the latter case, the + schema array should be interpreted as an RDF list rather as + a set of statement (to preserve order). It is however not + possible to express both cases with a single JSON-LD + context. The context given in Example 1 only reflects the + former case.

+
+
+
+ Note +
+

JSON schema allows schemas to be defined in a + "collection" object under definitions. This + feature is purely syntactical, hence not reflected in the + present RDF vocabulary for JSON schema. Interpreting + schemas under definitions as JSON-LD requires + prior normalization, by substituting references in the main + schema with their definition. This normalization procedure + may be directly supported by JSON-LD processors in the + future.

+
+
+
+ Note +
+

The JSON Schema RDF vocabulary does not include + terms for title and description. + Instead, the example context maps them to widely used + Dublin Core terms with equivalent semantics.

+
+
+
+
+

5.2 Referencing and linking

+
+

JSON schema defines the $id and + $ref keywords to increase reusability but also + to define schemas in a recursive fashion. This feature is + natively supported by RDF: if schema definitions are named + resources (identified by an IRI) instead of blank nodes, they + can be referenced from anywhere on the Web.

+

The id keyword (an alias for + @id) can be used for that purpose, as shown in + the following example, taken from an OCF standard.

+ +
+
+ Note +
+

If the same schema definition (with the same + IRI) is used twice as the value of one of the + properties of an object schema, it may result + in name collisions. Indeed, after transformation to RDF, + this schema will have two statements with + :propertyValue that do not link back to the + object from which they respectively originate.

+
+

Besides IRI references between schemas, JSON hyper-schema + [json-hyper-schema] + allows arbitrary links to be embedded in a schema definition. + An alternative to JSON hyper-schema is to use plain RDF + statements or the RDF vocabulary for + hypermedia controls. Examples can be found in the + documentation of that vocabulary.

+
+
+
+

+ 5.3 Defining a JSON-LD context for + data instances

+
+

JSON schema definitions may specify JSON structures that + are themselves interpretable as RDF (or JSON-LD). To be able + to do so, instances of a certain schema must be given a + JSON-LD context to map JSON terms to RDF IRIs. This can be + done within a schema definition using the JSON-LD vocabulary in RDF, + and more precisely with the property + jsonld:context.

+ +

The example above allows schema-aware agents on the Web to + interpret any instance of the schema as JSON-LD by appending + the context given as annotation to the instance JSON, as + shown below.

+ +

Note the difference with using @context in + the schema definition: it is used to interpret + instances as JSON-LD, while @context + would alter the way the schema itself is + interpreted.

+

The JSON-LD vocabulary in RDF includes terms to represent + any JSON-LD context in RDF. As a result, contexts can be + directly embedded in JSON schema definitions as well. The + example below is a variant of Example 6 in which only a subset of + schema.org's default context is embedded in the schema.

+ +
+
+
+

+ 5.4 Embedding schema definitions + in data instances

+
+

Although schema definitions are often put in separate + documents, it may be convenient to embed them in instance + data itself, as in the following example, which uses the + Smart Appliance Reference vocabulary (SAREF) [smartm2m]. + This usage of the JSON schema vocabulary is similar to that + of schema:PropertyValue + and schema:PropertyValueSpecification.

+ +

This way, it is possible to convey a JSON tree + representation that does not strictly follow the RDF + structure of some entity. In the following example, the + temperature property expressed in SAREF terms embeds a + variant of the schema of Example 3.

+ +
+
+ +
+
+

A. + References

+
+
+
+

A.1 Normative references

+
+
+
[json-hyper-schema]
+
+ + JSON Hyper-Schema: A Vocabulary for Hypermedia + Annotation of JSON. Henry Andrews; Austin + Wright. IETF. Internet-Draft. URL: + https://tools.ietf.org/html/draft-handrews-json-schema-hyperschema-00 +
+
[json-ld11]
+
+ JSON-LD + 1.1. Gregg Kellogg; Pierre-Antoine Champin; + Dave Longley. W3C. 16 July 2020. W3C Recommendation. URL: + https://www.w3.org/TR/json-ld11/ +
+
+ [json-schema-validation]
+
+ + JSON Schema Validation: A Vocabulary for Structural + Validation of JSON. Austin Wright; Henry + Andrews; Geraint Luff. IETF. Internet-Draft. URL: + + https://tools.ietf.org/html/draft-handrews-json-schema-validation-00 +
+
[smartm2m]
+
+ + ETSI TS 103 264 V2.1.1 (2017-03): SmartM2M; Smart + Appliances; Reference Ontology and oneM2M + Mapping. ETSI. March 2017. Published. URL: + + http://www.etsi.org/deliver/etsi_ts/103200_103299/103264/02.01.01_60/ts_103264v020101p.pdf +
+
[WOT-ARCHITECTURE]
+
+ Web of + Things (WoT) Architecture. Matthias Kovatsch; + Ryuichi Matsukura; Michael Lagally; Toru Kawaguchi; + Kunihiko Toumura; Kazuo Kajimoto. W3C. 9 April 2020. W3C + Recommendation. URL: https://www.w3.org/TR/wot-architecture/ +
+
+ [wot-thing-description]
+
+ Web + of Things (WoT) Thing Description. Sebastian + Käbisch; Takuki Kamiya; Michael McCool; Victor Charpenay; + Matthias Kovatsch. W3C. 9 April 2020. W3C Recommendation. + URL: https://www.w3.org/TR/wot-thing-description/ +
+
+
+
+ + + + + + + + + + + + + + + + + + + + diff --git a/publication/ver11/7-resources/ontology/tidiedFiles/td.html b/publication/ver11/7-resources/ontology/tidiedFiles/td.html new file mode 100644 index 000000000..bb219e52c --- /dev/null +++ b/publication/ver11/7-resources/ontology/tidiedFiles/td.html @@ -0,0 +1,3278 @@ + + + + + + + + + + Web of Things (WoT) Thing Description (TD) + Ontology + + + + + + + + + + +
+

+

Web of Things (WoT) Thing + Description (TD) Ontology

+

W3C Editor's Draft +

+
+ + More details about this document + +
+
This version:
+
+ https://www.w3.org/2019/wot/td +
+
Latest published version:
+
none
+
Latest editor's draft:
+
+ https://www.w3.org/2019/wot/td +
+
Editors:
+
+ Victor Charpenay + (Siemens AG) +
+
+ Maxime Lefrançois + (École des Mines de + Saint-Étienne) +
+
+ María Poveda Villalón + (Universidad Politécnica de + Madrid) +
+
+ Sebastian Käbisch + (Siemens AG) +
+
Ontology in RDF
+
+ Web of Things (WoT) TD Ontology in + RDF +
+
+
+

Copyright © 2023 + World Wide Web Consortium. + W3C® + liability, + trademark and + permissive + document license rules apply.

+
+
+
+

Abstract

+

The Thing Description (TD) ontology is an RDF axiomatization + of the TD information model, one of the building blocks of the + Web of Things (WoT). Besides providing an alternative to the + standard JSON representation format for TD documents, the TD + ontology can also be used to process contextual information on + Things and for alignments with other WoT-related + ontologies.

+
+
+

Status of This Document

+

This section describes the status of this document at + the time of its publication. A list of current W3C publications and the + latest revision of this technical report can be found in the + W3C technical reports + index at https://www.w3.org/TR/.

+

Validation of the document by the Working Group is expected + by the end of June 2019.

+

This document was published by the Web of Things Working + Group as an Editor's Draft.

+

Publication as an Editor's Draft does not imply endorsement + by W3C and its + Members.

+

This is a draft document and may be updated, replaced or + obsoleted by other documents at any time. It is inappropriate + to cite this document as other than work in progress.

+

This document was produced by a group operating under the + W3C Patent Policy. + W3C maintains a + public list of any + patent disclosures made in connection with the deliverables + of the group; that page also includes instructions for + disclosing a patent. An individual who has actual knowledge of + a patent which the individual believes contains Essential + Claim(s) must disclose the information in accordance with + section + 6 of the W3C + Patent Policy.

+

This document is governed by the 03 November 2023 + W3C Process + Document.

+
+ +
+
+

1. + Introduction

+
+

The TD ontology is an idiomatic RDF axiomatization of the TD + information model [WOT-THING-DESCRIPTION], + which can be used to describe WoT things and their interaction + affordances. The TD ontology imports the hypermedia + controls ontology. However, although the TD information + model also includes terms for data schemas and security + configurations, the TD ontology does not force the use of the + corresponding JSON schema and + WoT security + vocabularies. Other schema languages like SHACL + [shacl] can thus + be leveraged to describe WoT Things.

+
+
+
+

2. + Conformance

+
+

As well as sections marked as non-normative, all authoring + guidelines, diagrams, examples, and notes in this specification + are non-normative. Everything else in this specification is + normative.

+
+
+
+

3. + Terminology

+
+

The fundamental WoT terminology such as Thing, Consumer, Thing + Description (TD), Interaction Model, Interaction + Affordance, Property, Action, Event, Protocol Binding, Servient, etc. is defined in + Section + 3 of the WoT Architecture specification [WOT-ARCHITECTURE].

+

The Thing Description terminology such as TD Information + Model, TD + Document, Term (Vocabulary Term), etc. is defined in + Section + 3 of the WoT Thing Description specification + [WOT-THING-DESCRIPTION].

+
+
+
+

4. + Axiomatization

+
+
+
+

4.1 + Classes

+
+
+
+

4.1.1 ActionAffordance

+
+

IRI: + https://www.w3.org/2019/wot/td#ActionAffordance

An + Interaction Affordance that allows to invoke a function of + the Thing, which manipulates state (e.g., toggling a lamp + on or off) or triggers a process on the Thing (e.g., dim a + lamp over time). + + + + + + + + + + + + + + + +
Sub-class oftd:InteractionAffordance
In the domain oftd:hasInputSchema
+ td:hasOutputSchema
+ td:isIdempotent
+ td:isSafe
+ td:isSynchronous
In the range oftd:hasActionAffordance
+
+
+
+

4.1.2 EventAffordance

+
+

IRI: + https://www.w3.org/2019/wot/td#EventAffordance

An + Interaction Affordance that describes an event source, + which asynchronously pushes event data to Consumers (e.g., + overheating alerts). + + + + + + + + + + + + + + + +
Sub-class oftd:InteractionAffordance
In the domain oftd:hasCancellationSchema
+ + td:hasNotificationResponseSchema
+ + td:hasNotificationSchema
+ + td:hasSubscriptionSchema
In the range oftd:hasEventAffordance
+
+
+
+

4.1.3 InteractionAffordance

+
+

IRI: + https://www.w3.org/2019/wot/td#InteractionAffordance

Metadata + of a Thing that shows the possible choices to Consumers, + thereby suggesting how Consumers may interact with the + Thing. There are many types of potential affordances, but + W3C WoT + defines three types of Interaction Affordances: Properties, + Actions, and Events. + + + + + + + + + + + + + + + +
Super-class oftd:ActionAffordance
+ + td:EventAffordance
+ td:PropertyAffordance
In the domain oftd:description
+ td:descriptionInLanguage
+ + td:hasForm
+ td:hasUriTemplateSchema
+ + td:name
+ td:title
+ td:titleInLanguage
In the range oftd:hasInteractionAffordance
+
+
+
+

4.1.4 OperationType

+
+

IRI: + https://www.w3.org/2019/wot/td#OperationType

Enumeration + of well-known operation types necessary to implement the + WoT interaction model + + + + + + + +
Enumeration memberstd:cancelAction
+ td:invokeAction
+ td:observeAllProperties
+ + td:observeProperty
+ td:queryAction
+ td:queryAllActions
+ td:readAllProperties
+ + td:readMultipleProperties
+ + td:readProperty
+ td:subscribeAllEvents
+ + td:subscribeEvent
+ td:unobserveAllProperties
+ + td:unobserveProperty
+ + td:unsubscribeAllEvents
+ + td:unsubscribeEvent
+ + td:writeAllProperties
+ + td:writeMultipleProperties
+ + td:writeProperty
+
+
+
+

4.1.5 PropertyAffordance

+
+

IRI: + https://www.w3.org/2019/wot/td#PropertyAffordance

An + Interaction Affordance that exposes state of the Thing. + This state can then be retrieved (read) and/or updated + (write). Things can also choose to make Properties + observable by pushing the new state after a change. + + + + + + + + + + + + + + + +
Sub-class oftd:InteractionAffordance
In the domain oftd:isObservable
In the range oftd:hasPropertyAffordance
+
+
+
+

4.1.6 + Thing

+
+

IRI: + https://www.w3.org/2019/wot/td#Thing

An + abstraction of a physical or a virtual entity whose + metadata and interfaces are described by a WoT Thing + Description, whereas a virtual entity is the composition of + one or more Things. + + + + + + + +
In the domain oftd:baseURI
+ td:definesSecurityScheme
+ + td:description
+ td:descriptionInLanguage
+ + td:followsProfile
+ td:hasForm
+ td:hasInteractionAffordance
+ + td:hasSecurityConfiguration
+ + td:instance
+ td:model
+ td:title
+ td:titleInLanguage
+
+
+
+
+

4.2 Object Properties

+
+
+
+

4.2.1 definesSecurityScheme

+
+

IRI: + https://www.w3.org/2019/wot/td#definesSecurityScheme

A + Thing may define abstract security schemes, used to + configure the secure access of (a set of) + affordance(s). + + + + + + + +
Domain includestd:Thing
+
+
+
+

4.2.2 hasActionAffordance

+
+

IRI: + https://www.w3.org/2019/wot/td#hasActionAffordance

All + Action-based interaction affordance of the Thing. + + + + + + + +
Range includestd:ActionAffordance
+
+
+
+

4.2.3 hasCancellationSchema

+
+

IRI: + https://www.w3.org/2019/wot/td#hasCancellationSchema

Defines + any data that needs to be passed to cancel a subscription, + e.g., a specific message to remove a Webhook + + + + + + + +
Domain includestd:EventAffordance
+
+
+
+

4.2.4 + hasConfigurationInstance

+
+

IRI: + https://www.w3.org/2019/wot/td#hasConfigurationInstance

Instantiation, + as used here, is a form of non-symmetric equivalence + between a scheme and a configuration: whatever statement on + the scheme is also true of the configuration but not + vice-versa. + + + + + + + +
Domain includes + wotsec:SecurityScheme
+
+
+
+

4.2.5 hasEventAffordance

+
+

IRI: + https://www.w3.org/2019/wot/td#hasEventAffordance

All + Event-based interaction affordance of the Thing. + + + + + + + +
Range includestd:EventAffordance
+
+
+
+

4.2.6 + hasForm

+
+

IRI: + https://www.w3.org/2019/wot/td#hasForm

Set + of form hypermedia controls that describe how an operation + can be performed. Forms are serializations of Protocol + Bindings. The array cannot be empty + + + + + + + + + + + +
Domain includestd:InteractionAffordance
+ + td:Thing
Range includeshctl:Form
+
+
+
+

4.2.7 hasInputSchema

+
+

IRI: + https://www.w3.org/2019/wot/td#hasInputSchema

Used + to define the input data schema of the action. + + + + + + + +
Domain includestd:ActionAffordance
+
+
+
+

4.2.8 + hasInteractionAffordance

+
+

IRI: + https://www.w3.org/2019/wot/td#hasInteractionAffordance

Offers + an affordance to interact with the Thing + + + + + + + + + + + +
Domain includestd:Thing
Range includestd:InteractionAffordance
+
+ +
+
+

+ 4.2.10 + hasNotificationResponseSchema

+
+

IRI: + https://www.w3.org/2019/wot/td#hasNotificationResponseSchema

Defines + the data schema of the Event response messages sent by the + consumer in a response to a data message. + + + + + + + +
Domain includestd:EventAffordance
+
+
+
+

4.2.11 hasNotificationSchema

+
+

IRI: + https://www.w3.org/2019/wot/td#hasNotificationSchema

Defines + the data schema of the Event instance messages pushed by + the Thing. + + + + + + + +
Domain includestd:EventAffordance
+
+
+
+

4.2.12 hasOutputSchema

+
+

IRI: + https://www.w3.org/2019/wot/td#hasOutputSchema

Used + to define the output data schema of the action. + + + + + + + +
Domain includestd:ActionAffordance
+
+
+
+

4.2.13 hasPropertyAffordance

+
+

IRI: + https://www.w3.org/2019/wot/td#hasPropertyAffordance

All + Property-based interaction affordance of the Thing. + + + + + + + +
Range includestd:PropertyAffordance
+
+
+
+

4.2.14 + hasSecurityConfiguration

+
+

IRI: + https://www.w3.org/2019/wot/td#hasSecurityConfiguration

A + security configuration is a a security scheme applied to a + (set of) affordance(s). + + + + + + + +
Domain includeshctl:Form
+ + td:Thing
+
+
+
+

4.2.15 hasSubscriptionSchema

+
+

IRI: + https://www.w3.org/2019/wot/td#hasSubscriptionSchema

Defines + data that needs to be passed upon subscription, e.g., + filters or message format for setting up Webhooks. + + + + + + + +
Domain includestd:EventAffordance
+
+
+
+

4.2.16 hasUriTemplateSchema

+
+

IRI: + https://www.w3.org/2019/wot/td#hasUriTemplateSchema

Define + URI template variables according to [RFC6570] as collection based on + schema specifications. The individual variables DataSchema + cannot be an ObjectSchema or an ArraySchema. + + + + + + + +
Domain includestd:InteractionAffordance
+
+
+
+
+

4.3 Datatype Properties

+
+
+
+

4.3.1 + baseURI

+
+

IRI: + https://www.w3.org/2019/wot/td#baseURI

Define + the base URI that is used for all relative URI references + throughout a TD document. In TD instances, all relative + URIs are resolved relative to the base URI using the + algorithm defined in [RFC3986]. base does not affect the + URIs used in @context and the IRIs used within Linked Data + [LINKED-DATA] graphs that are relevant when semantic + processing is applied to TD instances. + + + + + + + + + + + +
Domain includestd:Thing
Range includesschema:URL
+
+
+
+

4.3.2 description

+
+

IRI: + https://www.w3.org/2019/wot/td#description

description + of the TD element (Thing, interaction affordance, security + scheme or data schema) + + + + + + + + + + + +
Domain includesjsonschema:DataSchema
+ + + wotsec:SecurityScheme
+ td:InteractionAffordance
+ + td:Thing
Range includesschema:Text
+
+
+
+

4.3.3 descriptionInLanguage

+
+

IRI: + https://www.w3.org/2019/wot/td#descriptionInLanguage

description + of the TD element (Thing, interaction affordance, security + scheme or data schema) with language tag. By convention, a + language tag must be added to the object of + 'descriptionInLanguage' triples. Otherwise, use + 'description'. + + + + + + + + + + + +
Domain includesjsonschema:DataSchema
+ + + wotsec:SecurityScheme
+ td:InteractionAffordance
+ + td:Thing
Range includesschema:Text
+
+
+
+

4.3.4 followsProfile

+
+

IRI: + https://www.w3.org/2019/wot/td#followsProfile

Indicates + the WoT Profile mechanisms followed by this Thing + Description and the corresponding Thing + implementation. + + + + + + + + + + + +
Domain includestd:Thing
Range includes
+
+
+
+

4.3.5 + instance

+
+

IRI: + https://www.w3.org/2019/wot/td#instance

Provides + a version identicator of this TD instance. + + + + + + + +
Domain includestd:Thing
+
+
+
+

4.3.6 isIdempotent

+
+

IRI: + https://www.w3.org/2019/wot/td#isIdempotent

Indicates + whether the action is idempotent (=true) or not. Informs + whether the action can be called repeatedly with the same + result, if present, based on the same input. + + + + + + + + + + + +
Domain includestd:ActionAffordance
Range includesschema:Boolean
+
+
+
+

4.3.7 isObservable

+
+

IRI: + https://www.w3.org/2019/wot/td#isObservable

A + hint that indicates whether Servients hosting the Thing and + Intermediaries should provide a Protocol Binding that + supports the observeproperty and + unobserveproperty operations for this + Property. + + + + + + + + + + + +
Domain includestd:PropertyAffordance
Range includesschema:Boolean
+
+
+
+

4.3.8 + isSafe

+
+

IRI: + https://www.w3.org/2019/wot/td#isSafe

Signals + if the action is safe (=true) or not. Used to signal if + there is no internal state (cf. resource state) is changed + when invoking an Action. In that case responses can be + cached as example. + + + + + + + + + + + +
Domain includestd:ActionAffordance
Range includesschema:Boolean
+
+
+
+

4.3.9 isSynchronous

+
+

IRI: + https://www.w3.org/2019/wot/td#isSynchronous

Indicates + whether the action is synchronous (=true) or not. A + synchronous action means that the response of action + contains all the information about the result of the action + and no further querying about the status of the action is + needed. Lack of this keyword means that no claim on the + synchronicity of the action can be made. + + + + + + + + + + + +
Domain includestd:ActionAffordance
Range includesschema:Boolean
+
+
+
+

4.3.10 + model

+
+

IRI: + https://www.w3.org/2019/wot/td#model

Provides + a version indicator of the underlying TM. + + + + + + + +
Domain includestd:Thing
+
+
+
+

4.3.11 + name

+
+

IRI: + https://www.w3.org/2019/wot/td#name

Indexing + property to store entity names when serializing them in + a JSON-LD @index container. + + + + + + + + + + + +
Domain includestd:InteractionAffordance
Range includesschema:Text
+
+
+
+

4.3.12 + title

+
+

IRI: + https://www.w3.org/2019/wot/td#title

title + of the TD element (Thing, interaction affordance or data + schema) + + + + + + + + + + + +
Domain includesjsonschema:DataSchema
+ + td:InteractionAffordance
+ + td:Thing
Range includesschema:Text
+
+
+
+

4.3.13 titleInLanguage

+
+

IRI: + https://www.w3.org/2019/wot/td#titleInLanguage

title + of the TD element (Thing, interaction affordance or data + schema) with language tag. By convention, a language tag + must be added to the object of 'titleInLanguage' triples. + Otherwise, use 'title'. + + + + + + + + + + + +
Domain includesjsonschema:DataSchema
+ + td:InteractionAffordance
+ + td:Thing
Range includesschema:Text
+
+
+
+
+

4.4 Annotation Properties

+
+
+
+

4.4.1 supportContact

+
+

IRI: + https://www.w3.org/2019/wot/td#supportContact

Provides + information about the TD maintainer as URI scheme (e.g., + mailto [RFC6068], tel + [RFC3966], + https[RFC9112]). +
+
+
+
+

4.4.2 versionInfo

+
+

IRI: + https://www.w3.org/2019/wot/td#versionInfo

Provides + version information. +
+
+
+
+
+

4.5 Named Individuals

+
+
+
+

4.5.1 cancelAction

+
+

IRI: + https://www.w3.org/2019/wot/td#cancelAction

Operation + type of forms used to cancel an action + + + + + + + +
Instance oftd:OperationType
+
+
+
+

4.5.2 invokeAction

+
+

IRI: + https://www.w3.org/2019/wot/td#invokeAction

Operation + type of forms used to read a property value + + + + + + + +
Instance oftd:OperationType
+
+
+
+

4.5.3 observeAllProperties

+
+

IRI: + https://www.w3.org/2019/wot/td#observeAllProperties

Operation + type of forms used to observe all property values + + + + + + + +
Instance oftd:OperationType
+
+
+
+

4.5.4 observeProperty

+
+

IRI: + https://www.w3.org/2019/wot/td#observeProperty

Operation + type of forms used to observe a property value + + + + + + + +
Instance oftd:OperationType
+
+
+
+

4.5.5 queryAction

+
+

IRI: + https://www.w3.org/2019/wot/td#queryAction

Operation + type of forms used to query the status of an action + + + + + + + +
Instance oftd:OperationType
+
+
+
+

4.5.6 queryAllActions

+
+

IRI: + https://www.w3.org/2019/wot/td#queryAllActions

Operation + type of forms used to query the status of all + actions + + + + + + + +
Instance oftd:OperationType
+
+
+
+

4.5.7 readAllProperties

+
+

IRI: + https://www.w3.org/2019/wot/td#readAllProperties

Operation + type of forms used to read all property values + + + + + + + +
Instance oftd:OperationType
+
+
+
+

4.5.8 readMultipleProperties

+
+

IRI: + https://www.w3.org/2019/wot/td#readMultipleProperties

Operation + type of forms used to read a property value + + + + + + + +
Instance oftd:OperationType
+
+
+
+

4.5.9 readProperty

+
+

IRI: + https://www.w3.org/2019/wot/td#readProperty

Operation + type of forms used to read a property value + + + + + + + +
Instance oftd:OperationType
+
+
+
+

4.5.10 subscribeAllEvents

+
+

IRI: + https://www.w3.org/2019/wot/td#subscribeAllEvents

Operation + type of forms used to subscribe to all event types + + + + + + + +
Instance oftd:OperationType
+
+
+
+

4.5.11 subscribeEvent

+
+

IRI: + https://www.w3.org/2019/wot/td#subscribeEvent

Operation + type of forms used to read a property value + + + + + + + +
Instance oftd:OperationType
+
+
+
+

4.5.12 unobserveAllProperties

+
+

IRI: + https://www.w3.org/2019/wot/td#unobserveAllProperties

Operation + type of forms used to unobserve all property value + + + + + + + +
Instance oftd:OperationType
+
+
+
+

4.5.13 unobserveProperty

+
+

IRI: + https://www.w3.org/2019/wot/td#unobserveProperty

Operation + type of forms used to unobserve a property value + + + + + + + +
Instance oftd:OperationType
+
+
+
+

4.5.14 unsubscribeAllEvents

+
+

IRI: + https://www.w3.org/2019/wot/td#unsubscribeAllEvents

Operation + type of forms used to unsubscribe from all event + types + + + + + + + +
Instance oftd:OperationType
+
+
+
+

4.5.15 unsubscribeEvent

+
+

IRI: + https://www.w3.org/2019/wot/td#unsubscribeEvent

Operation + type of forms used to read a property value + + + + + + + +
Instance oftd:OperationType
+
+
+
+

4.5.16 writeAllProperties

+
+

IRI: + https://www.w3.org/2019/wot/td#writeAllProperties

Operation + type of forms used to read a property value + + + + + + + +
Instance oftd:OperationType
+
+
+
+

4.5.17 + writeMultipleProperties

+
+

IRI: + https://www.w3.org/2019/wot/td#writeMultipleProperties

Operation + type of forms used to write a property value + + + + + + + +
Instance oftd:OperationType
+
+
+
+

4.5.18 writeProperty

+
+

IRI: + https://www.w3.org/2019/wot/td#writeProperty

Operation + type of forms used to write a property value + + + + + + + +
Instance oftd:OperationType
+
+
+
+
+
+

5. + Alignments

+
+

The TD ontology shares commonalities with other WoT-related + vocabularies, in particular with SOSA [vocab-ssn] and + schema.org. Alignments between + these vocabularies are provided in a human-readable way in the + following.

+
+
+

5.1 + SOSA

+
+

All alignments with SOSA are also available here in OWL: + td-sosa.ttl.

+

Alignment of td:Thing with SOSA:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Sub-ClassSuper-Class
td:Thingsosa:Sensor or
+ sosa:Actuator or
+ sosa:Platform or
+ sosa:FeatureOfInterest
td:Thing and
+ sosa:FeatureOfInterest		ssn:hasProperty some (
+ (sosa:isObservedBy + some sosa:Sensor) or
+ (sosa:isActedOnBy + some sosa:Actuator)
+ )
td:Thing and
+ sosa:Sensor		sosa:observes some
+ sosa:ObservableProperty
td:Thing and
+ sosa:Actuator		sosa:actsOnProperty some
+ sosa:ActuatableProperty
td:Thing and
+ sosa:Platform		sosa:hosts some (
+ (
+ sosa:Sensor and
+ sosa:observes + some
+ sosa:ObservableProperty
+ + ) or (
+ sosa:Actuator + and
+ sosa:actsOnProperty + some
+ sosa:ActuatableProperty
+ + )
+ )
+

Alignment of td:InteractionAffordance with + SOSA:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Sub-ClassSuper-Class
td:PropertyAffordance and
+ td:hasForm some
+ hctl:hasOperationType + value
+ td:readProperty		ssn:forProperty some + sosa:ObservableProperty
td:PropertyAffordance and
+ td:hasForm some
+ hctl:hasOperationType + value
+ td:writeProperty		ssn:forProperty some + sosa:ActuatableProperty
td:ActionAffordancessn:forProperty some
+ sosa:ActuatableProperty
td:EventAffordancessn:forProperty some
+ sosa:ObservableProperty
+
+
+
+

5.2 + Schema.org

+
+

The alignments with schema.org's actions are also + available here in OWL: td-sdo.ttl.

+ + + + + + + + + + + + + +
Sub-ClassSuper-Class
td:InteractionAffordanceschema:Action and
+ schema:actionStatus value schema:PotentialActionStatus
+
+ + + + + + + + + + + + + +
Sub-PropertySuper-Property
td:hasInteractionAffordanceschema:potentialAction
+
+
+
+
+

6. Usage + Examples

+
+
+
+

+ 6.1 Thing Description JSON-LD 1.1 + Instance to RDF Dataset

+
+

The following example shows a TD instance from + Example 1 Thing Description specification + [WOT-THING-DESCRIPTION] + in JSON-LD 1.1 (JSON-LD 1.1 tab) and in a RDF dataset (RDF + tab).

+ +

The RDF dataset contains the corresponding Thing + Description IRIs as defined in this document. This IRI + mapping is provided by the Thing Description context file + https://www.w3.org/2019/wot/td/v1. For instance, + the field actions is transformed to + <https://www.w3.org/2019/wot/td#hasActionAffordance>.

+
+
+
+

6.2 Merging Thing Descriptions

+
+

The following example includes two TD documents in the + standard TD JSON representation format [WOT-THING-DESCRIPTION], + identified by a unique electronic product code + [RFC5134].

+

If these two documents are being merged together with + contextual information in the form of an RDF graph that uses + the same identifiers, it is possible to retrieve form + metadata of these TDs depending on the relations that exist + between Things. Here, the two Things share information on + room 101 of some example building.

+ +
+
+
+

6.3 Internal State of a Thing

+
+

It is possible for affordances of different kinds to have + the same effect. For instance, an affordance to a writable + property may be equivalent to an affordance to invoke an + action that changes the property value. Similarly, for every + observable property, there may be an equivalent affordance to + subscribe to an event that occurs at every property value + change.

+

WoT clients can avoid having to deal with these + discrepancies by using the generic + td:hasInteractionAffordance predicate. They can + then decide to perform an action based solely on the + operation type of the form embedded in the affordance + object.

+ +
+
+
+

+ 6.4 Specifying Affordances by + Device Classes

+
+

It is possible to use the TD ontology to extend the + definition of well-known subclasses of Thing by + defining expected affordances that Things of such types + should present. The following example specifies that every + temperature sensor presents an affordance to a temperature + property (expressed in the SAREF vocabulary [smartM2M]).

+ +
+
+ +
+
+

A. + References

+
+
+
+

A.1 Normative references

+
+
+
[RFC3966]
+
+ The tel + URI for Telephone Numbers. H. Schulzrinne. + IETF. December 2004. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3966 +
+
[RFC5134]
+
+ A + Uniform Resource Name Namespace for the EPCglobal + Electronic Product Code (EPC) and Related + Standards. M. Mealling. IETF. January 2008. + Informational. URL: https://www.rfc-editor.org/rfc/rfc5134 +
+
[RFC6068]
+
+ The + 'mailto' URI Scheme. M. Duerst; L. Masinter; + J. Zawinski. IETF. October 2010. Proposed Standard. URL: + https://www.rfc-editor.org/rfc/rfc6068 +
+
[RFC6570]
+
+ URI + Template. J. Gregorio; R. Fielding; M. Hadley; + M. Nottingham; D. Orchard. IETF. March 2012. Proposed + Standard. URL: https://www.rfc-editor.org/rfc/rfc6570 +
+
[RFC9112]
+
+ HTTP/1.1. + R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.. + IETF. June 2022. Internet Standard. URL: https://httpwg.org/specs/rfc9112.html +
+
[shacl]
+
+ Shapes + Constraint Language (SHACL). Holger Knublauch; + Dimitris Kontokostas. W3C. 20 July 2017. W3C + Recommendation. URL: https://www.w3.org/TR/shacl/ +
+
[smartM2M]
+
+ + ETSI TS 103 264 V2.1.1 (2017-03): SmartM2M; Smart + Appliances; Reference Ontology and oneM2M + Mapping. ETSI. March 2017. Published. URL: + + http://www.etsi.org/deliver/etsi_ts/103200_103299/103264/02.01.01_60/ts_103264v020101p.pdf +
+
[vocab-ssn]
+
+ Semantic + Sensor Network Ontology. Armin Haller; + Krzysztof Janowicz; Simon Cox; Danh Le Phuoc; Kerry + Taylor; Maxime Lefrançois. W3C. 19 October 2017. W3C + Recommendation. URL: https://www.w3.org/TR/vocab-ssn/ +
+
[WOT-ARCHITECTURE]
+
+ Web of + Things (WoT) Architecture. Matthias Kovatsch; + Ryuichi Matsukura; Michael Lagally; Toru Kawaguchi; + Kunihiko Toumura; Kazuo Kajimoto. W3C. 9 April 2020. W3C + Recommendation. URL: https://www.w3.org/TR/wot-architecture/ +
+
+ [WOT-THING-DESCRIPTION]
+
+ Web + of Things (WoT) Thing Description. Sebastian + Käbisch; Takuki Kamiya; Michael McCool; Victor Charpenay; + Matthias Kovatsch. W3C. 9 April 2020. W3C Recommendation. + URL: https://www.w3.org/TR/wot-thing-description/ +
+
+
+
+ + + + + + + + + + + + + + + + + + + + diff --git a/publication/ver11/7-resources/ontology/tidiedFiles/tm.html b/publication/ver11/7-resources/ontology/tidiedFiles/tm.html new file mode 100644 index 000000000..beae79519 --- /dev/null +++ b/publication/ver11/7-resources/ontology/tidiedFiles/tm.html @@ -0,0 +1,1208 @@ + + + + + + + + + Web of Things (WoT) Thing Model (TM) Ontology + + + + + + + + + +
+

+

Web of Things (WoT) Thing Model + (TM) Ontology

+

W3C Editor's Draft +

+
+ + More details about this document + +
+
This version:
+
+ https://www.w3.org/2019/wot/td +
+
Latest published version:
+
none
+
Latest editor's draft:
+
+ https://www.w3.org/2019/wot/td +
+
Editors:
+
+ Mahda Noura (Siemens + AG) +
+
+ Sebastian Käbisch + (Siemens AG) +
+
Ontology in RDF
+
+ Web of Things (WoT) Thing Model (TM) + Ontology in RDF +
+
+
+

Copyright © 2023 + World Wide Web Consortium. + W3C® + liability, + trademark and + permissive + document license rules apply.

+
+
+
+

Abstract

+

The Thing Model (TM) ontology is an RDF axiomatization of + the TM concepts, one of the building blocks of the Web of + Things (WoT). Besides providing an alternative to the standard + JSON representation format for TM documents, the TM ontology + can also be used to process contextual information on Things + and for alignments with other WoT-related ontologies.

+
+
+

Status of This Document

+

This section describes the status of this document at + the time of its publication. A list of current W3C publications and the + latest revision of this technical report can be found in the + W3C technical reports + index at https://www.w3.org/TR/.

+

This document was published by the Web of Things Working + Group as an Editor's Draft.

+

Publication as an Editor's Draft does not imply endorsement + by W3C and its + Members.

+

This is a draft document and may be updated, replaced or + obsoleted by other documents at any time. It is inappropriate + to cite this document as other than work in progress.

+

This document was produced by a group operating under the + W3C Patent Policy. + W3C maintains a + public list of any + patent disclosures made in connection with the deliverables + of the group; that page also includes instructions for + disclosing a patent. An individual who has actual knowledge of + a patent which the individual believes contains Essential + Claim(s) must disclose the information in accordance with + section + 6 of the W3C + Patent Policy.

+

This document is governed by the 03 November 2023 + W3C Process + Document.

+
+ +
+
+

1. + Introduction

+
+

The TM ontology is an idiomatic RDF axiomatization of the + TM + concepts , which can be used as a template for + instantiating Thing Descriptions (TD)s. The TM ontology imports + the TD + ontology.

+
+
+
+

2. + Conformance

+
+

As well as sections marked as non-normative, all authoring + guidelines, diagrams, examples, and notes in this specification + are non-normative. Everything else in this specification is + normative.

+

The key word MUST in this document + is to be interpreted as described in BCP 14 + [RFC2119] + [RFC8174] + when, and only when, they appear in all capitals, as shown + here.

+
+
+
+

3. + Terminology

+
+

The fundamental WoT terminology such as Thing, Consumer, Thing + Description (TD), Interaction Model, Interaction + Affordance, Property, Action, Event, Protocol Binding, Servient, etc. is defined in + Section + 3 of the WoT Architecture specification [WOT-ARCHITECTURE].

+

The Thing Description terminology such as TD Information + Model, TD + Document, Term (Vocabulary Term), etc. is defined in + Section + 3 of the WoT Thing Description specification + [WOT-THING-DESCRIPTION].

+
+
+
+

4. + Axiomatization

+
+
+
+

4.1 + Classes

+
+
+
+

4.1.1 + ThingModel

+
+

IRI: + https://www.w3.org/2019/wot/tm#ThingModel

A + Thing Model is a description for a class of Things that + have the same capabilities. It describes the Properties, + Actions, and Events and common metadata that are shared for + an entire group of Things. Compared to a Thing Description, + a Thing Model does not contain enough information to + identify or interact with a Thing instance. + + + + + + + +
In the domain oftd:description
+ + td:hasLink
+ + td:title
+ + tm:hasVersion
+ tm:optional
+ tm:required
+
+
+
+

4.1.2 + Version

+
+

IRI: + https://www.w3.org/2019/wot/tm#Version

The + Version is a container that provides versioning information + for the Thing Model definition. + + + + + + + + + + + +
In the domain oftm:model
In the range oftm:hasVersion
+
+
+
+
+

4.2 Object Properties

+
+
+
+

4.2.1 + hasVersion

+
+

IRI: + https://www.w3.org/2019/wot/tm#hasVersion

Provides + the relation between a Thing Model and its version. + + + + + + + + + + + +
Domain includestm:ThingModel
Range includestm:Version
+
+
+
+
+

4.3 Datatype Properties

+
+
+
+

4.3.1 + model

+
+

IRI: + https://www.w3.org/2019/wot/tm#model

Provides + a version indicator of the underlying TM. + + + + + + + + + + + +
Domain includestm:Version
Range includesschema:Text
+
+
+
+

4.3.2 + optional

+
+

IRI: + https://www.w3.org/2019/wot/tm#optional

Constraint + that provides references to declarations in the Thing Model + that are optional and do not necessarily need to be + implemented when Thing Description instances are derived + from this Thing Model. The value of tm:optional MUST provide JSON Pointer [RFC6901] + references to the required interaction model + definitions. + + + + + + + + + + + +
Domain includestm:ThingModel
Range includesschema:Text
+
+
+
+

4.3.3 + ref

+
+

IRI: + https://www.w3.org/2019/wot/tm#ref

Provides + a reference to an existing (external or local) definition + that is copied into a newly defined definition. The + reference value is based on three parts: an (optional) + URI-reference (used for external reference), '#' sign, and + JSON Pointer [RFC6901] value. + + + + + + + + + + + +
Domain includes + td:InteractionAffordance
Range includesschema:Text
+
+
+
+

4.3.4 + required

+
+

IRI: + https://www.w3.org/2019/wot/tm#required

Constraint + that provides references to declarations in the Thing Model + that are mandatory and must be present when Thing + Description instances are derived from this Thing Model. + The reference value is a JSON Pointer [RFC6901]. + + + + + + + + + + + +
Domain includestm:ThingModel
Range includesschema:Text
+
+
+
+
+

4.4 Annotation Properties

+
+
+
+

4.4.1 versionInfo

+
+

IRI: + https://www.w3.org/2019/wot/tm#versionInfo

Provides + version information of the TM ontology. +
+
+
+
+ +
+
+

A. + References

+
+
+
+

A.1 Normative references

+
+
+
[RFC2119]
+
+ Key words + for use in RFCs to Indicate Requirement + Levels. S. Bradner. IETF. March 1997. Best + Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119 +
+
[RFC8174]
+
+ Ambiguity + of Uppercase vs Lowercase in RFC 2119 Key + Words. B. Leiba. IETF. May 2017. Best Current + Practice. URL: https://www.rfc-editor.org/rfc/rfc8174 +
+
[WOT-ARCHITECTURE]
+
+ Web of + Things (WoT) Architecture. Matthias Kovatsch; + Ryuichi Matsukura; Michael Lagally; Toru Kawaguchi; + Kunihiko Toumura; Kazuo Kajimoto. W3C. 9 April 2020. W3C + Recommendation. URL: https://www.w3.org/TR/wot-architecture/ +
+
+ [WOT-THING-DESCRIPTION]
+
+ Web + of Things (WoT) Thing Description. Sebastian + Käbisch; Takuki Kamiya; Michael McCool; Victor Charpenay; + Matthias Kovatsch. W3C. 9 April 2020. W3C Recommendation. + URL: https://www.w3.org/TR/wot-thing-description/ +
+
+
+
+ + + + + + + + + + + + + + + + + + + + diff --git a/publication/ver11/7-resources/ontology/tidiedFiles/wotsec.html b/publication/ver11/7-resources/ontology/tidiedFiles/wotsec.html new file mode 100644 index 000000000..104d0212b --- /dev/null +++ b/publication/ver11/7-resources/ontology/tidiedFiles/wotsec.html @@ -0,0 +1,2149 @@ + + + + + + + + + + Web of Things (WoT) Security Ontology + + + + + + + + + +
+

+

Web of Things (WoT) Security + Ontology

+

W3C Editor's Draft +

+
+ + More details about this document + +
+
This version:
+
+ https://www.w3.org/2019/wot/security +
+
Latest published version:
+
none
+
Latest editor's draft:
+
+ https://www.w3.org/2019/wot/security +
+
Editors:
+
Victor Charpenay
+
Michael McCool
+
Ontology in RDF
+
+ Web of Things (WoT) Security + Ontology in RDF +
+
+
+

Copyright © 2023 + World Wide Web Consortium. + W3C® + liability, + trademark and + permissive + document license rules apply.

+
+
+
+

Abstract

+

This document introduces an RDF vocabulary for the security + metadata definitions. This vocabulary provides a stable + namespace IRI for security keywords, as well as simple axioms, + defined against schema.org's meta-model. Examples on how to use + the vocabulary are also introduced.

+
+
+

Status of This Document

+

This section describes the status of this document at + the time of its publication. A list of current W3C publications and the + latest revision of this technical report can be found in the + W3C technical reports + index at https://www.w3.org/TR/.

+

This document was published by the Web of Things Working + Group as an Editor's Draft.

+

Publication as an Editor's Draft does not imply endorsement + by W3C and its + Members.

+

This is a draft document and may be updated, replaced or + obsoleted by other documents at any time. It is inappropriate + to cite this document as other than work in progress.

+

This document was produced by a group operating under the + W3C Patent Policy. + W3C maintains a + public list of any + patent disclosures made in connection with the deliverables + of the group; that page also includes instructions for + disclosing a patent. An individual who has actual knowledge of + a patent which the individual believes contains Essential + Claim(s) must disclose the information in accordance with + section + 6 of the W3C + Patent Policy.

+

This document is governed by the 03 November 2023 + W3C Process + Document.

+
+ +
+
+

1. + Introduction

+
+

This documents provides an ontology of 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]). However while the + HTTP security schemes, Vocabulary, and syntax given in this + specification share many similarities with OpenAPI, they are + not compatible.

+
+
+
+

2. + Conformance

+
+

As well as sections marked as non-normative, all authoring + guidelines, diagrams, examples, and notes in this specification + are non-normative. Everything else in this specification is + normative.

+

The key words MAY, MUST, MUST NOT, + SHOULD, and SHOULD + NOT in this document are to be interpreted as described in + BCP + 14 [RFC2119] + [RFC8174] + when, and only when, they appear in all capitals, as shown + here.

+
+
+
+

3. + Terminology

+
+

The fundamental WoT terminology such as Thing, Consumer, Thing + Description (TD), Interaction Model, Interaction + Affordance, Property, Action, Event, Protocol + Binding, Servient, etc. is defined in Section + 3 of the WoT Architecture specification [WOT-ARCHITECTURE].

+

The Thing Description terminology such as TD Information + Model, TD + Document, Term (Vocabulary Term), TD Context + Extension etc. is defined in Section + 3 of the WoT Thing Description specification + [WOT-THING-DESCRIPTION].

+
+
+
+

4. + Axiomatization

+
+
+
+

4.1 + Classes

+
+
+
+

4.1.1 APIKeySecurityScheme

+
+

IRI: + https://www.w3.org/2019/wot/security#APIKeySecurityScheme

API + key authentication security configuration identified by the + term apikey (i.e., "scheme": + "apikey"). This scheme is to be used when the access + token is opaque, for example when a key in a 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 of service requests + using the mechanism indicated by the "in" + field. + + + + + + + + + + + +
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:in
+ wotsec:name
+
+
+
+

4.1.2 AutoSecurityScheme

+
+

IRI: + https://www.w3.org/2019/wot/security#AutoSecurityScheme

An + automatic authentication security configuration identified + by the term auto (i.e., "scheme": + "auto"). This scheme indicates that the security + parameters are going to be negotiated by the underlying + protocols at runtime, subject to the respective + specifications for the protocol (e.g. [RFC8288] for Basic Authentication + when using HTTP). + + + + + + + +
Sub-class ofwotsec:SecurityScheme
+
+
+
+

4.1.3 BasicSecurityScheme

+
+

IRI: + https://www.w3.org/2019/wot/security#BasicSecurityScheme

Basic + authentication security configuration identified by the + term basic (i.e., "scheme": + "basic"), using an unencrypted username and + password. + + + + + + + + + + + +
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:in
+ wotsec:name
+
+
+
+

4.1.4 BearerSecurityScheme

+
+

IRI: + https://www.w3.org/2019/wot/security#BearerSecurityScheme

Bearer + token authentication security configuration identified by + the term bearer (i.e., "scheme": + "bearer"). This scheme is intended for situations + where bearer tokens are used independently of OAuth2. If + the oauth2 scheme is specified it is not + generally necessary to specify this scheme as well as it is + implied. For format, the value + jwt indicates conformance with RFC7519, + jws indicates conformance with RFC7797, + cwt indicates conformance with RFC8392, and + jwe indicates conformance with !RFC7516, with + values for alg interpreted consistently with + those standards. Other formats and + algorithms for bearer tokens MAY + be specified in vocabulary extensions. + + + + + + + + + + + +
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:alg
+ wotsec:authorization
+ wotsec:format
+ wotsec:in
+ wotsec:name
+
+
+
+

4.1.5 ComboSecurityScheme

+
+

IRI: + https://www.w3.org/2019/wot/security#ComboSecurityScheme

+

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.

+ + + + + + + + + + + +
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:allOf
+ wotsec:oneOf
+
+
+
+

4.1.6 DigestSecurityScheme

+
+

IRI: + https://www.w3.org/2019/wot/security#DigestSecurityScheme

Digest + authentication security configuration identified by the + term digest (i.e., "scheme": + "digest"). This scheme is similar to basic + authentication but with added features to avoid + man-in-the-middle attacks. + + + + + + + + + + + +
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:in
+ wotsec:name
+ wotsec:qop
+
+
+
+

4.1.7 NoSecurityScheme

+
+

IRI: + https://www.w3.org/2019/wot/security#NoSecurityScheme

A + security configuration corresponding to identified by the + term nosec (i.e., "scheme": + "nosec"), indicating there is no authentication or + other mechanism required to access the resource. + + + + + + + +
Sub-class ofwotsec:SecurityScheme
+
+
+
+

4.1.8 OAuth2SecurityScheme

+
+

IRI: + https://www.w3.org/2019/wot/security#OAuth2SecurityScheme

+

OAuth 2.0 authentication security configuration + for systems conformant with [RFC6749] + and [RFC8252], identified + by the Vocabulary Term + oauth2 (i.e., "scheme": + "oauth2"). For the code + flow both authorization and token + MUST be included. + For the + client flow token MUST be included. For the + client flow authorization + MUST NOT be included. The + mandatory elements for each flow are summarized in the + following table:

+ + + + + + + + + + + + + + + + + + + + + + + +
Elementcodeclient
authorizationmandatoryomit
tokenmandatorymandatory
refreshoptionaloptional
+ + + + + + + + + + + +
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:authorization
+ wotsec:flow
+ wotsec:refresh
+ wotsec:scopes
+ wotsec:token
+
+
+
+

4.1.9 PSKSecurityScheme

+
+

IRI: + https://www.w3.org/2019/wot/security#PSKSecurityScheme

Pre-shared + key authentication security configuration identified by the + 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], + and that the ciphersuite used for keys will be established + during protocol negotiation. + + + + + + + + + + + +
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:identity
+
+
+
+

4.1.10 SecurityScheme

+
+

IRI: + https://www.w3.org/2019/wot/security#SecurityScheme

+

Metadata describing the configuration of a + security mechanism. The value assigned to the name + scheme MUST be defined within + a Vocabulary included in + the Thing Description, + either in the standard Vocabulary defined in + § 5. TD Information Model or in a TD Context + Extension.

+

For all security schemes, any + keys, passwords, or other sensitive information directly + providing access MUST NOT be stored + in the TD and should instead be shared and stored + out-of-band via other mechanisms. 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.

+

Each security scheme object used in a TD defines a set + of requirements to be met before access can be granted. We + say a security scheme is satisfied when all its + requirements are met. In some cases requirements from + multiple security schemes will have to be met before access + can be granted.

+

Security schemes generally may require additional + authentication parameters, such as a password or key. The + location of this information is indicated by the value + associated with the name in, often in + combination with the value associated with + name. The in name can take one of + the following values:

+
+
header:
+
The parameter will be given 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 query parameter provided + by name.
+
body:
+
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. 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. Since + this value is not a fragment identifier, it also does not + need to URL-encode special characters. The targeted + element may or may not already exist at the specified + location in the referenced data schema. If it does not, + it will be inserted. This avoids having to duplicate + definitions in the data schemas of every interaction. + 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 be possible to + insert the indicated element at the location indicated by + the pointer.. For example, pointing to a key of a + Map where that key does not exist in the corresponding + Data Schema, the key and its value, which is the + credential, would be inserted to the Map at the specified + location during the operation execution. On the other + hand, pointing to an Array's item with a number as the + item index, that number should be outside the range of + the Array's already specified items in order to not alter + the strict sequence of items. The JSON pointer 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 body security information + location 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 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 for in in a security scheme only + if query is not applicable. + The URIs provided in + interactions where a security scheme using + uri MUST be a URI + template including the defined variable.
+
auto:
+
The location is determined as part of the protocol, + or negotiated. If a value of + auto is set for the in field of + a SecurityScheme, then the name + field SHOULD NOT be set. + In this case, the application of the + SecurityScheme is subject to the respective + specification for the given protocol (e.g. + [RFC8288] + when using the BasicSecurityScheme with + HTTP).
+
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 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 declared in the TD.

+ + + + + + + + + + + +
Super-class ofwotsec:APIKeySecurityScheme
+ + wotsec:AutoSecurityScheme
+ + wotsec:BasicSecurityScheme
+ + wotsec:BearerSecurityScheme
+ + wotsec:ComboSecurityScheme
+ + wotsec:DigestSecurityScheme
+ + wotsec:NoSecurityScheme
+ + wotsec:OAuth2SecurityScheme
+ + wotsec:PSKSecurityScheme
In the domain ofwotsec:proxy
+ td:description
+ + + td:descriptionInLanguage
+ + td:hasConfigurationInstance
+
+
+
+
+

4.2 Object Properties

+
+
+
+

4.2.1 + allOf

+
+

IRI: + https://www.w3.org/2019/wot/security#allOf

Array + of two or more strings identifying other named security + scheme definitions, all of which must be satisfied for + access. + + + + + + + +
Domain includeswotsec:ComboSecurityScheme
+
+
+
+

4.2.2 authorization

+
+

IRI: + https://www.w3.org/2019/wot/security#authorization

URI + of the authorization server. + + + + + + + +
Domain includeswotsec:BearerSecurityScheme
+ + wotsec:OAuth2SecurityScheme
+
+
+
+

4.2.3 + oneOf

+
+

IRI: + https://www.w3.org/2019/wot/security#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. + + + + + + + +
Domain includeswotsec:ComboSecurityScheme
+
+
+
+

4.2.4 + refresh

+
+

IRI: + https://www.w3.org/2019/wot/security#refresh

URI + of the refresh server. + + + + + + + +
Domain includeswotsec:OAuth2SecurityScheme
+
+
+
+

4.2.5 + token

+
+

IRI: + https://www.w3.org/2019/wot/security#token

URI + of the token server. + + + + + + + +
Domain includeswotsec:OAuth2SecurityScheme
+
+
+
+
+

4.3 Datatype Properties

+
+
+
+

4.3.1 + alg

+
+

IRI: + https://www.w3.org/2019/wot/security#alg

Encoding, + encryption, or digest algorithm. + + + + + + + +
Domain includeswotsec:BearerSecurityScheme
+
+
+
+

4.3.2 + in

+
+

IRI: + https://www.w3.org/2019/wot/security#apikeyIn

Specifies + the location of security authentication information. + + + + + + + +
Domain includeswotsec:APIKeySecurityScheme
+
+
+
+

4.3.3 + flow

+
+

IRI: + https://www.w3.org/2019/wot/security#flow

Authorization + flow. + + + + + + + +
Domain includeswotsec:OAuth2SecurityScheme
+
+
+
+

4.3.4 + format

+
+

IRI: + https://www.w3.org/2019/wot/security#format

Specifies + format of security authentication information. + + + + + + + +
Domain includeswotsec:BearerSecurityScheme
+
+
+
+

4.3.5 + identity

+
+

IRI: + https://www.w3.org/2019/wot/security#identity

Identifier + providing information which can be used for selection or + confirmation. + + + + + + + +
Domain includeswotsec:PSKSecurityScheme
+
+
+
+

4.3.6 + in

+
+

IRI: + https://www.w3.org/2019/wot/security#in

Specifies + the location of security authentication information. + + + + + + + +
Domain includeswotsec:BasicSecurityScheme
+ + wotsec:BearerSecurityScheme
+ + wotsec:DigestSecurityScheme
+
+
+
+

4.3.7 + name

+
+

IRI: + https://www.w3.org/2019/wot/security#name

Name + for query, header, cookie, or uri parameters. + + + + + + + +
Domain includeswotsec:APIKeySecurityScheme
+ + wotsec:BasicSecurityScheme
+ + wotsec:BearerSecurityScheme
+ + wotsec:DigestSecurityScheme
+
+
+
+

4.3.8 + proxy

+
+

IRI: + https://www.w3.org/2019/wot/security#proxy

URI + of the proxy server this security configuration provides + access to. If not given, the corresponding security + configuration is for the endpoint.
+ This feature is at risk. + + + + + + + + + + + +
Domain includeswotsec:SecurityScheme
Range includes
+
+
+
+

4.3.9 + qop

+
+

IRI: + https://www.w3.org/2019/wot/security#qop

Quality + of protection.
+ This feature is at risk. + + + + + + + +
Domain includeswotsec:DigestSecurityScheme
+
+
+
+

4.3.10 + scopes

+
+

IRI: + https://www.w3.org/2019/wot/security#scopes

Set + of authorization scope identifiers provided as an array. + These are provided in tokens returned by an authorization + server and associated with forms in order to identify what + resources a client may access and how. The values + associated with a form should be chosen from those defined + in an OAuth2SecurityScheme active on that + form.
+ This feature is at risk. + + + + + + + +
Domain includeswotsec:OAuth2SecurityScheme
+
+
+
+
+

4.4 Annotation Properties

+
+

No AnnotationProperty found in the ontology.

+
+
+
+
+

5. Usage + Examples

+
+
+
+

5.1 Extended Configuration

+
+ +
+
+ +
+
+

A. + References

+
+
+
+

A.1 Normative references

+
+
+
[RFC2119]
+
+ Key words + for use in RFCs to Indicate Requirement + Levels. S. Bradner. IETF. March 1997. Best + Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119 +
+
[rfc4279]
+
+ Pre-Shared + Key Ciphersuites for Transport Layer Security + (TLS). P. Eronen, Ed.; H. Tschofenig, Ed.. + IETF. December 2005. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc4279 +
+
[RFC6749]
+
+ The OAuth + 2.0 Authorization Framework. D. Hardt, Ed.. + IETF. October 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6749 +
+
[RFC6901]
+
+ JavaScript + Object Notation (JSON) Pointer. P. Bryan, Ed.; + K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed + Standard. URL: https://www.rfc-editor.org/rfc/rfc6901 +
+
[RFC8174]
+
+ Ambiguity + of Uppercase vs Lowercase in RFC 2119 Key + Words. B. Leiba. IETF. May 2017. Best Current + Practice. URL: https://www.rfc-editor.org/rfc/rfc8174 +
+
[RFC8252]
+
+ OAuth 2.0 + for Native Apps. W. Denniss; J. Bradley. IETF. + October 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8252 +
+
[RFC8288]
+
+ Web + Linking. M. Nottingham. IETF. October 2017. + Proposed Standard. URL: https://httpwg.org/specs/rfc8288.html +
+
[WOT-ARCHITECTURE]
+
+ Web of + Things (WoT) Architecture. Matthias Kovatsch; + Ryuichi Matsukura; Michael Lagally; Toru Kawaguchi; + Kunihiko Toumura; Kazuo Kajimoto. W3C. 9 April 2020. W3C + Recommendation. URL: https://www.w3.org/TR/wot-architecture/ +
+
+ [WOT-THING-DESCRIPTION]
+
+ Web + of Things (WoT) Thing Description. Sebastian + Käbisch; Takuki Kamiya; Michael McCool; Victor Charpenay; + Matthias Kovatsch. W3C. 9 April 2020. W3C Recommendation. + URL: https://www.w3.org/TR/wot-thing-description/ +
+
+
+
+
+

A.2 Informative references

+
+
+
[OPENAPI]
+
+ OpenAPI + Specification. Darrell Miller; Jeremy + Whitlock; Marsh Gardiner; Mike Ralphson; Ron Ratovsky; + Uri Sarid; Tony Tam; Jason Harmon. OpenAPI Initiative. + URL: https://www.openapis.org/ +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + From 146568adaadfbb0dcf19cefd018a924495287716 Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Wed, 17 Jan 2024 19:55:20 +0100 Subject: [PATCH 43/43] mention last step of ontology html --- publication/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/publication/README.md b/publication/README.md index 6602a851e..a2bb449c5 100644 --- a/publication/README.md +++ b/publication/README.md @@ -65,3 +65,4 @@ When publishing the REC version, you need to do additional steps: * Set static publication date for ontology HTML versions * Check for the date or version within JSON Schema files * Generate static versions of the ontology HTML files + * Generate tidied versions of the ontology HTML files