JSON Schema in RDF

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.

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 of	`jsonschema:DataSchema`
In the domain of	`jsonschema: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 of jsonschema: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 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`

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`

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

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`

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`

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`

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 includes	`jsonschema:DataSchema`
Range includes	`jsonschema: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 includes	`jsonschema:DataSchema`
Range includes	`jsonschema:DataSchema`

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`

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`

properties

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

Data schema nested definitions

Domain includes	`jsonschema:ObjectSchema`
Range includes	`jsonschema:DataSchema`

Datatype Properties

const

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

Provides a constant value.

Domain includes jsonschema:DataSchema

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

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

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

enum

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

Restricted set of values provided as an array.

Domain includes jsonschema:DataSchema

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotation Properties

No AnnotationProperty found in the ontology.

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.

{
    "@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" }
    }
}

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

{
    "type": "integer",
    "minimum": 0,
    "maximum": 255
}

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

{
    "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"]
}

@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" .

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.

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.

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.

{
    "@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#"
        }
    ]
}

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.

{
    "@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" }
    }
}

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.

{
    "@context": "http://schema.org",
    "name": "some manufactured product",
    "gtin14": "0 00 12345 60001 2",
    "manufacturer": "http://comapny.example.com"
}

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.

{
    "@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" }
    }
}

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.

{
    "@context": {
        ...,
        "saref": "http://w3id.org/saref#",
        "schema": "http://schema.org/"
    },
    "@type": "saref:LightSwitch",
    "saref:hasState": {
        "@type": "saref:OnOffState",
        "type": "boolean"
    }
}

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 .

{
    "@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"
        }
    }
}

Introduction

Axiomatization

Classes

ArraySchema

BooleanSchema

DataSchema

IntegerSchema

NullSchema

NumberSchema

ObjectSchema

StringSchema

Object Properties

allOf

anyOf

items

oneOf

properties

Datatype Properties

const

contentEncoding

contentMediaType

default

enum

exclusiveMaximum

exclusiveMinimum

format

maxItems

maxLength

maximum

minItems

minLength

minimum

multipleOf

pattern

propertyName

readOnly

required

writeOnly

Annotation Properties

Usage Examples

Interpreting JSON Schema as JSON-LD 1.1

Referencing and linking

Defining a JSON-LD context for data instances

Embedding schema definitions in data instances