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

Introduce draft for text binding template #140

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

Introduce draft for text binding template #140

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a0d0551
introduce draft for text binding template
relu91 Dec 3, 2021
245587b
text binding improve mapping description
relu91 Apr 19, 2022
f1551e1
text binding improve introduction ad abstract
relu91 Apr 19, 2022
fd012c3
improve payloads represtnation description
relu91 Apr 19, 2022
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
136 changes: 136 additions & 0 deletions bindings/payloads/text/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
<!DOCTYPE html>
<html>

<head>
<meta charset='utf-8'>
<script src='https://www.w3.org/Tools/respec/respec-w3c' class='remove'></script>
<script class='remove'>
var respecConfig = {
specStatus: "ED",
editors: [
{
name: "Cristiano Aguzzi",
w3cid: "105495",
company: "Invited Expert",
companyURL: "https://github.com/relu91"
}
],
edDraftURI: "https://w3c.github.io/wot-binding-templates/text",
shortName: "wot-txt-template",
otherLinks: [
{
key: "Other documentation",
data: [{
value: "In the GitHub repository",
href: "https://github.com/w3c/wot-binding-templates/graphs/contributors"
}]
}
]
};
</script>
<title>Text Binding Template</title>
</head>

<body>
<section id="abstract">
<p>
The Thing Description specification defines a data model for describing payloads. This
document describes how to map <a href="https://www.rfc-editor.org/rfc/rfc2046.html#section-4.1.3">Text Plain</a>
payloads to the WoT Data model.
</p>
</section>
<section id='introduction'>
<h2>Introduction</h2>
<p>
The Internet of things is well-known for its wide range of protocols and payload formats. The Web of Things Binding
Templates specification addresses the interoperability challenges between the different IoT technologies using a
declarative approach. In particular, for various payload formats, it defines a set of mappings between content types and
the data model defined in the Thing Description specification. This document focuses on the <a href="https://www.rfc-editor.org/rfc/rfc2046.html#section-4.1.3">Text Plain</a>
content type and provides examples of payloads that can be used in a WoT application.
</p>
</section>
<section id='sotd'>
<p>
<em>This document is a work in progress</em>
</p>
</section>
<section>
<h2>Media type</h2>
<p>
The text binding template refers to <a href="https://www.rfc-editor.org/rfc/rfc2046.html#section-4.1.3">Text Plain</a>
with <code>text/plain</code> as MIME type.
</section>
<section>
<h2>Mapping <code>text/plain</code> to DataSchema values</h2>
<p>
This section describes how a <code>text/plain</code> payloads can be de/serialized in one of the supported
DataSchema types.
<ul>
<li>
<code>string</code>: The payload is interpreted as a string of characters.
</li>
<li>
<code>number</code>: The payload contains a number serialized as characters. Implementations should
convert the characters to a <code>number</code> and viceversa when reading/writing the payload.
</li>
<li>
<code>integer</code>: The payload contains an integer serialized as characters. Implementations should
convert the characters to an <code>integer</code> and viceversa when reading/writing the payload.
</li>
</ul>
</p>
</section>
<section>
<h2>Supported Data Schema terms</h2>
<p>
This section describes which terms can be used when describing data with <code>text/plain</code> content type.
</p>
<p>
Given the nature of <code>text/plain</code> documents and the mapping function described below, the following terms are not supported:
<ul>
<li><code>object</code></li>
<li><code>array</code></li>
<li><code>null</code></li>
<li><code>boolean</code></li>
</ul>
<p class="ednote">
Implementations may use custom serialization/deserialization functions to support these terms.
</p>
</p>
</section>

<section>
<h2>Examples</h2>
Consider this Data schema:
<pre class="example">
{
"type": "string",
}
</pre>
<p>
A valid document can be:
</p>
<pre class="example">
This is the context of ta text file sent by the remote device.
</pre>
Numbers instead can be mapped as follows:
<pre class="example">
{
"type": "number",
}
</pre>
A set of valid <code>text/plain</code> documents according to this schema are:
<pre class="example">
123
</pre>
<pre class="example">
123.456
</pre>
<pre class="example">
-13
</pre>
</section>

</body>

</html>
82 changes: 53 additions & 29 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,14 @@
publisher: "Modbus Organization",
status: "",
date: "26 April 2012"
}
},
"JSON" : {
href: "https://datatracker.ietf.org/doc/html/rfc8259",
title: "JSON",
publisher: "IETF",
status: "",
date: "December 2017"
},
}
};
</script>
Expand Down Expand Up @@ -315,30 +322,29 @@ <h4>Creating a new Protocol Binding</h4>

<section id="payloads-intro">
<h3>Payload Representation</h3>

Various payloads sent in the messages of protocols can be described in TDs using two mechanisms:
<ul>
<li>
<b>Media Types:</b> Media Types [[IANA-MEDIA-TYPES]] describe the encoding used for sending and
receiving the data with a protocol.
They are represented with the <code>contentType</code> in the Forms of a TD, which is mandatory for
each Interaction Affordance.
In some cases such as images, videos or any unstructured data, they are enough to describe the
payload.
Correct indication of Media Types enables proper processing of the serialized documents.
This way, the documents can be exchanged in any format and allow the upper layers of an application
to adapt to different formats.
</li>
<li>
<b>Data Schema:</b> The TD specification defines the Data Schema concept to describe the structure
of the data payloads.
Even though it is largely inspired by JSON Schema [[json-schema]], it can be used for describing
other payload types such as [[XML]], string-encoded images, bit representations of integers, etc.
Data Schema SHOULD be used in addition to the media types.
</li>
</ul>

The table below summarizes the currently specified payload formats.
<p>
IoT protocols use various payload formats to transport application data between different nodes. Sometimes,
payload formats are re used between different platforms or even different protocols. One example is the extraordinary
popularity of [JSON] or [XML]. The scope of this section is to collect a set of common payload formats that can be
used in an interaction between two different Web Things. In a Thing Description payloads format are identified using
a <b>Media Types</b> [[IANA-MEDIA-TYPES]] specified in the <code>contentType</code> attribute of a Form
which is mandatory for each Interaction Affordance.
</p>
<p>
However, <b>Media Types</b> does not always define the exact structure of the exchanged information.
For example, a [JSON] document may contain an Array or an Object. Application wise the lacking of a proper
defined structure may cause interoperability and validation challenges. Therefore, in such cases a
<b>Media Types</b> can be further described using a Data Schema. In a nutshell, a Data Schema will describe
a payload using the Thing Description data model and can be used to validate the payload.
</p>
<p>
Not every <b>Media Types</b> can be mapped onto the Thing Description data model because of its
specific nature. For example, simple images does not usually contain structured information but just raw
image binary data. Therefore, the following table describes the supported <b>Media Types</b> and their
respective specifications for mapping to the Thing Description data model. If a <b>Media Type</b> is not
listed here, it MAY be still supported by the Web of Things but applications SHOULD treat it as an unstructured
payload. Unstructured payloads cannot have an associated Data Schema.
</p>

<table class="def">
<thead>
Expand All @@ -354,6 +360,18 @@ <h3>Payload Representation</h3>
<td>JSON</td>
<td>JavaScript Object Notation</td>
<td><code>application/json</code></td>
<td>Default mapping</td>
</tr>
<tr>
<td>JSON-LD</td>
<td>JSON for Linking Data</td>
<td><code>application/ld+json</code></td>
<td>TODO</td>
</tr>
<tr>
<td>CBOR</td>
<td>Concise Binary Object Representation</td>
<td><code>text/plain</code></td>
<td>TODO</td>
</tr>
<tr>
Expand All @@ -362,16 +380,22 @@ <h3>Payload Representation</h3>
<td><code>application/xml</code></td>
<td><a href="./bindings/payloads/xml/index.html">Link</a></td>
</tr>
<tr>
<td>EXI</td>
<td>Efficient XML Interchange</td>
<td><code>application/exi</code></td>
<td>TODO</td>
</tr>
<tr>
<td>text</td>
<td>text</td>
<td><code>text/plain</code></td>
<td>TODO</td>
<td><a href="./bindings/payloads/text/index.html">Link</a></td>
</tr>
<tr>
<td>Unstructured Data</td>
<td>Unstructured Data</td>
<td>various</td>
<td>bytes</td>
<td>octet-stream</td>
<td><code>application/octet-stream</code></td>
<td>TODO</td>
</tr>
</tbody>
Expand Down