-
Notifications
You must be signed in to change notification settings - Fork 63
/
jsonschema.template.html
529 lines (482 loc) · 19.7 KB
/
jsonschema.template.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
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<title>Web of Things (WoT) JSON Schema Ontology</title>
<script src='https://www.w3.org/Tools/respec/respec-w3c' class='remove'></script>
<script class='remove'>
var respecConfig = {
specStatus: "ED",
latestVersion: null,
// publishDate: "2023-12-05",
group: "wg/wot",
editors: [{
name: "Victor Charpenay"
}, {
name: "Maxime Lefrançois"
}, {
name: "María Poveda Villalón"
}],
edDraftURI: "https://www.w3.org/2019/wot/json-schema",
shortName: "wot-jsonschema-ontology",
localBiblio: {
"json-schema-validation": {
title: "JSON Schema Validation: A Vocabulary for Structural Validation of JSON"
, href: "https://tools.ietf.org/html/draft-handrews-json-schema-validation-00"
, authors: [
"Austin Wright",
"Henry Andrews",
"Geraint Luff"
]
, status: "Internet-Draft"
, publisher: "IETF"
},
"json-hyper-schema": {
title: "JSON Hyper-Schema: A Vocabulary for Hypermedia Annotation of JSON"
, href: "https://tools.ietf.org/html/draft-handrews-json-schema-hyperschema-00"
, authors: [
"Henry Andrews",
"Austin Wright"
]
, status: "Internet-Draft"
, publisher: "IETF"
}
},
otherLinks: [{
key: "Ontology in RDF",
data: [
{
value: "Web of Things (WoT) JSON Schema Ontology in RDF",
href: "jsonschema.ttl",
}
]
}
]
};
</script>
</head>
<body>
<section id='abstract'>
<p>
This document introduces an RDF vocabulary for JSON schema definitions.
This vocabulary provides a stable namespace IRI for JSON schema keywords,
as well as simple axioms, defined against schema.org's meta-model. Various
examples on how to use the vocabulary are also introduced, e.g. to annotate
schemas with JSON-LD metadata or to embed schema annotations inside RDF
graphs.
</p>
</section>
<section id='sotd'>
<p>
Validation of the document by the Working Group is expected by the end of June 2019.
</p>
</section>
<section>
<h2>Introduction</h2>
<p>
JSON schema is a popular schema language for JSON documents
[[json-schema-validation]]. This vocabulary includes the main terms
defined by JSON schema in order to represent schema definitions in RDF.
Besides providing a stable namespace IRI for JSON schema terms, this
vocabulary also includes axioms based on schema.org's meta-model. Its
design favors simplicity of use over completeness.
</p>
<p>
Representing JSON schema in RDF was originally intended to be used
as part of the W3C Web of Things (WoT) framework and in particular in
the Thing Description model [[wot-thing-description]]. However,
processing JSON schema in RDF is not limited to WoT. Other use cases
include:
</p>
<ul>
<li>Alignment of schema definitions with RDF vocabularies and RDF shapes</li>
<li>Rule-based validation or transformation of JSON data</li>
<li>Integration of various forms of data specfications, including JSON schema</li>
</ul>
<p>
incidentally, the RDF representation of JSON schema definitions
provides an alternative to the JSON hyper-schema [[json-hyper-schema]]
for cross-references and linking. Examples are provided at the end
of the document.
</p>
<p>
Please note that the Turtle version of the ontology can be always obtained by doing content negotiation as explained in
<a href="https://www.w3.org/TR/2023/REC-wot-thing-description11-20231205/#json-ld-ctx-usage">Appendix D of the Thing
Description Recommendation</a>.
You can include <code>Accept: text/turtle</code> in the request to obtain the Turtle version of this ontology.
</p>
</section>
<section id="conformance"></section>
<section id="terminology">
<h2>Terminology</h2>
<p>The fundamental WoT terminology such as
<dfn class="lint-ignore">Thing</dfn>,
<dfn class="lint-ignore">Consumer</dfn>,
<dfn class="lint-ignore">Thing Description</dfn> (<dfn class="lint-ignore">TD</dfn>),
<dfn class="lint-ignore">Interaction Model</dfn>,
<dfn class="lint-ignore">Interaction Affordance</dfn>,
<dfn class="lint-ignore">Property</dfn>,
<dfn class="lint-ignore">Action</dfn>,
<dfn class="lint-ignore">Event</dfn>,
<dfn class="lint-ignore">Protocol Binding</dfn>,
<dfn class="lint-ignore">Servient</dfn>,
etc. is defined in <a href="https://www.w3.org/TR/wot-architecture/#terminology">Section 3</a>
of the WoT Architecture specification [[WOT-ARCHITECTURE]].
</p>
<p>
The Thing Description terminology such as
<dfn class="lint-ignore">TD Information Model</dfn>,
<dfn class="lint-ignore">TD Document</dfn>,
<dfn class="lint-ignore">Term</dfn> (<dfn class="lint-ignore">Vocabulary Term</dfn>),
etc. is defined in <a href="https://www.w3.org/TR/wot-thing-description/#terminology">Section 3</a>
of the WoT Thing Description specification [[WOT-THING-DESCRIPTION]].
</p>
</section>
<!-- axioms rendered from RDF definitions -->
%s
<section>
<h2>Usage Examples</h2>
<section>
<h3>Interpreting JSON Schema as JSON-LD 1.1</h3>
<p>
The following JSON-LD context [[json-ld11]] can be added to JSON schema
definitions to obtain an RDF representation of these definitions.
</p>
<aside id="json-ld11-ctx" class="example" title="JSON-LD 1.1 context for the JSON schema vocabulary">
<pre>
{
"@context": {
"@version": 1.1,
"xsd": "http://www.w3.org/2001/XMLSchema#",
"@vocab": "https://www.w3.org/2019/wot/json-schema#",
"dct": "http://purl.org/dc/terms/",
"id": { "@id": "@id" },
"type": { "@id": "@type" },
"object": "ObjectSchema",
"array": "ArraySchema",
"boolean": "BooleanSchema",
"string": "StringSchema",
"number": "NumberSchema",
"integer": "IntegerSchema",
"null": "NullSchema",
"properties": {
"@container": "@index",
"@index": "propertyName"
},
"items": { "@type": "@vocab" },
"oneOf": { "@type": "@vocab", "@container": "@set" },
"allOf": { "@type": "@vocab", "@container": "@set" },
"anyOf": { "@type": "@vocab", "@container": "@set" },
"minItems": { "@type": "xsd:nonNegativeInteger" },
"maxItems": { "@type": "xsd:nonNegativeInteger" },
"minimum": { "@type": "xsd:decimal" },
"maximum": { "@type": "xsd:decimal" },
"enum": { "@container": "@set", "@type": "@json" },
"writeOnly": { "@type": "xsd:boolean" },
"readOnly": { "@type": "xsd:boolean" },
"format": { "@type": "xsd:string" },
"required": { "@type": "xsd:string", "@container": "@set" },
"title": { "@id": "dct:title", "@type": "xsd:string" },
"description": { "@id": "dct:description", "@type": "xsd:string" }
}
}
</pre>
</aside>
<p>
The two following examples show the equivalence between the
JSON and the Turtle representations of schema definitions.
These examples were taken from <a href="https://oneiota.org/">the
collection of schemas</a> managed by the Open Connectivity
Foundation (OCF).
</p>
<aside class="example" title="Number schema representing a byte">
<pre class="split-example">
{
"type": "integer",
"minimum": 0,
"maximum": 255
}
</pre>
<pre class="split-example">
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix : <https://www.w3.org/2019/wot/json-schema#> .
[] a :IntegerSchema ;
:minimum "0"^^xsd:integer ;
:maximum "255"^^xsd:integer .
</pre>
</aside>
<aside id="ocf-temp" class="example" title="Object schema for a temperature measurement">
<pre class="split-example">
{
"type": "object",
"properties": {
"temperature": {
"type": "number",
"description": "Current temperature setting or measurement"
},
"units": {
"type": "string",
"enum": ["C", "F", "K"],
"description": "units for the temperature value",
"readOnly": true
}
},
"required": ["temperature"]
}
</pre>
<pre class="split-example">
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix : <https://www.w3.org/2019/wot/json-schema#> .
[] a :ObjectSchema ;
:properties [
a :NumberSchema ;
:propertyName "temperature" ;
:description "Current temperature setting or measurement"
], [
a :StringSchema ;
:propertyName "units" ;
:enum "C", "F", "K" ;
:description "units for the temperature value"
:readOnly "true"^^xsd:boolean
] ;
:required "temperature" .
</pre>
</aside>
<p class="note">
The value defined for the <code>const</code> and <code>enum</code> terms
is always interpreted as a raw JSON value, even if it is an array or an
object. In RDF, it becomes a typed literal with datatype <code>rdf:JSON</code>.
</p>
<p class="note">
In its latest version, the JSON schema <code>items</code> term can be interpreted
in two different ways: if the value is a single schema definition, all items in
the array must then be proper instance of that schema ; if the value is an array
of schema definitions, an item in the instance array must be an instance of the
schema at the same index in the schema array. In the latter case, the schema
array should be interpreted as an RDF list rather as a set of statement (to
preserve order). It is however not possible to express both cases with a single
JSON-LD context. The context given in <a href="#json-ld11-ctx"></a> only
reflects the former case.
</p>
<p class="note">
JSON schema allows schemas to be defined in a "collection" object under
<code>definitions</code>. This feature is purely syntactical, hence not reflected
in the present RDF vocabulary for JSON schema. Interpreting schemas under
<code>definitions</code> as JSON-LD requires prior normalization, by substituting
references in the main schema with their definition. This normalization procedure
may be directly supported by JSON-LD processors in the future.
</p>
<p class="note">
The JSON Schema RDF vocabulary does not include terms for <code>title</code>
and <code>description</code>. Instead, the example context maps them to widely
used Dublin Core terms with equivalent semantics.
</p>
</section>
<section>
<h3>Referencing and linking</h3>
<p>
JSON schema defines the <code>$id</code> and <code>$ref</code> keywords
to increase reusability but also to define schemas in a recursive fashion.
This feature is natively supported by RDF: if schema definitions are named
resources (identified by an IRI) instead of blank nodes, they can be
referenced from anywhere on the Web.
</p>
<p>
The <code>id</code> keyword (an alias for <code>@id</code>) can be used for
that purpose, as shown in the following example, taken from an OCF standard.
</p>
<aside class="example" title="Object schema for light control with reference to a base schema">
<pre>
{
"@context": {
...,
"@base": "http://openinterconnect.org/iotdatamodels/schemas/"
},
"id": "oic.r.light.dimming.json#",
"allOf": [
{
"type": "object",
"properties": {
"dimmingSetting": {
"type": "integer",
"description": "Current dimming value"
}
}
},
{
"id": "oic.baseResource.json#"
}
]
}
</pre>
</aside>
<p class="note">
If the same schema definition (with the same IRI) is used twice as the
value of one of the <code>properties</code> of an object schema, it may result
in name collisions. Indeed, after transformation to RDF, this schema will have
two statements with <code>:propertyValue</code> that do not link back to the
object from which they respectively originate.
</p>
<p>
Besides IRI references between schemas, JSON hyper-schema [[json-hyper-schema]]
allows arbitrary links to be embedded in a schema definition. An alternative to
JSON hyper-schema is to use plain RDF statements or the
<a href="http://www.w3.org/2019/wot/hypermedia">RDF vocabulary for hypermedia
controls</a>. Examples can be found in the documentation of that vocabulary.
</p>
</section>
<section>
<h3>Defining a JSON-LD context for data instances</h3>
<p>
JSON schema definitions may specify JSON structures that
are themselves interpretable as RDF (or JSON-LD). To be able
to do so, instances of a certain schema must be given a
JSON-LD context to map JSON terms to RDF IRIs. This can be
done within a schema definition using the
<a href="http://www.w3.org/ns/json-ld">JSON-LD vocabulary in RDF</a>,
and more precisely with the property <code>jsonld:context</code>.
</p>
<aside class="example" title="Schema with context annotation">
<pre>
{
"@context": {
...,
"jsonld": "http://www.w3.org/ns/json-ld#"
}
"jsonld:context": "http://schema.org",
"type": "object",
"description": "Schema of a commercial product with GTIN and manufacturer",
"properties" : {
"gtin14": { "type": "string" },
"manufacturer": { "type": "string" }
}
}
</pre>
</aside>
<p>
The example above allows schema-aware agents on the Web to interpret
any instance of the schema as JSON-LD by appending the context given
as annotation to the instance JSON, as shown below.
</p>
<aside id="ctx-ref" class="example" title="Instance interpreted as JSON-LD">
<pre>
{
"@context": "http://schema.org",
"name": "some manufactured product",
"gtin14": "0 00 12345 60001 2",
"manufacturer": "http://comapny.example.com"
}
</pre>
</aside>
<p>
Note the difference with using <code>@context</code> in the
schema definition: it is used to interpret <em>instances</em>
as JSON-LD, while <code>@context</code> would alter the way
the <em>schema</em> itself is interpreted.
</p>
<p>
The JSON-LD vocabulary in RDF includes terms to represent any JSON-LD
context in RDF. As a result, contexts can be directly embedded in JSON
schema definitions as well. The example below is a variant of
<a href="#ctx-ref"></a> in which only a subset of schema.org's default
context is embedded in the schema.
</p>
<aside class="example" title="Schema with embedded context">
<pre>
{
"@context": {
...,
"jsonld": "http://www.w3.org/ns/json-ld#",
"jsonld:iri" : { "@type": "@id" }
},
"jsonld:context": {
"jsonld:definition": [
{
"@type": "jsonld:TermDefinition",
"jsonld:term": "gtin14",
"jsonld:iri": "http://schema.org/gtin14"
},
{
"@type": "jsonld:TermDefinition",
"jsonld:term": "manufacturer",
"jsonld:iri": "http://schema.org/manufacturer"
}
]
},
"type": "object",
"description": "Schema of a commercial product with GTIN and manufacturer",
"properties" : {
"gtin14": { "type": "string" },
"manufacturer": { "type": "string" }
}
}
</pre>
</aside>
</section>
<section>
<h3>Embedding schema definitions in data instances</h3>
<p>
Although schema definitions are often put in separate documents, it may
be convenient to embed them in instance data itself, as in the following
example, which uses the Smart Appliance Reference vocabulary (SAREF)
[[smartm2m]]. This usage of the JSON schema vocabulary is similar to that
of <a href="http://schema.org/PropertyValue"><code>schema:PropertyValue</code></a>
and <a href="http://schema.org/PropertyValueSpecification"><code>schema:PropertyValueSpecification</code></a>.
</p>
<aside class="example" title="SAREF on/off state with embedded schema definition">
<pre>
{
"@context": {
...,
"saref": "http://w3id.org/saref#",
"schema": "http://schema.org/"
},
"@type": "saref:LightSwitch",
"saref:hasState": {
"@type": "saref:OnOffState",
"type": "boolean"
}
}
</pre>
</aside>
<p>
This way, it is possible to convey a JSON tree representation
that does not strictly follow the RDF structure of some entity.
In the following example, the temperature property expressed
in SAREF terms embeds a variant of the schema of
<a href="#ocf-temp"></a>.
</p>
<aside class="example" title="SAREF temperature property with embedded schema definition">
<pre>
{
"@context": {
...,
"saref": "http://w3id.org/saref#",
"om": "http://www.wurvoc.org/vocabularies/om-1.8/"
},
"@type": "saref:TemperatureSensor",
"saref:measuresProperty": {
"@type": "saref:Temperature",
"saref:isMeasuredByDevice": "http://device.example.com",
"type": "object",
"properties": [ "_:measure", "om:degree_Celsius" ]
},
"saref:makesMeasurement": {
"@id": "_:measure",
"@type": "saref:Measurement",
"propertyName": "temperature",
"type": "number",
"saref:isMeasuredIn": {
"@id": "om:degree_Celsius",
"propertyName": "units",
"type": "string",
"const": "C"
}
}
}
</pre>
</aside>
</section>
</section>
</body>
</html>