diff --git a/.github/workflows/prettify.yml b/.github/workflows/prettify.yml index e875b8f8c..b16d71f76 100644 --- a/.github/workflows/prettify.yml +++ b/.github/workflows/prettify.yml @@ -23,7 +23,8 @@ jobs: uses: actions/checkout@v3 with: # Make sure the actual branch is checked out when running on pull requests - ref: ${{ github.head_ref }} + ref: ${{ github.event.pull_request.head.ref }} + repository: ${{ github.event.pull_request.head.repo.full_name }} # This is important to fetch the changes to the previous commit fetch-depth: 0 diff --git a/ontology/td.html b/ontology/td.html index 846c503a0..a7443a3f4 100644 --- a/ontology/td.html +++ b/ontology/td.html @@ -119,10 +119,10 @@

Terminology

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:descriptionInLanguage
td:followsProfile
td:hasForm
td:hasInteractionAffordance
td:hasSecurityConfiguration
td:instance
td:model
td:titleInLanguage

Object Properties

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

hasActionAffordance

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

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

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
-

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

hasEventAffordance

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

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

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

hasInputSchema

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

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

hasInstanceConfiguration

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

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

hasInteractionAffordance

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

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

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
diff --git a/ontology/td.ttl b/ontology/td.ttl index a27083a52..3d27fb186 100644 --- a/ontology/td.ttl +++ b/ontology/td.ttl @@ -130,8 +130,8 @@ schema:domainIncludes :Thing ; rdfs:isDefinedBy . -:hasConfigurationInstance rdf:type owl:ObjectProperty ; - rdfs:label "hasConfigurationInstance" ; +:hasInstanceConfiguration rdf:type owl:ObjectProperty ; + rdfs:label "hasInstanceConfiguration" ; rdfs:comment "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." ; schema:domainIncludes wotsec:SecurityScheme ; rdfs:isDefinedBy . diff --git a/ontology/wotsec.html b/ontology/wotsec.html index 4ab05f4ca..2c8cc1d83 100644 --- a/ontology/wotsec.html +++ b/ontology/wotsec.html @@ -95,7 +95,7 @@

Terminology

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: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:descriptionInLanguage
td:hasInstanceConfiguration

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