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

Jump to bottom

addresses CR 1.1 candidate review from Oracle #1558

Merged
merged 20 commits into from Aug 17, 2022
Merged

addresses CR 1.1 candidate review from Oracle #1558

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
5343c87
addresses Oracle CR 1.1 candidate review
sebastiankb Jun 29, 2022
3541f02
vocabulary terms and values MUST be case sensitive
sebastiankb Jun 29, 2022
8041ce4
reword all logic for the security array
egekorkan Jul 13, 2022
5294d11
add text that forms cannot be empty
egekorkan Jul 13, 2022
7c5b333
explain required usage
egekorkan Jul 13, 2022
4a6e103
add rfcs for the support text
egekorkan Jul 13, 2022
6bffaf4
fix rogue keywords in versioninfo
egekorkan Jul 13, 2022
a858811
remove ed note from thing models
egekorkan Jul 13, 2022
3e16a90
add assertion on validity of TD according to its TM
egekorkan Jul 13, 2022
ba5fcaa
Merge branch 'main' into oracle-review-11cr
egekorkan Aug 10, 2022
8688f92
reremove rogue words and render again
egekorkan Aug 10, 2022
06d1574
reword private keys assertion
egekorkan Aug 10, 2022
8ffd81c
propagate changes to index.html
egekorkan Aug 10, 2022
87ca92a
revert sec credentials part
egekorkan Aug 10, 2022
d5b9b2b
remove assertion about case sensitive
egekorkan Aug 17, 2022
b207961
revert the assertion text on security array
egekorkan Aug 17, 2022
faf3b2e
revert and thus wording
egekorkan Aug 17, 2022
9e4890c
remove issue note
egekorkan Aug 17, 2022
21866d6
rewordings
egekorkan Aug 17, 2022
3e2ba00
rewordings for security all
egekorkan Aug 17, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
81 changes: 29 additions & 52 deletions index.html
View file
Open in desktop
Expand Up @@ -1167,7 +1167,7 @@ <h2>Class Definitions</h2>
</p>

<p>
Please note that all vocabulary terms and values are case sensitive.
In particular, note that all vocabulary terms and values are case sensitive.
This is also true for the serialization of the information model (Section <a href="#sec-td-serialization"></a>).
egekorkan marked this conversation as resolved.
Show resolved Hide resolved
</p>

Expand All @@ -1194,10 +1194,9 @@ <h2>Core Vocabulary Definitions</h2>
<tr class="rfc2119-table-assertion" id="td-vocab-modified--Thing"><td><code>modified</code></td><td>Provides information when the TD instance was
last modified.</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#dateTime"><code>dateTime</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-support--Thing"><td><code>support</code></td><td>Provides information about the TD maintainer as
URI scheme (e.g., <code>mailto</code>
[<cite><a class="bibref" data-link-type="biblio" href='#bib-rfc6068' title="The 'mailto' URI Scheme">RFC6068</a></cite>],
<code>tel</code> [<cite><a class="bibref" data-link-type="biblio" href='#bib-rfc3966' title="The tel URI for Telephone Numbers">RFC3966</a></cite>],
<code>https</code>).</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr>
URI scheme (e.g., <code>mailto</code> [[RFC6068]],
<code>tel</code> [[RFC3966]],
<code>https</code> [[RFC9112]]).</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-base--Thing"><td><code>base</code></td><td>Define the base URI that is used for all
relative URI references throughout a TD document.
In TD instances, all relative URIs are resolved
Expand Down Expand Up @@ -1227,8 +1226,7 @@ <h2>Core Vocabulary Definitions</h2>
serializations of Protocol Bindings. Thing-level forms are used to describe endpoints for a group of interaction affordances.</td><td>optional</td><td><a>Array</a> of <a href="#form"><code>Form</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-security--Thing"><td><code>security</code></td><td>Set of security definition names, chosen from
those defined in <code>securityDefinitions</code>.
These must all be satisfied for access to
resources.</td><td>mandatory</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> or <a>Array</a> of <a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
These must all be satisfied for access to resources.</td><td>mandatory</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> or <a>Array</a> of <a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-securityDefinitions--Thing"><td><code>securityDefinitions</code></td><td>Set of named security configurations
(definitions only). Not actually applied unless
names are used in a <code>security</code>
Expand Down Expand Up @@ -1512,9 +1510,9 @@ <h2>Core Vocabulary Definitions</h2>
definitions outside of the TD namespace) can be extended
via the <a href="#dfn-context-ext" class="internalDFN" data-link-type="dfn">TD Context Extension</a>
mechanism.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Assignment</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-instance--VersionInfo"><td><code>instance</code></td><td>Provides a version indicator of this TD.
instance.</td><td>mandatory</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
</td><td>mandatory</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-model--VersionInfo"><td><code>model</code></td><td>Provides a version indicator of the underlying TM.
instance.</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table><p>It is recommended that the values within <code>instances</code> and <code>model</code> of
</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table><p>It is recommended that the values within <code>instances</code> and <code>model</code> of
the <code>VersionInfo</code> <a href="#dfn-class" class="internalDFN" data-link-type="dfn">Class</a> follow the
semantic versioning pattern, where a sequence of three
numbers separated by a dot indicates the major version,
Expand Down Expand Up @@ -1694,8 +1692,7 @@ <h2>Data Schema Vocabulary Definitions</h2>
This <a href="#dfn-subclass" class="internalDFN" data-link-type="dfn">Subclass</a> is indicated by the
value <code>object</code> assigned to <code>type</code>
in <code>DataSchema</code> instances.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Assignment</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-properties--ObjectSchema"><td><code>properties</code></td><td>Data schema nested definitions.</td><td>optional</td><td><a>Map</a> of <a href="#dataschema"><code>DataSchema</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-required--ObjectSchema"><td><code>required</code></td><td>Defines which members of the object type are
mandatory.</td><td>optional</td><td><a>Array</a> of <a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
<tr class="rfc2119-table-assertion" id="td-vocab-required--ObjectSchema"><td><code>required</code></td><td>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 <code>invokeaction</code>, <code>writeproperty</code>) and what members will be definitely delivered in the payload that is being received (e.g. output of <code>invokeaction</code>, <code>readproperty</code>)</td><td>optional</td><td><a>Array</a> of <a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
<section><h3><code>StringSchema</code></h3><p>Metadata describing data of type <code>string</code>.
This <a href="#dfn-subclass" class="internalDFN" data-link-type="dfn">Subclass</a> is indicated by the
value <code>string</code> assigned to <code>type</code>
Expand Down Expand Up @@ -2205,8 +2202,7 @@ <h2>Hypermedia Controls Vocabulary Definitions</h2>
include "gzip", "deflate", etc. .</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-security--Form"><td><code>security</code></td><td>Set of security definition names, chosen from
those defined in <code>securityDefinitions</code>.
These must all be satisfied for access to
resources.</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> or <a>Array</a> of <a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
These must all be satisfied for access to resources.</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> or <a>Array</a> of <a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-scopes--Form"><td><code>scopes</code></td><td>Set of authorization scope identifiers provided
as an array. These are provided in tokens returned
by an authorization server and associated with
Expand Down Expand Up @@ -5090,12 +5086,6 @@ <h3>Example II: State Annotations</h3>
<section id="semantic-annotations-example-geoloc">
<h3>Example III: Geolocation Annotations</h3>

<p class="issue">
This new subsection is in work in progress. Examples will be updated based on experience
of the next PlugFests.
</p>


<p>
For many use cases like in building, agriculture, or smart city location based data is required. This
information can be provided in the Thing Description in different ways and can be relied on
Expand Down Expand Up @@ -5754,22 +5744,17 @@ <h4>Other Protocol Bindings</h4>

<section id="thing-model" class="normative">
<h1>Thing Model</h1>

<p class="note">
The following section has its origin in [[wot-thing-description]], Annex C. Here Thing Description
Template is renamed to <a>Thing Model</a>, but keeps the same intention.
For this version of the specification, <a>Thing Model</a> and its model features (e.g., extensions, referencing, obligations, placeholder) are formal
introduced. For Thing Model, an own content type is under discussion. Please note this section is in work in progress.
</p>

<section id="thing-model-concept" class="normative">
<h2>Basic Concept</h2>

<p>
The figure below illustrates the relation of the <a>Thing Model</a> and <a>Thing Description</a>. A <a>Thing Model</a> mainly describes
interaction affordances such as the <a>Properties</a>, <a>Actions</a>, and <a>Events</a> and common metadata. This kind of template should
be valid and followed for all instantiated <a>Thing Descriptions</a> that are relied on this <a>Thing Model</a>. This paradigm can be compared
with abstract class or interface definition (~Thing Model) in object-oriented programming to create objects (~Thing Descriptions).
The figure below illustrates the relation of the <a>Thing Model</a> and <a>Thing Description</a>.
A <a>Thing Model</a> mainly describes interaction affordances such as the <a>Properties</a>, <a>Actions</a>, and <a>Events</a> and common metadata.
<span class="rfc2119-assertion" id="tm-derivation-validity">
When a <a>Thing Descriptions</a> is instantiated by relying on a Thing Model, it SHOULD be valid according to that Thing Model.
</span>
This paradigm can be compared with abstract class or interface definition (~Thing Model) in object-oriented programming to create objects (~Thing Descriptions).
</p>

<figure id="thing-model-td">
Expand Down Expand Up @@ -7079,11 +7064,10 @@ <h5>Script Injection</h5>
<dl><dt>Mitigation:</dt><dd>
Strings sourced from TDs should be treated like any other source of external string
when generating HTML: with care.
<span class="rfc2119-assertion" id="sec-inj-sanitize">
Strings sourced from TDs MUST either be sanitized using a carefully vetted HTML
sanitizer that disables any markup or should be inserted into an HTML template using
DOM node manipulation APIs that will escape any markup.
</span>
As a matter of policy, it is strongly suggested that
strings sourced from TDs either be sanitized using a carefully vetted HTML
sanitizer that disables any markup or be inserted into an HTML template using
DOM node manipulation APIs that will escape any markup.
It is also possible that strings sourced from TDs could be used to generate documents
in other markup languages, such as MD files or XML.
Such usages should take equivalent
Expand Down Expand Up @@ -7194,18 +7178,14 @@ <h5>Context Fetching</h5>
The set of supported extensions can be established by a
WoT Profile [[WOT-PROFILE]], for example.
<span class="rfc2119-assertion" id="security-static-context">
Constrained implementations SHOULD use statically managed and vetted
versions of their supported context extensions.
</span>
Constrained implementations SHOULD use vetted
versions of their supported context extensions
managed statically or as part of a secure update process.</span>
<span class="rfc2119-assertion" id="security-remote-context">
Constrained implementations SHOULD NOT follow links to remote contexts.
</span>
In this case the URLs are used only to identify extensions,
not to fetch their definitions.
<span class="rfc2119-assertion" id="security-update-contexts">
Supported context extensions on constrained implementations MAY be managed
through secure software update mechanisms.
</span>
</dd>
</dl>
</section>
Expand All @@ -7222,17 +7202,15 @@ <h5>Immutable Identifiers</h5>
<dl><dt>Mitigation:</dt><dd>
<span class="rfc2119-assertion" id="privacy-mutable-identifiers">
All identifiers used in a TD SHOULD be mutable,
and in particular there should be a mechanism to update the <code>id</code>
and in particular there SHOULD be a mechanism to update the <code>id</code>
of a <a>Thing</a> when necessary.
</span>
Specifically,
the <code>id</code> of a <a>Thing</a> should not be fixed in hardware.
This does, however, conflict with the Linked Data ideal that
identifiers are fixed URIs.
However,
<span class="rfc2119-assertion" id="privacy-mutable-id-ownership">TD
identifiers SHOULD be updated upon major changes in configuration
or reinitialization.</span>
However, as a matter of policy, it is strongly suggested that deployments
update identifiers upon major changes in configuration or reinitialization.
Examples of major changes in configuration include moving a Thing to a new
local area network, assigning a new domain name,
or unregistering the Thing from one hub and registering it with a new
Expand Down Expand Up @@ -7361,11 +7339,10 @@ <h5>Inferencing of Personally Identifiable Information</h5>
which can lead to additional inferences about that person.
</p>
<dl><dt>Mitigation:</dt><dd>
<span class="rfc2119-assertion" id="privacy-td-pii">
A Thing Description associated with a
personal device SHOULD be treated as if it contained
personally identifiable information, even if this information is not explicit.
</span>
As a matter of policy, it is strongly suggested that
Thing Descriptions associated with
personal devices be treated as if they contained
personally identifiable information, even if this information is not explicit.
As an example application of this principle,
consider how to obtain user consent.
Consent for usage of personally identifiable data
Expand Down
27 changes: 8 additions & 19 deletions index.template.html
View file
Open in desktop
Expand Up @@ -1167,7 +1167,7 @@ <h2>Class Definitions</h2>
</p>

<p>
Please note that all vocabulary terms and values are case sensitive.
In particular, note that all vocabulary terms and values are case sensitive.
This is also true for the serialization of the information model (Section <a href="#sec-td-serialization"></a>).
</p>
egekorkan marked this conversation as resolved.
Show resolved Hide resolved

Expand Down Expand Up @@ -3818,12 +3818,6 @@ <h3>Example II: State Annotations</h3>
<section id="semantic-annotations-example-geoloc">
<h3>Example III: Geolocation Annotations</h3>

<p class="issue">
This new subsection is in work in progress. Examples will be updated based on experience
of the next PlugFests.
</p>


<p>
For many use cases like in building, agriculture, or smart city location based data is required. This
information can be provided in the Thing Description in different ways and can be relied on
Expand Down Expand Up @@ -4482,22 +4476,17 @@ <h4>Other Protocol Bindings</h4>

<section id="thing-model" class="normative">
<h1>Thing Model</h1>

<p class="note">
The following section has its origin in [[wot-thing-description]], Annex C. Here Thing Description
Template is renamed to <a>Thing Model</a>, but keeps the same intention.
For this version of the specification, <a>Thing Model</a> and its model features (e.g., extensions, referencing, obligations, placeholder) are formal
introduced. For Thing Model, an own content type is under discussion. Please note this section is in work in progress.
</p>

<section id="thing-model-concept" class="normative">
<h2>Basic Concept</h2>

<p>
The figure below illustrates the relation of the <a>Thing Model</a> and <a>Thing Description</a>. A <a>Thing Model</a> mainly describes
interaction affordances such as the <a>Properties</a>, <a>Actions</a>, and <a>Events</a> and common metadata. This kind of template should
be valid and followed for all instantiated <a>Thing Descriptions</a> that are relied on this <a>Thing Model</a>. This paradigm can be compared
with abstract class or interface definition (~Thing Model) in object-oriented programming to create objects (~Thing Descriptions).
The figure below illustrates the relation of the <a>Thing Model</a> and <a>Thing Description</a>.
A <a>Thing Model</a> mainly describes interaction affordances such as the <a>Properties</a>, <a>Actions</a>, and <a>Events</a> and common metadata.
<span class="rfc2119-assertion" id="tm-derivation-validity">
When a <a>Thing Descriptions</a> is instantiated by relying on a Thing Model, it SHOULD be valid according to that Thing Model.
</span>
This paradigm can be compared with abstract class or interface definition (~Thing Model) in object-oriented programming to create objects (~Thing Descriptions).
</p>

<figure id="thing-model-td">
Expand Down Expand Up @@ -5945,7 +5934,7 @@ <h5>Immutable Identifiers</h5>
<dl><dt>Mitigation:</dt><dd>
<span class="rfc2119-assertion" id="privacy-mutable-identifiers">
All identifiers used in a TD SHOULD be mutable,
and in particular there should be a mechanism to update the <code>id</code>
and in particular there SHOULD be a mechanism to update the <code>id</code>
of a <a>Thing</a> when necessary.
</span>
Specifically,
Expand Down