Web of Things (WoT) JSON Schema Ontology

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.

Please note that the Turtle version of the ontology can be always obtained by doing content negotiation as explained in Appendix D of the Thing Description Recommendation. You can include Accept: text/turtle in the request to obtain the Turtle version of this ontology.

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`

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

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:descriptionInLanguage` `td:titleInLanguage`
In the range of	`jsonschema:allOf` `jsonschema:anyOf` `jsonschema:items` `jsonschema:oneOf` `jsonschema:properties`

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`

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

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`

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`

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`

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`

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`

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`

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`

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

Data schema nested definitions

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

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

Provides a constant value.

Domain includes jsonschema:DataSchema

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

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

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

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

Restricted set of values provided as an array.

Domain includes jsonschema:DataSchema

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

No AnnotationProperty found in the ontology.

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

Example 1: JSON-LD 1.1 context for the JSON schema vocabulary

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

Example 2: Number schema representing a byte

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

Example 3: Object schema for a temperature measurement

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

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.

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.

Example 4: Object schema for light control with reference to a base schema

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

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.

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.

Example 5: Schema with context annotation

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

Example 6: Instance interpreted as JSON-LD

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

Example 7: Schema with embedded context

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

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.

Example 8: SAREF on/off state with embedded schema definition

{
    "@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 Example 3.

Example 9: SAREF temperature property with embedded schema definition

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

Web of Things (WoT) JSON Schema Ontology

Abstract

Status of This Document

1. Introduction

2. Conformance

3. Terminology

4. Axiomatization

4.1 Classes

4.1.1 ArraySchema

4.1.2 BooleanSchema

4.1.3 DataSchema

4.1.4 IntegerSchema

4.1.5 NullSchema

4.1.6 NumberSchema

4.1.7 ObjectSchema

4.1.8 StringSchema

4.2 Object Properties

4.2.1 allOf

4.2.2 anyOf

4.2.3 items

4.2.4 oneOf

4.2.5 properties

4.3 Datatype Properties

4.3.1 const

4.3.2 contentEncoding

4.3.3 contentMediaType

4.3.4 default

4.3.5 enum

4.3.6 exclusiveMaximum

4.3.7 exclusiveMinimum

4.3.8 format

4.3.9 maxItems

4.3.10 maxLength

4.3.11 maximum

4.3.12 minItems

4.3.13 minLength

4.3.14 minimum

4.3.15 multipleOf

4.3.16 pattern

4.3.17 propertyName

4.3.18 readOnly

4.3.19 required

4.3.20 writeOnly

4.4 Annotation Properties

5. Usage Examples

5.1 Interpreting JSON Schema as JSON-LD 1.1

5.2 Referencing and linking

5.3 Defining a JSON-LD context for data instances

5.4 Embedding schema definitions in data instances

A. References

A.1 Normative references