Web of Things (WoT) JSON Schema Ontology

W3C Editor's Draft

More details about this document
This version:
https://www.w3.org/2019/wot/json-schema
Latest published version:
none
Latest editor's draft:
https://www.w3.org/2019/wot/json-schema
Editors:
Victor Charpenay
Maxime Lefrançois
María Poveda Villalón
Ontology in RDF
Web of Things (WoT) JSON Schema Ontology in RDF

Abstract

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.

Status of This Document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

Validation of the document by the Working Group is expected by the end of June 2019.

This document was published by the Web of Things Working Group as an Editor's Draft.

Publication as an Editor's Draft does not imply endorsement by W3C and its Members.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 03 November 2023 W3C Process Document.

1. Introduction

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.

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:

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.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

3. Terminology

The fundamental WoT terminology such as Thing, Consumer, Thing Description (TD), Interaction Model, Interaction Affordance, Property, Action, Event, Protocol Binding, Servient, etc. is defined in Section 3 of the WoT Architecture specification [WOT-ARCHITECTURE].

The Thing Description terminology such as TD Information Model, TD Document, Term (Vocabulary Term), etc. is defined in Section 3 of the WoT Thing Description specification [WOT-THING-DESCRIPTION].

4. Axiomatization

4.1 Classes

4.1.1 ArraySchema

IRI: https://www.w3.org/2019/wot/json-schema#ArraySchema

Metadata describing data of type array. This subclass is indicated by the value array assigned to type in DataSchema instances.
Sub-class of jsonschema:DataSchema
In the domain of jsonschema:items
jsonschema:maxItems
jsonschema:minItems

4.1.2 BooleanSchema

IRI: https://www.w3.org/2019/wot/json-schema#BooleanSchema

Metadata describing data of type boolean. This subclass is indicated by the value boolean assigned to type in DataSchema instances.
Sub-class of jsonschema:DataSchema

4.1.3 DataSchema

IRI: https://www.w3.org/2019/wot/json-schema#DataSchema

Metadata that describes the data format used. It can be used for validation.
Super-class of jsonschema:ArraySchema
jsonschema:BooleanSchema
jsonschema:IntegerSchema
jsonschema:NullSchema
jsonschema:NumberSchema
jsonschema:ObjectSchema
jsonschema:StringSchema
In the domain of jsonschema:allOf
jsonschema:anyOf
jsonschema:const
jsonschema:default
jsonschema:enum
jsonschema:oneOf
jsonschema:propertyName
jsonschema:readOnly
jsonschema:writeOnly
td:description
td:descriptionInLanguage
td:title
td:titleInLanguage
In the range of jsonschema:allOf
jsonschema:anyOf
jsonschema:items
jsonschema:oneOf
jsonschema:properties

4.1.4 IntegerSchema

IRI: https://www.w3.org/2019/wot/json-schema#IntegerSchema

Metadata describing data of type integer. This subclass is indicated by the value integer assigned to type in DataSchema instances.
Sub-class of jsonschema:DataSchema
In the domain of jsonschema:exclusiveMaximum
jsonschema:exclusiveMinimum
jsonschema:maximum
jsonschema:minimum
jsonschema:multipleOf

4.1.5 NullSchema

IRI: https://www.w3.org/2019/wot/json-schema#NullSchema

Metadata describing data of type null. This subclass is indicated by the value null assigned to type in DataSchema instances. This Subclass describes only one acceptable value, namely null. It is important to note that null does not mean the absence of a value. It is analogous to null in JavaScript, None in Python, null in Java and nil in Ruby programming languages. It can be used as part of a oneOf declaration, where it is used to indicate, that the data can also be null.
Sub-class of jsonschema:DataSchema

4.1.6 NumberSchema

IRI: https://www.w3.org/2019/wot/json-schema#NumberSchema

Metadata describing data of type number. This subclass is indicated by the value number assigned to type in DataSchema instances.
Sub-class of jsonschema:DataSchema
In the domain of jsonschema:exclusiveMaximum
jsonschema:exclusiveMinimum
jsonschema:maximum
jsonschema:minimum
jsonschema:multipleOf

4.1.7 ObjectSchema

IRI: https://www.w3.org/2019/wot/json-schema#ObjectSchema

Metadata describing data of type object. This subclass is indicated by the value object assigned to type in DataSchema instances.
Sub-class of jsonschema:DataSchema
In the domain of jsonschema:properties
jsonschema:required

4.1.8 StringSchema

IRI: https://www.w3.org/2019/wot/json-schema#StringSchema

Metadata describing data of type string. This subclass is indicated by the value string assigned to type in DataSchema instances.
Sub-class of jsonschema:DataSchema
In the domain of jsonschema:contentEncoding
jsonschema:contentMediaType
jsonschema:format
jsonschema:maxLength
jsonschema:minLength
jsonschema:pattern

4.2 Object Properties

4.2.1 allOf

IRI: https://www.w3.org/2019/wot/json-schema#allOf

Used to ensure that the data is valid against all of the specified schemas in the array.
Domain includes jsonschema:DataSchema
Range includes jsonschema:DataSchema

4.2.2 anyOf

IRI: https://www.w3.org/2019/wot/json-schema#anyOf

Used to ensure that the data is valid against any of the specified schemas in the array.
Domain includes jsonschema:DataSchema
Range includes jsonschema:DataSchema

4.2.3 items

IRI: https://www.w3.org/2019/wot/json-schema#items

Used to define the characteristics of an array.
Domain includes jsonschema:ArraySchema
Range includes jsonschema:DataSchema

4.2.4 oneOf

IRI: https://www.w3.org/2019/wot/json-schema#oneOf

Used to ensure that the data is valid against exactly one of the specified schemas in the array.
Domain includes jsonschema:DataSchema
Range includes jsonschema:DataSchema

4.2.5 properties

IRI: https://www.w3.org/2019/wot/json-schema#properties

Data schema nested definitions
Domain includes jsonschema:ObjectSchema
Range includes jsonschema:DataSchema

4.3 Datatype Properties

4.3.1 const

IRI: https://www.w3.org/2019/wot/json-schema#const

Provides a constant value.
Domain includes jsonschema:DataSchema

4.3.2 contentEncoding

IRI: https://www.w3.org/2019/wot/json-schema#contentEncoding

Specifies the encoding used to store the contents, as specified in RFC 2054. The values that are accepted: "7bit", "8bit", "binary", "quoted-printable" and "base64".
Domain includes jsonschema:StringSchema

4.3.3 contentMediaType

IRI: https://www.w3.org/2019/wot/json-schema#contentMediaType

Specifies the MIME type (e.g., image/png, audio/mpeg) of the contents of a string value, as described in RFC 2046.
Domain includes jsonschema:StringSchema

4.3.4 default

IRI: https://www.w3.org/2019/wot/json-schema#default

Supply a default value. The value should validate against the data schema in which it resides.
Domain includes jsonschema:DataSchema

4.3.5 enum

IRI: https://www.w3.org/2019/wot/json-schema#enum

Restricted set of values provided as an array.
Domain includes jsonschema:DataSchema

4.3.6 exclusiveMaximum

IRI: https://www.w3.org/2019/wot/json-schema#exclusiveMaximum

Specifies a maximum numeric value, representing an exclusive upper limit. Only applicable for associated number or integer types.
Domain includes jsonschema:IntegerSchema
jsonschema:NumberSchema

4.3.7 exclusiveMinimum

IRI: https://www.w3.org/2019/wot/json-schema#exclusiveMinimum

Specifies a minimum numeric value, representing an exclusive lower limit. Only applicable for associated number or integer types.
Domain includes jsonschema:IntegerSchema
jsonschema:NumberSchema

4.3.8 format

IRI: https://www.w3.org/2019/wot/json-schema#format

Allows validation based on a format pattern such as "date-time", "email", "uri", etc.
Domain includes jsonschema:StringSchema

4.3.9 maxItems

IRI: https://www.w3.org/2019/wot/json-schema#maxItems

Defines the maximum number of items that have to be in the array.
Domain includes jsonschema:ArraySchema

4.3.10 maxLength

IRI: https://www.w3.org/2019/wot/json-schema#maxLength

Specifies the maximum length of a string. Only applicable for associated string types.
Domain includes jsonschema:StringSchema

4.3.11 maximum

IRI: https://www.w3.org/2019/wot/json-schema#maximum

Specifies a maximum numeric value, representing an inclusive upper limit. Only applicable for associated number or integer types.
Domain includes jsonschema:IntegerSchema
jsonschema:NumberSchema

4.3.12 minItems

IRI: https://www.w3.org/2019/wot/json-schema#minItems

Defines the minimum number of items that have to be in the array.
Domain includes jsonschema:ArraySchema

4.3.13 minLength

IRI: https://www.w3.org/2019/wot/json-schema#minLength

Specifies the minimum length of a string. Only applicable for associated string types.
Domain includes jsonschema:StringSchema

4.3.14 minimum

IRI: https://www.w3.org/2019/wot/json-schema#minimum

Specifies a minimum numeric value, representing an inclusive lower limit. Only applicable for associated number or integer types.
Domain includes jsonschema:IntegerSchema
jsonschema:NumberSchema

4.3.15 multipleOf

IRI: https://www.w3.org/2019/wot/json-schema#multipleOf

Specifies the multipleOf value number. The value must strictly greater than 0. Only applicable for associated number or integer types.
Domain includes jsonschema:IntegerSchema
jsonschema:NumberSchema

4.3.16 pattern

IRI: https://www.w3.org/2019/wot/json-schema#pattern

Provides a regular expression to express constraints of the string value. The regular expression must follow the ECMA 262 dialect.
Domain includes jsonschema:StringSchema

4.3.17 propertyName

IRI: https://www.w3.org/2019/wot/json-schema#propertyName

Used to store the indexing name in the parent object when this schema appears as a property of an object schema.
Domain includes jsonschema:DataSchema

4.3.18 readOnly

IRI: https://www.w3.org/2019/wot/json-schema#readOnly

Boolean value that is a hint to indicate whether a property interaction / value is read only (=true) or not (=false)
Domain includes jsonschema:DataSchema

4.3.19 required

IRI: https://www.w3.org/2019/wot/json-schema#required

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 invokeaction, writeproperty) and what members will be definitely delivered in the payload that is being received (e.g. output of invokeaction, readproperty)
Domain includes jsonschema:ObjectSchema

4.3.20 writeOnly

IRI: https://www.w3.org/2019/wot/json-schema#writeOnly

Boolean value that is a hint to indicate whether a property interaction / value is write only (=true) or not (=false)
Domain includes jsonschema:DataSchema

4.4 Annotation Properties

No AnnotationProperty found in the ontology.

5. Usage Examples

5.1 Interpreting JSON Schema as JSON-LD 1.1

The following JSON-LD context [json-ld11] can be added to JSON schema definitions to obtain an RDF representation of these definitions.

The two following examples show the equivalence between the JSON and the Turtle representations of schema definitions. These examples were taken from the collection of schemas managed by the Open Connectivity Foundation (OCF).

Note

The value defined for the const and enum 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 rdf:JSON.

Note

In its latest version, the JSON schema items 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 Example 1 only reflects the former case.

Note

JSON schema allows schemas to be defined in a "collection" object under definitions. This feature is purely syntactical, hence not reflected in the present RDF vocabulary for JSON schema. Interpreting schemas under definitions 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.

Note

The JSON Schema RDF vocabulary does not include terms for title and description. Instead, the example context maps them to widely used Dublin Core terms with equivalent semantics.

5.2 Referencing and linking

JSON schema defines the $id and $ref 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.

The id keyword (an alias for @id) can be used for that purpose, as shown in the following example, taken from an OCF standard.

Note

If the same schema definition (with the same IRI) is used twice as the value of one of the properties of an object schema, it may result in name collisions. Indeed, after transformation to RDF, this schema will have two statements with :propertyValue that do not link back to the object from which they respectively originate.

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 RDF vocabulary for hypermedia controls. Examples can be found in the documentation of that vocabulary.

5.3 Defining a JSON-LD context for data instances

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 JSON-LD vocabulary in RDF, and more precisely with the property jsonld:context.

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.

Note the difference with using @context in the schema definition: it is used to interpret instances as JSON-LD, while @context would alter the way the schema itself is interpreted.

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 Example 6 in which only a subset of schema.org's default context is embedded in the schema.

5.4 Embedding schema definitions in data instances

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 schema:PropertyValue and schema:PropertyValueSpecification.

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 Example 3.

A. References

A.1 Normative references

[json-hyper-schema]
JSON Hyper-Schema: A Vocabulary for Hypermedia Annotation of JSON. Henry Andrews; Austin Wright. IETF. Internet-Draft. URL: https://tools.ietf.org/html/draft-handrews-json-schema-hyperschema-00
[json-ld11]
JSON-LD 1.1. Gregg Kellogg; Pierre-Antoine Champin; Dave Longley. W3C. 16 July 2020. W3C Recommendation. URL: https://www.w3.org/TR/json-ld11/
[json-schema-validation]
JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Austin Wright; Henry Andrews; Geraint Luff. IETF. Internet-Draft. URL: https://tools.ietf.org/html/draft-handrews-json-schema-validation-00
[smartm2m]
ETSI TS 103 264 V2.1.1 (2017-03): SmartM2M; Smart Appliances; Reference Ontology and oneM2M Mapping. ETSI. March 2017. Published. URL: http://www.etsi.org/deliver/etsi_ts/103200_103299/103264/02.01.01_60/ts_103264v020101p.pdf
[WOT-ARCHITECTURE]
Web of Things (WoT) Architecture. Matthias Kovatsch; Ryuichi Matsukura; Michael Lagally; Toru Kawaguchi; Kunihiko Toumura; Kazuo Kajimoto. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-architecture/
[wot-thing-description]
Web of Things (WoT) Thing Description. Sebastian Käbisch; Takuki Kamiya; Michael McCool; Victor Charpenay; Matthias Kovatsch. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-thing-description/