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.

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

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.

Axiomatization

Classes

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 ofjsonschema:DataSchema
In the domain ofjsonschema:items
jsonschema:maxItems
jsonschema:minItems

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 ofjsonschema:DataSchema

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 ofjsonschema:ArraySchema
jsonschema:BooleanSchema
jsonschema:IntegerSchema
jsonschema:NullSchema
jsonschema:NumberSchema
jsonschema:ObjectSchema
jsonschema:StringSchema
In the domain ofjsonschema:allOf
jsonschema:anyOf
jsonschema:const
jsonschema:enum
jsonschema:oneOf
jsonschema:propertyName
jsonschema:readOnly
jsonschema:writeOnly
In the range ofjsonschema:allOf
jsonschema:anyOf
jsonschema:items
jsonschema:oneOf
jsonschema:properties

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 ofjsonschema:DataSchema
In the domain ofjsonschema:maximum
jsonschema:minimum

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 can be used as part of a oneOf declaration, where it is used to indicate, that the data can also be null.
Sub-class ofjsonschema:DataSchema

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 ofjsonschema:DataSchema
In the domain ofjsonschema:maximum
jsonschema:minimum

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 ofjsonschema:DataSchema
In the domain ofjsonschema:properties
jsonschema:required

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 ofjsonschema:DataSchema
In the domain ofjsonschema:format

Object Properties

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 includesjsonschema:DataSchema
Range includesjsonschema:DataSchema

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 includesjsonschema:DataSchema
Range includesjsonschema:DataSchema

items

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

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

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 includesjsonschema:DataSchema
Range includesjsonschema:DataSchema

properties

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

Data schema nested definitions
Domain includesjsonschema:ObjectSchema
Range includesjsonschema:DataSchema

Datatype Properties

const

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

Provides a constant value.
Domain includesjsonschema:DataSchema

enum

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

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

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 includesjsonschema:StringSchema

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 includesjsonschema:ArraySchema

maximum

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

Specifies a maximum numeric value. Only applicable for associated number or integer types.
Domain includesjsonschema:IntegerSchema
jsonschema:NumberSchema

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 includesjsonschema:ArraySchema

minimum

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

Specifies a minimum numeric value. Only applicable for associated number or integer types.
Domain includesjsonschema:IntegerSchema
jsonschema:NumberSchema

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 includesjsonschema:DataSchema

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 includesjsonschema:DataSchema

required

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

Defines which members of the object type are mandatory.
Domain includesjsonschema:ObjectSchema

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 includesjsonschema:DataSchema

Usage Examples

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).

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.

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 only reflects the former case.

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.

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.

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.

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

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 .