Adding Semantic Annotations to JSON Schema

[vcharpenay]

This issue mirrors the one posted in the JSON Schema repository. Discussion should take place there, the present issue will just include the outcomes of it.

See json-schema-org/json-schema-spec#309.

[vcharpenay]

Issue

add semantic annotations in the JSON Schema snippets that are embedded in a Thing Description, in order to perform both validation and semantic processing with the same document (TD).

Proposals

1. embed @context elements in the schema (initial proposal)
   1. TD servients MUST ignore non-JSON-Schema-keywords during validation (stronger than 6.4 Extending JSON Schema, no modification required)
   2. JSON-LD keywords MUST always be ignored for validation (would require re-writing 6.4 Extending JSON Schema)
2. include a link to an external context in the schema using Hyper Schema (no modification required)
3. include links in the schema to context elements (idem)

Decision

Because using hyperlinks at such a fine granularity might not meet the constraints of certain IoT devices, 1. is preferred over 2./3. Moreover, since data type modeling in the Thing Description is likely to evolve, we also exclude 1.2. that requires changes in the JSON Schema specification.

We will therefore adopt 1.1. for our coming PlugFests. More precisely, JSON Schema snippets may include @id and @type keywords, such that, if the root definition is of type object, its properties object can be interpreted as a JSON-LD context. Here is an illustration:

Example

The following schema describes a robot IMU and includes semantic annotations:

{
  "type": "object",
  "properties": {
    "prop1": {
      "@id": "http://example.org/vocab#Acceleration",
      "@type": "@id",
      "$def": "#/definitions/def1"
    },
    "prop2": {
      "@id": "http://example.org/vocab#Orientation",
      "@type": "@id",
      "$def": "#/definitions/def1"
    }
  },
  "definitions": {
    "def1": {
      "type": "array",
      "minItem": "3",
      "maxItem": "3",
      "items": { "type": "number" }
    }
  }
}

The following object (extracted from above) is a valid JSON-LD context:

{
  "prop1": {
    "@id": "http://example.org/vocab#Acceleration",
    "@type": "@id",
    "$def": "#/definitions/def1"
  },
  "prop2": {
    "@id": "http://example.org/vocab#Orientation",
    "@type": "@id",
    "$def": "#/definitions/def1"
  }
}