spec: remove/change extending meta-schemas recommendation

[epoberezkin]

https://github.com/json-schema-org/json-schema-spec/blob/master/jsonschema-core.xml#L254

The suggestion to extend meta-schemas using allOf (assuming that one of subschemas is $ref) is not feasible because meta-schemas are recursive and they have references to the meta-schema itself ("#"). Therefore if meta-schema is extended using $ref to the original meta-schema the # ref in that meta-schema will not point to the extended one, it will still point to the original, so the schemas would not be properly validated.

The only working meta-schema extension mechanism at the moment is copy-pasting and adding keywords, suggestion to use allOf is misleading because it implies $ref.

We have several options:

1. Suggest copy-pasting with explanation why it is the only working option
2. Adopt $merge/$patch keywords proposed by @fge
3. Drop this suggestion from this version of the spec until we agree what is the right thing.

Happy to draft 1, can draft 2 as well...

[handrews]

For any extension of JSON Schema, if an instance validates against the extended version, it should also validate against the regular JSON Schema. So while you do need to re-declare the properties with child schemas so that those children reference the extended meta-schema, doing that within the allOf is sufficient to make everything work.

If your extension sets additionalProperties to false (which is not advised), then we're back in a specific re-use problem, and I have a very detailed proposal that I hope to post today or tomorrow (it's derived from use cases and vague proposals from the email thread on the google group a while back). So, @epoberezkin , please wait before writing up $merge/$patch. For one thing, it's already written up as issue #15 , even if not specifically for this case.

[awwright]

Without thinking too much about it, I'd venture to guess that patching the official meta-schema to replace all meta-schema references references to your own meta-schema would be really painful (at least if absolute URIs were used exclusively)

[epoberezkin]

patching the official meta-schema to replace all meta-schema references references to your own meta-schema would be really painful

@awwright you don't need to. See the example below.

doing that within the allOf is sufficient to make everything work.

@handrews if you limit the definition of "work" to "pass validation of valid schemas", allOf keyword would indeed be sufficient. Actually with this definition of "working" you don't have to extend the original meta-schema at all. If you include into the definition of "work" the requirement "to fail validation of invalid schemas" then it won't work.

Consider the example: you add a new keyword my to the schema vocabulary that must be boolean. To validate your new keyword you extend the meta-schema in this way:

{
  "id": "draft6_with_my",
  "$schema": "draft6",
  "allOf": [
    { "$ref": "draft6" },
    { "properties": { "my": { "type": "boolean" } } }
  ]
}

That's what I think the suggestion of using allOf implies.

Now this schema would indeed be invalid, as it should be:

{
  "$schema": "draft6_with_my",
  "my": "foo"
}

But this schema will be valid, although it must be invalid:

{
  "$schema": "draft6_with_my",
  "properties": {
    "prop": { "my": "foo" }
  }
}

The schema above will be valid because the subschema for "prop" property will be validated using the original rather than the extended meta-schema. I hope it makes sense.

Now, to address this issue without using copy-paste with the proposed @merge keyword you can write the meta-schema in this way, (@awwright without the need to patch all the references):

{
  "id": "draft6_with_my",
  "$schema": "draft6",
  "$merge": {
    "source": { "$ref": "draft6" },
    "with": { "properties": { "my": { "type": "boolean" } } }
  }  
}

The result of this merge should be the new schema where all the refs to # would point to this new schema, rather than to the original, and this new schema would have "my" keyword added to the list of standard keywords, so it would validate it on all levels. Or at least that's my interpretation of what @merge should be doing.

In any case, whether we add @merge or not is another issue, I agree. But "allOf" approach doesn't work as you can see from the example, unless you copy paste the whole schema instead of using $ref (which would not be different from simply editing this copy without using allOf).

[epoberezkin]

@awwright Actually, that also means that $ref in $merge should mean a different thing from $ref outside of $merge (inlining vs validating - see #85 (comment)). So maybe we should add one more $ keyword for inlining instead of using $ref for both purposes. That would make sense actually because in $ref'd (=referenced) schemas refs will be resolved based on the ID of $ref'd schema and in inlined schemas ($inline?) refs will be resolved based on the ID in the current schema. You kind of need both for different use-cases...

[awwright]

I... I'll need to contemplate this when I'm feeling a little more awake

[epoberezkin]

Yep... Needs some thinking indeed

[epoberezkin]

I will sleep on it and create another issue proposing this $inline (or whatever it's called) thing with motivation, explanation and examples.

[handrews]

@epoberezkin : You don't need to change $ref to get $merge to work. We implemented it at Riverbed and used it extensively. You just need to ensure that $merge is also late-binding.

Here's the (I think) most concise way of handling this without $merge:

{
    "id": "draft6_with_my",
    "$schema": "draft6",
    "allOf": [
        { "$ref": "draft6" },
        {
            "properties": {
                "my": { "type": "boolean" },
                "properties": { "$ref": "#" },
                "patternProperties": { "additionalProperties": { "$ref": "#" } },
                "additionalProperties": { "oneOf": [ { "type": "boolean" }, { "$ref": "#" } ] },
                "items": { "oneOf": [ { "$ref": "#" }, { "type": "array", "items": { "$ref": "#" } } ] },
                "additionalItems": { "oneOf": [ { "type": "boolean" }, { "$ref": "#" } ] },
                "dependencies": { "additionalProperties": { "oneOf": [ { "type": "string" }, { "$ref": "#" } ] } },
                "anyOf": { "type": "array", "items": { "$ref": "#" } },
                "allOf": { "type": "array", "items": { "$ref": "#" } },
                "oneOf": { "type": "array", "items": { "$ref": "#" } },
                "not": { "$ref": "#" },
                "definitions": { "additionalProperties": { "$ref": "#" } }
            }
        }
    ]
}

While "concise" might be stretching it, it is actually quite clear. A shorthand would be useful, but as you'll soon see with my forthcoming issue on re-using schemas that set additionalProperties to be false, trying to have schemas that are being re-used together produce a result that depends on both of them is highly problematic.

I have also come around to the idea that $merge and $patch are too generic and powerful to be part of JSON Schema. The correct option might simply be for someone to implement those separately and then folks can have a build step that processes them out before feeding the results to any actual JSON Schema validator.

[jdesrosiers]

The Hyper-Schema meta schema is a real-life example of the difficulties with extending JSON Schema.

[handrews]

One thing worth considering is whether this is a use case that really needs optimizing. How often will people extend the schema? Also, the meta-schemas shouldn't be changing. Even if we release new updates frequently while driving this to completion, each new revision should be a new document, with the old ones left valid. So while I loathe copy-pasting, it's pretty safe here.

[epoberezkin]

Here's the (I think) most concise way of handling this without $merge

Copying 50% of the schema is marginally better than copying it all. You still need to repeat all the keywords that contain schemas, and the new keywords are coming.

How often will people extend the schema?

The meta-schema extension is needed to validate application specific custom keywords. A lot of people use custom keywords in their schemas and the proper way is to define your own meta-schema that would validate both standard and custom keywords. At the moment, because there is no extension mechanism, Ajv allows to define micro-meta-schemas for each custom keyword separately, but it seems a wrong solution - the correct one is to be able to validate the whole schema.

The fact that $merge is powerful seems to be the argument to use it, rather than to not use it. We use $merge not only for meta-schema extension, but to derive similar schemas from one schema without having "additionalProperties" issue. So I don't really understand the opposition.

In any case, this issue is not about $merge, it's about the paragraph in the spec that encourages users to extend meta-schemas giving them misleading recommendations how to do it. Nobody will make a mental leap from the suggestion to use allOf to the realisation that you need to copy/paste 50% of the original meta-schema inside allOf.

[epoberezkin]

@handrews see this comment: #85 (comment)

In addition to being not concise, the meta-schema you suggest will validate many keywords twice. I don't think there are any validators smart enough to avoid it.