WIP: Common constraints - identifiers #271
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -643,12 +643,15 @@ <h2>Security</h2> | |
| </ul> | ||
| </div> | ||
| <p><span class="rfc2119-assertion" id="common-constraints-security-2"> | ||
| Conformant Consumers MUST support at least all of these security schemes.</span> | ||
| </p> | ||
|
|
||
| <p><span class="rfc2119-assertion" id="common-constraints-security-3"> | ||
| A Thing MAY implement multiple security schemes.</span> | ||
| </p> | ||
| <p><span class="rfc2119-assertion" id="common-constraints-security-4"> | ||
| A Thing MUST support at least one of the above security schemes.</span> | ||
| </p> | ||
|
|
||
| <p><span class="rfc2119-assertion" id="common-constraints-security-6"> | ||
| Conformant Consumers MUST support security bootstrapping for all | ||
|
|
@@ -901,7 +904,7 @@ <h3>Media Types for Link Targets</h3> | |
|
|
||
| <!-- Errors --> | ||
| <section id="common-constraints-errors"> | ||
| <h3 id="error-responses">Errors</h3> | ||
| <p> | ||
| <span class="rfc2119-assertion" id="common-constraints-errors-1"> | ||
| If any of the operations defined in the protocol bindings of HTTP | ||
|
|
@@ -920,6 +923,7 @@ <h2 id="error-responses">Errors</h2> | |
| <li><code>403 Forbidden</code></li> | ||
| <li><code>404 Not Found</code></li> | ||
| <li><code>500 Internal Server Error</code></li> | ||
| <li><code>503 Service Unavailable</code></li> | ||
| </ul> | ||
| </div> | ||
| <p> | ||
|
|
@@ -956,6 +960,56 @@ <h2>Default Language</h2> | |
| (e.g., en, de-AT, gsw-CH, zh-Hans, zh-Hant-HK, sl-nedis).</span> | ||
| </span> | ||
| </section> | ||
| <section id="sec-identifiers"> | ||
| <h2>Identifiers</h2> | ||
| <p> | ||
| Web resources are identified by uniform resource identifiers (URIs). | ||
| The Thing Description defines the field <a href="https://w3c.github.io/wot-thing-description/#thing><code>id</code></a> | ||
| for that purpose, which is in the format "anyURI". | ||
| </p> | ||
| <p> | ||
| In deployments of multiple devices in the same application context, things must be distinguished by the consumer. | ||
| In these cases, these identifiers must be <em>unique</em>. | ||
| Use cases with worldwide deployments typically require <em>globally</em> unique identifiers. | ||
| </p> | ||
| <section id="sec-identifiers-format"> | ||
| <h3>Format</h3> | ||
| <p> | ||
| A common and well defined format for these identifiers enables easy implementation | ||
| and simplifies handling across manufacturers through the use of libraries. | ||
| It also ensures that there are no name clashes of devices from different manufacturers. | ||
| The [[UUID]] format has been developed to satisfy these requirements. | ||
| </p> | ||
| <p> | ||
| <span class="rfc2119-assertion" id="common-constraints-identifiers-uuid"> | ||
| It is RECOMMENDED to use Universally Unique IDentifier (UUID) [[RFC4122]] as common format for identifers. | ||
| </span> | ||
| </p> | ||
| <span class="rfc2119-assertion" id="common-constraints-identifiers-random"> | ||
| It is RECOMMENDED to use [[UUIDv4]] as common format for unique identifers, where random identifiers are required. | ||
| </span> | ||
| </p> | ||
| </section> | ||
| <section id="sec-identifiers-mutability"> | ||
| <h3>Mutable and Immutable Identifiers</h3> | ||
| <p> | ||
| Many use cases require that identifiers do not change during the lifecycle of the thing in the application context. | ||
| However there are cases, where the IDs must change due to legal or privacy obligations. | ||
| IDs should be changed when a device is offboarded and onboarded on a new system (e.g. for change | ||
| of ownership). | ||
| In these cases, or when a device is moved to a new usage context, identifiers usually must change. | ||
| </p> | ||
|
|
||
| <p><span class="rfc2119-assertion" id="common-constraints-identifiers-mutable"> | ||
| In certain use cases where privacy is a factor or legal obligations mandate changing identifiers, | ||
| the use of a <em>mutable UUID</em> is RECOMMENDED.</span> | ||
| </p> | ||
|
|
||
| <p><span class="rfc2119-assertion" id="common-constraints-identifiers-immutable-ids"> | ||
| If possible and allowed by law, required immutable IDs SHOULD be made available through a | ||
| property rather than used as the id for the TD itself. | ||
| </span></p> | ||
| </section> | ||
|
Comment on lines
+995
to
+1012
There was a problem hiding this comment. This is already covered in section 11.2 Immutable Identifiers of TD 1.1. I don't think this text really adds anything to that text. There was a problem hiding this comment. This goes beyond what the TD describes in section 11.2. The proposed text talks specifically about UUIDs, i.e. a format this is well-defined, whereas the TD does not have any format description for identifiers. |
||
| </section> | ||
|
|
||
|
|
||
|
|
@@ -1667,7 +1721,18 @@ <h6 id="async-action-response">Asynchronous Action Response</h6> | |
| "timeRequested": "2021-11-10T11:43:19.135Z" | ||
| } | ||
| </pre> | ||
| <div class="rfc2119-assertion" id="http-basic-profile-protocol-binding-invokeaction-22"> | ||
| <p> | ||
| In resource constrained environments, the ActionStatus objects of older completed/failed actions MAY be deleted to make room for newly invoked actions. | ||
| </p> | ||
| </div> | ||
| <div class="rfc2119-assertion" id="http-basic-profile-protocol-binding-invokeaction-23"> | ||
| <p> | ||
| A Web Thing SHOULD return a <code>503</code> error response if the invocation cannot be accepted because the action is unavailable, | ||
| e.g. because the Thing is overloaded. | ||
| </p> | ||
| </div> | ||
| </section> | ||
|
|
||
| <section id="http-basic-profile-protocol-binding-queryaction"> | ||
| <h5><code>queryaction</code></h5> | ||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm pleased to see that this is only a recommendation, however:
In WebThings we still use the URL of the Thing Description as its ID, which has many benefits.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The URL is not stable in scenarios where things may transition between different networks. Think of roaming scenarios in fleet management, IP reassignment cases etc.