-
Notifications
You must be signed in to change notification settings - Fork 6
/
Copy pathindex.html
334 lines (323 loc) · 14.3 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSON-LD 1.1 in CBOR</title>
<script src="https://www.w3.org/Tools/respec/respec-w3c-common" class="remove"></script>
<script type="text/javascript" src="common/common.js" class="remove" defer></script>
<script type="text/javascript" src="common/jsonld.js" class="remove"></script>
// See https://github.com/w3c/respec/wiki/ for how to configure ReSpec
<script class='remove'>
var respecConfig = {
localBiblio: jsonld.localBiblio,
specStatus: "ED",
copyrightStart: "2019",
shortName: "json-ld-cbor",
github: "https://github.com/w3c/json-ld-cbor/",
edDraftURI: "https://w3c.github.io/json-ld-cbor/",
includePermalinks: true,
doJsonLd: true,
pluralize: true,
editors: [{
name: "Somebody..."
}],
// name of the WG
wg: "JSON-LD Working Group",
// URI of the public WG page
wgURI: "https://www.w3.org/2018/json-ld-wg/",
// name (with the @w3c.org) of the public mailing to which comments are due
wgPublicList: "public-json-ld-wg",
processVersion: 2018,
maxTocLevel: 4,
noRecTrack: "true"
};
</script>
</head>
<body>
<section id="abstract">
<p>
TODO in the end
</p>
</section>
<section id="sotd">
<p>
This is an unofficial proposal.
</p>
</section>
<section id="introduction" data-cite="JSON-LD11">
<h2>Introduction</h2>
<!--
<p>
See <a href="https://github.com/w3c/respec/wiki/User's-Guide">ReSpec's user guide</a>
for how to get started!
</p>
-->
<p>
The [[[RFC7049]]] [[RFC7049]] is a data format for constrained environments.
It is designed to be processable with small code, and to produce small messages.
Its underlying data model is an extension of the
<a data-cite="RFC8259#" data-no-xref="">JSON</a> data model [[RFC8259]].
That makes it an possible format to transport JSON-LD documents,
in constrained contexts such as, e.g., the Web of Things.
It also allows JSON-LD <a data-cite="JSON-LD11#dfn-context">contexts</a> to be used to provide a layer of semantics on existing CBOR data.
</p>
<p>
More specifically, this note specifies how to convert between the
<a data-cite="RFC7049#">CBOR</a> data format and the
<a href="JSON-LD11#dfn-internal-representation">JSON-LD internal representation</a>
(a is straightforward abstraction of the JSON format<span style="display: none">
using the following terms,
which are only included here to please ReSpec, but should not be displayed:
<dfn data-cite="INFRA#list" class="preserve">array</dfn>,
<dfn data-cite="INFRA#boolean" class="preserve">boolean</dfn>,
<dfn data-cite="INFRA#ordered-map" class="preserve">map</dfn>,
<dfn data-cite="INFRA#map-entry" data-lt="map entry|entry" data-ld-noDefault class="preserve">entries</dfn>,
<dfn data-cite="INFRA#nulls" class="preserve">null</dfn>,
<dfn data-cite="ECMASCRIPT#sec-terms-and-definitions-number-value" data-lt="number|JSON number" class="preserve">number</dfn>,
<dfn data-cite="WEBIDL#idl-long" class="preserve">long</dfn>,
<dfn data-cite="WEBIDL#idl-double" class="preserve">double</dfn>,
<dfn data-cite="INFRA#primitive-data-types" class="preserve">scalar</dfn>,
<dfn data-cite="INFRA#javascript-string" class="preserve">string</dfn>
</span>).
Since CBOR emphasizes small messages,
we also propose a number of techniques for reducing the size of messages.
</p>
<p>
To understand this note you must be familiar both the
<a data-cite="RFC8259" data-no-xref="">JSON</a> format [[RFC8259]] and the
<a data-cite="RFC7049" data-no-xref="">CBOR</a> format [[RFC7049]].
You must also understand the basics of
<a data-cite="JSON-LD11" data-no-xref="">JSON-LD 1.1</a> [[JSON-LD11]].
</p>
</section>
<section id="serialize">
<h2>Serializing JSON-LD to CBOR</h2>
<p>While being generally based on the
<a data-cite="RFC8259#">JSON</a> data model,
the <a data-cite="RFC7049#">CBOR</a>
specification does not specify a standard conversion between both models.
This is due in part to the fact that the
<a data-cite="RFC7049#">CBOR</a> model is an extension of the former.
In this section, we provide a complete specification of such a conversion,
following the guidelines from <a data-cite="RFC7049#section-4.2">§4.2 of RFC7049</a>,
and taking into account the particularities of <a data-cite="JSON-LD11#">JSON-LD</a>.
</p>
<ul>
<li id="serialize-null-bool">
<a>Null</a> and <a>boolean</a> values are serialized with major type 7,
and additional type value 22 for `null`, 20 for `false` and 21 for `true`.
</li>
<li id="serialize-int">
<a>Numbers</a> without a fractional part (integer numbers)
are serialized as CBOR integers (major types 0 and 1),
choosing the shortest form.
</li>
<li id="serialize-float">
<a>Numbers</a> with a fractional part are serialized as CBOR floating-point values
(major type 7, and additional type value from 25 to 27).
Preferably,
the shortest exact floating-point representation is used;
for instance, 1.5 is represented in a 16-bit floating-point value
(not all implementations will be capable of efficiently finding the minimum form, though).
</li>
<li id="serialize-string">
<a>Strings</a> are serialized as CBOR UTF-8 strings
(major type 3).
Note that, unlike JSON,
CBOR does not require any escaping in strings,
so all escape codes (if any)
present in the JSON source must be replaced beforehand by their corresponding character.
</li>
<li id="serialize-array">
<a>Arrays</a> are serialized as CBOR arrays (major type 4),
and their items are serialized by applying these rules recursively.
</li>
<li id="serialize-object">
<a data-cite="RFC8259#section-4">JSON objects</a>,
are internally represented as <a>maps</a> in JSON-LD,
and are generally serialized as CBOR maps (major type 5).
All keys are strings, and are serialized as above;
all values are serialized by applying these rules recursively.
There are however a few exceptions described below,
to take into account their specific meaning in JSON-LD:
<ul>
<li>
If the object is a
<a data-cite="JSON-LD11#dfn-value-object">value object</a>
with a `@type` of `xsd:integer` (TODO full IRI),
an if its `@value` is a valid decimal representation of an integer,
then the object is serialized as a CBOR integer (major type 0 or 1)
choosing the shortest form.
</li>
<li>
If the object is a
<a data-cite="JSON-LD11#dfn-value-object">value object</a>
with a `@type` of `xsd:base64Binary` (TODO full IRI),
an if its `@value` complies with the
<a data-cite="XSD#base64Binary">lexical space</a>
of `xsd:base64Binary` (i.e. is it a valid base 64 string [[RFC3548]]),
then the JSON object is serialized as a CBOR binary string
(major type 2) representing the decoded value.
</li>
</ul>
<!--
TODO
- semantic tag for @list, @set and friends?
- xsd:float / xsd:double (incl. NaN, +INF... , -0)
- xsd:decimal -> decimal (semantic tag)???
- xsd:dateType -> semantic tag (depending on actual format)
- @json -> encode JSON in CBOR? without the excepetions above?
- semantic tag for @list, @set and friends?
- rdf:CBOR ???
Some of them have a specific interpretation,
and are therefore processed differently from others.
<ul>
<li>
If the object is a
<a data-cite="JSON-LD11#dfn-value-object">value object</a>
with a `@type` <a>entry</a> equal to
`http://www.w3.org/1999/02/22-rdf-syntax-ns#CBOR`,
its `@value` is a valid lexical value for this datatype (see
<a href="#datatype"></a> below),
it is serialized as a map (major type 5), with two entries:
...
</li>
</ul>
-->
</li>
</ul>
</section>
<section id="parse">
<h2>Parsing CBOR to JSON-LD</h2>
<p>
This section describes how to parse CBOR data into the
<a href="JSON-LD11#dfn-internal-representation">JSON-LD internal representation</a>,
following the guidelines from <a data-cite="RFC7049#section-4.1">§4.1 of RFC7049</a>.
It is the inverse process of the one described in
<a href="#serialize"></a>.
</p>
<ul>
<li>
A data item with major type 0 or 1 (positive or negative integer, respectively)
is parsed as the equivalent <a>number</a>.
If the size of this number exceeds the size supported by the implementation,
a parser must produce instead a <a>map</a> with two entries:
<ul>
<li>a `@type` entry whose value is `xsd:integer` (TODO full IRI),</li>
<li>a `@value` entry whose value is a decimal representation of the integer, as a string.</li>
</ul>
<!-- TODO or encode it as a xsd:float? -->
</li>
<li>
A data item with major type 2 (binary string)
is parsed as a <a>map</a> with two entries:
<ul>
<li>a `@type` entry whose value is `xsd:base64Binary` (TODO full IRI),</li>
<li>a `@value` entry whose value is the base 64 encoding of the binary string, complying with the constraints on the
<a data-cite="XSD#base64Binary">lexical space</a>
of `xsd:base64Binary`.
</li>
</ul>
</li>
<li>
A data item with major type 3 (text string)
is parsed as the equivalent <a>string</a>.
</li>
<li>
A data item with major type 4 (array) is parsed as an <a>array</a>,
whose items are parsed by recursively applying these rules to the items of the CBOR array.
</li>
<li>
A data item with major type 5 (map) is parsed as a <a>map</a>,
whose keys and values are parsed by recursively applying these rules to the items of the CBOR map.
Any <a>entry</a> whose key is not a <a>string</a> can not be inserted in the <a>map</a>,
and must therefore raise an error.
</ul>
</li>
<li>
A data item with major type 6 (semantic tag) is generally ignored;
its following value is simply parsed by recursively applying these rules.
<!-- TODO There are a few exception, however. -->
</ul>
</li>
<li>
A data item with major type 7 (primitive) is parsed as
<ul>
<li>the <a>boolean</a> value `false` if the additional type value is 20,</li>
<li>the <a>boolean</a> value `true` if the additional type value is 21,</li>
<li>the <a>null</a> if the additional type value is 22.</li>
<li>if the additional type value is 24,
25 or 26 (floating point number),
<ul>
<li>
if the value is finite,
the data item is parsed as the corresponding <a>number</a>;
</li>
<li>
otherwise the data item represents either <i>NaN</i>,
positive infinity or negative infinity;
it is serialized as a <a>map</a> with two entries:
<ul>
<li>
a `@type` entry whose value is `xsd:double` (TODO full IRI),
</li>
<li>
a `@value` entry whose value is the <a>string</a> `NaN`, `INF` or `-INF`, respectively.
<!-- TODO -O as well? -->
</li>
</ul>
</li>
</ul>
</li>
<li>the corresponding floating point <a>number</a> if the additional type value is 24,
25 or 26 and its value is neither `NaN`, positive infinity nor negative infinity,</li>
</ul>
Any other additional type value must raise an error.
<!-- TODO or do something else?-->
</li>
</ul>
</section>
<section id="optimize">
<h2>CBOR-specific optimization of JSON-LD data</h2>
<p>TODO</p>
<section id="tag">
<h3>JSON-LD semantic tag</h3>
<p>TODO propose numeric aliases for keywords, and possibly often used IRIs?</p>
</section>
<section id="tag">
<h3>Designing contexts for CBOR</h3>
<p>TODO do no alias keywords, do not use type coercion, define small prefixes, more...</p>
</section>
</section>
<section id="datatype">
<h2>The `rdf:CBOR` datatype</h2>
<p>
The intent of this datatype is to make it possible to convey CBOR data as
<a data-cite="RDF11-CONCEPTS#section-Graph-Literal">RDF literals</a>.
It is defined as a subset of
<a data-cite="XSD#binary64Binary">the `xsd:base64Binary` datatype</a>.
</p>
<p>The <code>rdf:CBOR</code> datatype is defined as follows:</p>
<dl>
<dt>The IRI denoting this datatype</dt>
<dd>is `http://www.w3.org/1999/02/22-rdf-syntax-ns#CBOR`.</dd>
<dt>The lexical space</dt>
<dd>
is the subset of
<a data-cite="XSD#base64Binary">the lexical space of `xsd:base64Binary`</a>,
for which the lexical mapping produces well-formed CBOR data [[RFC7049]].
</dd>
<dt>The value space</dt>
<dd class="changed">
is the set of finite-length sequences of zero or more binary octets,
which are well-formed CBOR data [[RFC7049]].
</dd>
<dt>The lexical-to-value mapping and canonical mapping</dt>
<dd>
are the ones defined for the
<a data-cite="XSD#base64Binary">`xsd:base64Binary` datatype</a> [[XSD]].
</dd>
</dl>
</section>
</body>
</html>