How do I define my own JSON Schema keyword and vocabulary?

Question

I would like to define a JSON schema vocabulary to extend any regular JSON schema with storage related metadata. As an example I would like to define a pk keyword which marks an arbitrary JSON property as a primary key.

My meta-schema looks like this:

{
  "$schema": "http://json-schema.org/draft/2019-09/schema#",
  "$id": "https://myschema/meta/storage-schema",
  "$vocabulary": {
    "https://json-schema.org/draft/2019-09/vocab/core": true,
    "https://json-schema.org/draft/2019-09/vocab/applicator": true,
    "https://json-schema.org/draft/2019-09/vocab/validation": true,
    "https://json-schema.org/draft/2019-09/vocab/meta-data": true,
    "https://json-schema.org/draft/2019-09/vocab/format": false,
    "https://json-schema.org/draft/2019-09/vocab/content": true,
    "https://myschema/vocab/storage-schema": false
  },
  "$recursiveAnchor": true,

  "title": "JSON Storage-Schema",
  "allOf": [
    {"$ref": "https://json-schema.org/draft/2019-09/schema"},
    {
      "$recursiveAnchor": true,

      "title": "storage vocabulary meta-schema",

      "type": ["object", "boolean"],
      "properties": {
        "pk": {
          "description": "Marks a property as primary key",
          "type": "boolean",
          "default": false
        }
      }
    }
  ]
}

And a corresponding JSON instance might be:

{
  "$id": "https://myschema/invoice.schema.json",
  "$schema": "https://myschema/meta/storage-schema",
  "type": "object",
  "properties": {
    "invoiceNumber": {
      "pk": true,
      "type": "string"
    },
    "invoiceIssueDate": {
      "type": "string"
    }
  }
}

However, I am not sure if I am on the right track. For example WebStorm's IntelliSense only offers the pk keyword as a top level keyword and not as a keyword for properties:

{
  "$id": "https://myschema/invoice.schema.json",
  "$schema": "https://myschema/meta/storage-schema",
  "$comment": "Webstorm IntelliSense works and pk documentation is displayed",
  "pk": false,
  "type": "object",
  "properties": {
    "invoiceNumber": {
      "$comment": "No webstorm IntelliSense and no documentation displayed",
      "pk": true,
      "type": "string"
    },
    "invoiceIssueDate": {
      "type": "string"
    }
  }
}

Does anyone have experience with meta-schemas and custom keywords and can confirm if I am doing it right?

Hi Martin. Vocabularies is new for JSON Schema draft 2019-09, and while that may seem "not very new", there are only a handful of implementations so far. (Specs are a slow moving world sometimes). So, are you sure WebStorm actually supports draft 2019-09? It seems unlikely. — Relequestual, Sep 30 '20 at 14:57
Sorry, we haven't put together any proper documentation on how to do this yet. We're relying on people coming to our JSON Schema slack server to talk about it. It looks like you're on the right tracks. Take a look at http://json-schema.org/draft/2019-09/json-schema-core.html#rfc.appendix.D - (You don't need $recursiveAnchor in your subschema) — Relequestual, Sep 30 '20 at 14:59
How you add a vocabulary will depend on the library you're using, but I have a good scenario for mine: https://gregsdennis.github.io/json-everything/usage/schema/vocabs.html — gregsdennis, Sep 30 '20 at 23:41

score 3 · Answer 1 · answered Oct 01 '20 at 07:22

Looks like WebStorm doesn't support draft 2019-09 of JSON schema yet. I used this online validator to check my meta schema and as far as I can see it does what I expected.

Taking into account the comments to my question the final result looks like:

{
  "$schema": "http://json-schema.org/draft/2019-09/schema#",
  "$id": "https://myschema/meta/storage-schema",
  "$vocabulary": {
    "https://json-schema.org/draft/2019-09/vocab/core": true,
    "https://json-schema.org/draft/2019-09/vocab/applicator": true,
    "https://json-schema.org/draft/2019-09/vocab/validation": true,
    "https://json-schema.org/draft/2019-09/vocab/meta-data": true,
    "https://json-schema.org/draft/2019-09/vocab/format": false,
    "https://json-schema.org/draft/2019-09/vocab/content": true,
    "https://myschema/vocab/storage-schema": false
  },
  "$recursiveAnchor": true,

  "title": "JSON Storage-Schema",
  "allOf": [
    {"$ref": "https://json-schema.org/draft/2019-09/schema"},
    {
      "title": "storage vocabulary meta-schema",

      "type": ["object", "boolean"],
      "properties": {
        "pk": {
          "description": "Marks a property as primary key",
          "type": "boolean",
          "default": false
        }
      }
    }
  ]
}

Thx for the helpful comments!

How do I define my own JSON Schema keyword and vocabulary?

1 Answers1