How do I subclass a JSON schema

Question

How do I subclass in JSON-Schema?

First I restrict myself to draft-07, because that's all I can find implementations of.

The naive way to do sub-classing is described in

https://json-schema.org/understanding-json-schema/structuring.html#extending

But this works poorly with 'additionalProperties': false?

Why bother with additionalProperties': false?

Without it - nearly any random garbage input json will be considered valid, since all the 'error' (mistaken json) will just be considered 'additionalProperties'.

Recapping https://json-schema.org/understanding-json-schema/structuring.html#extending

use allOf(baseClass)
then add your own properties

The problem with this - is that it doesn't work with 'additionalProperties' (because of unclear but appantly unfortunate definitions of additionalProperties that it ONLY applies to locally defined (in that sub-schema) properties, so one or the other schema will fail validation.

Alternative Approaches:

meta languages/interpretters layered on top of JSONSchema (such as https://github.com/mokkabonna/json-schema-merge-allof)

This is not a good choice as the scehma can only be used from javascript (or the language of that meta processor). And not easily interoperable with other tools
https://github.com/java-json-tools/json-schema-validator/wiki/v5%3A-merge
An alternative I will propose as a 'solution' / answer

You should switch to an implementation supporting draft-2019-09 if you can, because this is exactly why unevaluatedProperties (and $recursiveRef) were added. — Ether
OK - I'm sold! which one do you recommend for Python? - And by the way, though thats a GREAT answer (happy this has been solved in 2019-09) - I didn't find any documentation indicating that. In fact, the docs on json-schema.org/understanding-json-schema/… maybe should be updated to reflect this? — lewis
@lewis We would love to complely overhaul the understanding site with nice documentation, but it all takes time. None of us get paid to work on JSON Schema during work hours. Pull Requests welcome! As an aside, we have a great and active slack community should you want to discuss things =] — Relequestual
I did NOT mean to complain about your volunteer work. I do my own open source projects, and I appreciate it when people post (thoughtful) complaints about lacking in documentation. We all want the work we do to be widely used and accessible. I'm too naive about JSONSchema to be a useful contributer at this point, but that could change. I will give your slack channel a shot; just joined. THANKS — lewis
@lewis it doesn't look like there is a draft-2019-09 implementation for python yet -- json-schema.org/implementations.html -- but I can recommend the Perl implementation authored by Yours Truly :D — Ether

lewis lewis · Accepted Answer · 2020-08-20T01:34:21

This isn't a GREAT answer. But until the definition of JSONSchema is improved (or someone provides a better answer) - this is what I've come up with as workable.

Basically, you define two copies of each type, the first with all the details but no additionalProperties: false flag. Then second, REFERENCING the first, but with the 'additionalProperties: false' set.

The first you can think of as an 'abstract class' and the second as a 'concrete class'.

Then, to 'subclass', you use the https://json-schema.org/understanding-json-schema/structuring.html#extending approach, but referencing the ABSTRACT class, and then add the 'additionalProperties: false'. SADLY, to make this work, you must also REPEAT all the inherited properties (but no need to include their type info - just their names) - due to the sad choice for how JSONSchema draft 7 appears to interpret additionalProperties.

An EXAMPLE - based on https://json-schema.org/understanding-json-schema/structuring.html#extending should help:

https://www.jsonschemavalidator.net/s/3fhU3O1X

(reproduced here in case other site /link not permanant/reliable)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://TEST",
  "definitions": {
    "interface-address": {
      "type": "object",
      "properties": {
        "street_address": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "state": {
          "type": "string"
        }
      },
      "required": ["street_address", "city", "state"]
    },
    "concrete-address": {
      "allOf": [
        {
          "$ref": "#/definitions/interface-address"
        }
      ],
      "properties": {
        "street_address": {},
        "city": {},
        "state": {}
      },
      "additionalProperties": false
    },
    "in-another-file-subclass-address": {
      "allOf": [
        {
          "$ref": "#/definitions/interface-address"
        }
      ],
      "additionalProperties": false,
      "properties": {
        "street_address": {},
        "city": {},
        "state": {},
        "type": {
          "enum": ["residential", "business"]
        }
      },
      "required": ["type"]
    },
    "test-of-address-schemas": {
      "type": "object",
      "properties": {
        "interface-address-allows-bad-fields": {
          "$ref": "#/definitions/interface-address"
        },
        "use-concrete-address-to-only-admit-legit-addresses-without-extra-crap": {
          "$ref": "#/definitions/concrete-address"
        },
        "still-can-subclass-using-interface-not-concrete": {
          "$ref": "#/definitions/in-another-file-subclass-address"
        }
      }
    }
  },
  "anyOf": [
    {
      "$ref": "#/definitions/test-of-address-schemas"
    }
  ]
}

and example document:

{
   "interface-address-allows-bad-fields":{
      "street_address":"s",
      "city":"s",
      "state":"s",
      "allow-bad-fields-this-is-why-we-need-additionalProperties":"s"
   },
   "use-concrete-address-to-only-admit-legit-addresses-without-extra-crap":{
      "street_address":"s",
      "city":"s",
      "state":"s"
   },
   "still-can-subclass-using-interface-not-concrete":{
      "street_address":"s",
      "city":"s",
      "state":"s",
      "type":"business"
   }
}

How do I subclass a JSON schema

How do I subclass in JSON-Schema?

2 Answers

Composition over inheritance

Polymorphism