Support standard extensions with "$requires"

[handrews]

The most contentious topic in JSON Schema, for many years, has been what sort of re-use functionality should be supported. In particular, how to both use "additionalProperties": false to prevent misspelled property names, and allow adding more property names when re-using such a schema.

This is not actually the intended purpose of "additionalProperties", and as of draft-06 "propertyNames" is preferred, but can be cumbersome. Also, many years of telling people not to use "additionalProperties" in this manner have had no effect whatsoever.

The proposal that attracts both the strongest support and strongest objections is #15 "$merge"/"$patch". It is by far the most powerful, but also breaks the theoretical model of JSON Schema validation as a constraint system in which you can add but never remove constraint. These two keywords allow arbitrary transformations.

We need to balance several things:

• Feature support for people who consider this a barrier to adoption
• Theoretical purity for those who do not need and do not want these features
• Interoperability for both groups, either uniform support or a clear fail-fast outcome

The simplest way to implement this is to allow declaring that your schema requires an optional feature. The implementations can either process your schema, or error out with a message that the feature is not supported.

This is only needed for extensions to core, such as "$merge" and "$patch". Unlike "format", which is still of use to applications even when not used for validation, and does not change the behavior of anything else when it is ignored, there is no possible way to use a schema involving "$merge" or "$patch" without supporting those keywords.

---

So I am proposing adding "$requires" to core as an extensibility mechanism. The value of this keyword MUST be an array. Elements in the array MUST be URIs identifying the extensions required to properly make use of the schema.

Implementations MUST error out if they do not support, or do not recognize, a required extension.
Implementations MUST NOT automatically attempt to dereference the URI, as such URIs need not be dereferencable at all, and the canonical server should not be overloaded by unnecessary requests.

The initial declared extensions would be something like http://json-schema.org/draft-07/extensions.$merge or tag:json-schema.org,2017-10-15:extensions.$patch depending on whether we want to stick with HTTP URIs or use an obviously not-dereferenceable scheme such as tag.

"$merge" and "$patch" would be separately declared extensions, as different users prefer different approaches, needing one or the other or both.

Also paging @erayd

[erayd]

A few thoughts - posting this from my phone, so briefly:

1. Can we call it $features rather than $require? That feels more semantically accurate, and prevents confusion with languages / frameworks that use 'require' as an inclusion keyword.

2. If we're using a URI to refer to a feature, that URI could also point to a meta-schema that validates use of the feature - essentially the same role that $schema serves for the core stuff.

3. If this proposal goes ahead, it gives custom keywords a proper home. Noting this, can we then go ahead and ban undefined keywords completely? I.e. a keyword must be defined by the core or an enabled feature in order to be valid, and unknown keywords result in a validation fail.

[erayd]

To further clarify my point (2) above, I'm not suggesting that implementations dereference this, merely that defining the URI as the canonical home of a meta-schema that validates the referenced feature makes sense, and allows used to easily locate the definition for any given feature.

[Anthropic]

@erayd re: 3, I think failing on undefined keywords would be a huge pain without a prefix based comment exclusion. I always test schema by slashing keywords "//keyword" to reduce what I am testing, it would be an unwelcomed outcome to not be able to easily exclude large parts of a schema when testing due to validation errors I don't want.

[erayd]

@Anthropic
That's a really good point. What if the default was to ban undefined keywords, but there was also a mechanism to turn that constraint off?

[Anthropic]

I'd prefer a definable prefix exclusion, but that's a whole other discussion already going on in the $comment thread I've been meaning to get back to :)

As for this I agree the name doesn't feel right to me, I'd prefer something like $keywords, $uses or $requiredSpecs. Not set on anything clearly, but $requires is too close to required for my comfort.