Skip to content

Commit

Permalink
Merge pull request #79 from benfrancis/profile-mechanism
Browse files Browse the repository at this point in the history 
New Profile Mechanism section
  • Loading branch information
@mlagally
mlagally authored Jun 23, 2021
2 parents f3a4d11 + d1933e4 commit 8da1330
Showing 1 changed file with 60 additions and 165 deletions.
225 changes: 60 additions & 165 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@
background-color: rgb(230,230,230)
}
</style>

</head>

<body>
Expand Down Expand Up @@ -179,7 +179,7 @@ <h3>Motivation for a Profile</h3>
WoT Thing Description [[wot-thing-description]] define a
powerful description mechanism and a format to describe
myriads of very different devices, which may be connected
over various protocols.
over various protocols.
</span>
The format is very flexible and open
and puts very few normative requirements on devices that
Expand Down Expand Up @@ -473,154 +473,49 @@ <h4 id="additional-definitions-">Additional Definitions:</h4>
</section>

<!-- Profiling mechanism -->

<section id="profiling-mechanism">
<h2 id="the-profiling-profile">Profiling Mechanism</h2>
<h2>Profiling Mechanism</h2>
<p>
This section describes a generic mechanism to define a
profile of the <a>WoT Thing Description</a> in a unambiguous way.
In order to conform with a profile, a
<a href="https://www.w3.org/TR/wot-architecture/#dfn-thing">Web Thing</a>
MUST conform with all the normative statements in the profile's specification.
</p>
<p>
The W3C <a>WoT Thing Description</a> specification defines a
formal language, i.e. a set of vocabulary terms (keywords),
a set of classes that are built from these keywords, and a
set of additional rules, that define constraints on
permitted values and keyword presence (mandatory / optional)
dependent on the context where the keyword is used. In
addition the <a>WoT Thing Description</a> specification defines relationships and
corresponding cardinalities between these classes.
In order to denote that a given
<a href="https://www.w3.org/TR/wot-architecture/#dfn-thing">Web Thing</a>
conforms to one or more profiles, its Thing Description MUST include a
<a href="https://w3c.github.io/wot-thing-description/#thing">
<code>profile</code></a> member [[wot-thing-description]]. The value of
the <code>profile</code> member MUST be set to either a valid URI
[[RFC3986]] identifying a single profile, or an array of valid URIs
identifying multiple profiles.
</p>
<p>
The <a>WoT Thing Description</a> specification already has some constraints,
but there is a wide variety of variations that are left to
the interpretation or the discretion of an implementer. The
rationale for the <a>Core Profile</a> is not to forbid
complex things, rather to enable statements like:
</p>

<ul>
<li><cite>If you constrain your TD to the <a>Core
Profile</a>, all other devices that conform the <a>Core
Profile</a> can interoperate with it out of the box.
</cite></li>
<li><cite>If you have additional needs your
device is free to implement other profiles or
add-ons at your own choice, but other devices that
only implement the <a>Core Profile</a> will most
likely not be able to use these additions.”
</cite></li>
</ul>

<section>
<h3 id="profile-description-methodology">Methodology</h3>

<p>
A profile is a set of constraints and rules, which
provide additional semantic guarantees that are applied
to the <a>WoT Thing Description</a> specification. These constraints define a
subset of valid <a>WoT Thing Descriptions</a> by defining
additional rules on various aspects of the <a>WoT Thing
Description</a> specification.
</p>

<table class="def">
<tr>
<th>Constraints on</th>
<th>Rationale</th>
<th>Example</th>
</tr>
<tr>
<td>vocabulary of Thing Description classes</td>
<td>guaranteed set of metadata fields</td>
<td>Make specific vocabulary terms mandatory,
remove others</td>
</tr>
<tr>
<td>class relationships</td>
<td>unambiguous structure</td>
<td>limited cardinality, e.g. only one form per
operation per interaction affordance.</td>
</tr>
<tr>
<td>values of vocabulary terms</td>
<td>simplified processing</td>
<td>Limit the length of characters per string.
Always use arrays, where the spec permits a
string or an array of strings.</td>
</tr>
<tr>
<td>data schemas</td>
<td>simplified processing</td>
<td>No arbitrary nested objects or arrays of
arrays</td>
</tr>
<tr>
<td>security</td>
<td>reduced implementation effort</td>
<td>Only a restricted set of security
mechanisms</td>
</tr>
<tr>
<td>protocol binding</td>
<td>guaranteed protocol semantics</td>
<td>limited protocol(s) and protocol features,
Example: predefined mapping of http verbs (GET/PUT) to
operation verbs, similar constraints for other protocols.</td>
</tr>
</table>


<p>These constraints and rules fall into two categories:</p>
<ul>
<li>constraints for the data model.</li>
<li>constraints for the protocol binding.</li>
</ul>

<p>These two categories are orthogonal to each other,
i.e. a data model that conforms to a profile can be
mapped to different protocols.
<span class="rfc2119-assertion" id="profile-4.1-profiling-mechanism-methodology-1">
The protocol binding for
each protocol may contain additional (protocol-specific)
constraints.
</span>
</p>

<p>
<span class="rfc2119-assertion" id="profile-4.1-profiling-mechanism-methodology-2">
A profile is not exclusive, i.e. a thing may conform
to multiple profiles.
</span>
Profiles can build on top of each
other or overlap, extended profiles can be built on top
of the core profile.</p>
<p>
This specification does not put any requirements on the
scope and contents of other profiles.
</p>

<figure id="WoT-Profiles">
<img src="images/WoT Profiles.png" class="wot-profiles" alt="WoT Profiles" />
<figcaption>WoT Core Profile - Other Profiles</figcaption>
</figure>

<p>
In the present document, we define a <a>Core Profile</a>
by defining a <a>Core Data Model</a> and a set of <a href="#protocol-binding">Protocol Binding</a> Rules
for selected protocols.
<!--
In the present version of this document we define a mapping to
HTTP(S). It is envisioned, that future versions of this document
contain additional mapping to Web Sockets and other protocols.
-->
</p>
</section>
<pre class="example">
{
"@context": "https://www.w3.org/2019/wot/td/v1",
"id": "urn:dev:ops:32473-WoTLamp-1234",
"profile": "https://www.w3.org/2021/wot/profile/core",
"title": "My Lamp",
"description": "A web connected lamp",
...
}
</pre>
<pre class="example">
{
"@context": "https://www.w3.org/2019/wot/td/v1",
"id": "urn:dev:ops:32473-WoTLamp-1234",
"profile": [
"https://www.w3.org/2021/wot/profile/core",
"https://www.w3.org/2021/wot/profile/constrained"
],
"title": "My Lamp",
"description": "A web connected lamp",
...
}
</pre>
</section>


<!-- <a>Core Profile</a> -->


<section id="core-profile">
<h2>WoT Core Profile</h2>
This section defines the <a>Core Profile</a> by defining a <a>Core
Expand Down Expand Up @@ -739,7 +634,7 @@ <h4>Length and Value Limits</h4>
<code>string</code>
or
<code>number</code>
.
.
</span>
<span class="rfc2119-assertion" id="profile-5.1.1.2-wot-core-data-model-length-and-value-Limits-5">
Different types in a single
Expand Down Expand Up @@ -852,7 +747,7 @@ <h5 id="recommended-practice-">Recommended
<span class="rfc2119-assertion" id="profile-5.1.2.1-thing-mandatory-fields-2">
If a Thing Description is used solely within
a company, the email address of the developer
SHOULD be used in the support field,
SHOULD be used in the support field,
</span>
<span class="rfc2119-assertion" id="profile-5.1.2.1-thing-mandatory-fields-3">
if the Thing Description is provided externally, a support email
Expand All @@ -862,13 +757,13 @@ <h5 id="recommended-practice-">Recommended

<section class="note">
<p>
<span class="rfc2119-assertion" id="profile-5.1.2.1-thing-mandatory-fields-4">
<span class="rfc2119-assertion" id="profile-5.1.2.1-thing-mandatory-fields-4">
It will be evaluated whether the profile also recommends some new TD terms that may be
introduced in TD 1.1.
introduced in TD 1.1.
</span>
Currently the following terms are discussed: serialNumber,
hardwareRevision, softwareRevision, loc_latitude, loc_longitude
loc_altitude, loc_height, and loc_depth.
loc_altitude, loc_height, and loc_depth.
<span class="rfc2119-assertion" id="profile-5.1.2.1-mandatory-fields-5">
If these, or some of them, are defined in the TD
1.1 model, they may be recommended here in one of the next draft updates.
Expand Down Expand Up @@ -907,7 +802,7 @@ <h4 id="constraints-against-the-td-specification">Data
The <a>Core Data Model</a> restricts the use of
arrays and objects to the <strong>top level</strong>
of Data Schemas, i.e. only a one-level hierarchy is
permitted.
permitted.
<span class="rfc2119-assertion" id="profile-5.1.3-thing-data-schema-1">
The members of a top level
<code>object</code>
Expand All @@ -918,10 +813,10 @@ <h4 id="constraints-against-the-td-specification">Data
</p>
<section class="note" title="RATIONALE">
<p>
<span class="rfc2119-assertion" id="profile-5.1.3-thing-data-schema-2">
<span class="rfc2119-assertion" id="profile-5.1.3-thing-data-schema-2">
This may appear as a severe limitation,
however it is motivated by integrating with
multiple cloud services.
multiple cloud services.
</span>
Many enterprise services and applications are based on
(relational) databases, where individual
Expand Down Expand Up @@ -1044,15 +939,15 @@ <h4>Additional Constraints</h4>
The <em>Thing Description</em> permits arbitrary
object depths for properties. Parsing of a
deeply nested structure is not possible on
resource constrained devices.
resource constrained devices.
<span class="rfc2119-assertion" id="profile-5.1.4.2-thing-property-affordance-additional-constraints-1">
Therefore each
property MUST NOT exceed a maximum depth
property MUST NOT exceed a maximum depth
of 5 levels of nested
<code>array</code>
or
<code>object</code>
elements. It is RECOMMENDED to keep the nesting
elements. It is RECOMMENDED to keep the nesting
of these elements below 4.
</span>
</p>
Expand Down Expand Up @@ -1152,7 +1047,7 @@ <h4>Recommended Practice</h4>
<p>
It is highly RECOMMENDED to always specify a
<code>unit</code>
, if a value has a metric.
, if a value has a metric.
<span class="rfc2119-assertion" id="profile-5.1.4.3-thing-properties-recommended-practice-1">
Authors of <em>Thing Descriptions</em> should be aware, that units
that are common in their geographic region are
Expand All @@ -1173,8 +1068,8 @@ <h4>Recommended Practice</h4>
<code>hex</code>
or
<code>bin</code>
,
<span class="rfc2119-assertion" id="profile-5.1.4.3-thing-properties-recommended-practice-2">
,
<span class="rfc2119-assertion" id="profile-5.1.4.3-thing-properties-recommended-practice-2">
to indicate how the value should be
interpreted. It is strongly RECOMMENDED to use
the values
Expand Down Expand Up @@ -1354,7 +1249,7 @@ <h3 id="x5-event-affordance">Event Affordance</h3>
class of section 5.3.1.5 of the <a>WoT Thing Description</a> Specification.

<p>
<span class="rfc2119-assertion" id="profile-5.1.6-thing-event-affordance-1">
<span class="rfc2119-assertion" id="profile-5.1.6-thing-event-affordance-1">
A <a>Thing</a> may provide more than one event
mechanism to enable a variety of consumers.
</span>
Expand Down Expand Up @@ -1461,7 +1356,7 @@ <h4>Additional Constraints</h4>
<section>
<h3 id="forms">Forms</h3>
<p>
<span class="rfc2119-assertion" id="profile-5.1.7-thing-forms-1">
<span class="rfc2119-assertion" id="profile-5.1.7-thing-forms-1">
A <a>Thing</a> may provide more than one event
mechanism to enable a variety of consumers.
</span>
Expand Down Expand Up @@ -1574,7 +1469,7 @@ <h3 id="security">Security</h3>
<span class="rfc2119-assertion" id="profile-5.1.9-thing-security-1">
The <a>Core Data Model</a> defines a subset of the
security schemes that MAY be implemented on resource
constrained devices.
constrained devices.
</span>
<span class="rfc2119-assertion" id="profile-5.1.9-thing-security-2">
A security scheme MUST be
Expand All @@ -1590,8 +1485,8 @@ <h3 id="security">Security</h3>
The set of security schemes supported in the <a>Core
Data Model</a> is based on the PlugFest results.
<span class="rfc2119-assertion" id="profile-5.1.9-thing-security-4">
To ensure interoperability, a TD consumer, which
compliant with the <a>Core Data Model</a> MUST
To ensure interoperability, a TD consumer, which
compliant with the <a>Core Data Model</a> MUST
support <strong>all</strong> of the following security schemes:
</span>
</p>
Expand Down Expand Up @@ -1937,7 +1832,7 @@ <h5><code>invokeaction</code></h5>
</span>
</p>
<p class="ednote">
The response to invoking an action needs to be defined.
The response to invoking an action needs to be defined.
<span class="rfc2119-assertion" id="profile-5.2.2.1-thing-protocol-binding-actions-invokeaction-4">
Given not all actions can be completed within the
timeout period of an HTTP response, this may need to include a
Expand Down Expand Up @@ -2009,15 +1904,15 @@ <h4>Error Responses</h4>
<p>
<span class="rfc2119-assertion" id="profile-5.2.4-thing-protocol-binding-error-responses-2">
Web Things MAY respond with other valid HTTP error codes
(e.g. <code>418 I'm a teapot</code>),
(e.g. <code>418 I'm a teapot</code>),
</span>
<span class="rfc2119-assertion" id="profile-5.2.4-thing-protocol-binding-error-responses-3">
but Consumers MAY interpret those error codes as a generic <code>4xx</code> or <code>5xx</code>
error with no special defined behaviour.
</span>
</p>
<p class="ednote">
<span class="rfc2119-assertion" id="profile-5.2.4-thing-protocol-binding-error-responses-3">
<span class="rfc2119-assertion" id="profile-5.2.4-thing-protocol-binding-error-responses-3">
If we define the finite set of error responses as above then we
should also define what a Consumer should do if it receives a 3xx
redirect type response.
Expand All @@ -2037,7 +1932,7 @@ <h4>Error Responses</h4>
<h2 id="external-td-representations">External TD
representations</h2>
<p>
<span class="rfc2119-assertion" id="profile-5.3-exteanal-td-representations-1">
<span class="rfc2119-assertion" id="profile-5.3-exteanal-td-representations-1">
The default representation is JSON. Semantic
annotations based on JSON-LD MAY be present but are not
required to perform all interactions with the thing
Expand Down

0 comments on commit 8da1330

Please sign in to comment.