Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WIP: Common constraints - identifiers #271

Open
wants to merge 38 commits into
base: main
Choose a base branch
from
Open

WIP: Common constraints - identifiers #271

Changes from 1 commit
Commits
Show all changes
38 commits
Select commit Hold shift + click to select a range
4cea12f
1st draft
Sep 2, 2022
3da07f2
Fix the Errors heading level
lu-zero Feb 13, 2023
63566cd
Update Explainer.md
mlagally Feb 16, 2023
a96e5b7
Update index.html
mlagally Feb 16, 2023
2178fa8
Merge branch 'main' into common-constraints-identifiers
mlagally Feb 16, 2023
168ea37
Merge pull request #365 from w3c/mlagally-explainer-remove-duplicate-…
mlagally Feb 22, 2023
5bbd014
Clarify the security constraints for HTTP
lu-zero Feb 13, 2023
439d590
Merge pull request #364 from luminem/security-http-sections
mlagally Feb 22, 2023
01775c4
Add 503 as suggested error code
lu-zero Mar 2, 2023
6d78636
Clarify the default behaviour for async actions
lu-zero Mar 2, 2023
2b3f6eb
Further clarifications
lu-zero Mar 2, 2023
d1f6d5c
Merge pull request #371 from luminem/async-action-clarifications
mlagally Mar 8, 2023
468504f
1st draft
Sep 2, 2022
dff873c
Update index.html
mlagally Feb 16, 2023
f9a8466
update after Day 1 of testfest
mmccool Dec 13, 2022
4722758
add categories
mmccool Dec 13, 2022
80cdc18
update after Day 2 of testfest
mmccool Dec 13, 2022
85fabaa
fixed (impl->pass) node-wot results
mmccool Dec 14, 2022
6ec32e7
add clarification on the server behavior of the Consumer
egekorkan Dec 21, 2022
546c207
revert commit
egekorkan Dec 21, 2022
6f364c2
remove atrisk markup from WD
mmccool Dec 21, 2022
918b63b
add clarification on server behavior of webhook consumer
egekorkan Dec 21, 2022
ddc0431
update static.html and Overview.html
Jan 18, 2023
5b0fb49
update static.html and Overview with HTML reference
Jan 18, 2023
79e501a
update static.html and Overview.html again
Jan 18, 2023
92c7ff8
update static.html and Overview.html with https
Jan 18, 2023
b997349
Update Explainer.md
mlagally Feb 1, 2023
46beaf3
Update Explainer.md
mlagally Feb 1, 2023
557aa5e
Update Explainer.md
mlagally Feb 8, 2023
b00a59f
Update Explainer.md
mlagally Feb 8, 2023
9dce595
Update Explainer.md
mlagally Feb 8, 2023
7ece752
Remove trailing whitespaces
lu-zero Feb 13, 2023
65e2524
Merge branch 'common-constraints-identifiers' of https://github.com/w…
mlagally Mar 22, 2023
90cbf97
fixing rebase problems
mlagally Mar 22, 2023
29283c3
intermediate rebase w/o identifier section
mlagally Mar 22, 2023
4b1b5fb
fixing rebase problem
mlagally Mar 22, 2023
4d3e683
fixing rebase problem
mlagally Mar 22, 2023
c61cf48
rebase problem
mlagally Mar 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1854,6 +1854,53 @@ <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 <code>id</code> for that purpose, which is in the format "anyURI".
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reference needed for "anyURI" (or the id member in TD which in turn has a reference for "anyURI")

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

reference was added.

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>
Comment on lines +984 to +986
Copy link
Member

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:

  1. A UUID is not a URI. Do you perhaps mean a URN?
  2. Can you explain why a URN is a better globally unique identifier than an HTTP URL with a fully qualified domain name and therefore a URN should be recommended over that?

In WebThings we still use the URL of the Thing Description as its ID, which has many benefits.

Copy link
Contributor Author

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.

</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>Unique Identifiers</h3>
Copy link
Member

@benfrancis benfrancis Sep 7, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this title be "Mutable Identifiers", or "Immutable Identifiers"?

Copy link
Contributor Author

@mlagally mlagally Feb 16, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both are valid titles, I combined them.

<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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>


Expand Down