opis/json-schema

Support extra keywords in a vocabulary

gregsdennis opened this issue · 1 comments

Hello.

I've noticed from the docs that this library supports a multitude of custom keywords. Vocabularies were introduced with draft 2019-09 (which this library supports) to manage custom keywords.

Additionally, many (if not all) of them start with a $ (e.g. $data). This is specifically recommended against.

While the "$" prefix is not formally reserved for the Core vocabulary, it is RECOMMENDED that extension keywords (in vocabularies or otherwise) begin with a character other than "$" to avoid possible future collisions.

Please consider

  • creating one or more vocabularies to formally define your keywords
  • removing the $ from them

For an example of a custom vocabulary, please see my data keyword vocabulary spec.

I realize that this will be a breaking change, but these keywords exist in direct conflict with a recommendation of the specification.

@gregsdennis they do allow disabling these keywords.

Implementing support for $vocabulary, making a vocabulary, and publishing a meta-schema requiring the vocabulary would (like OpenAPI 3.1's extensions) allow the extensions to be interoperable. See json-schema-org/json-schema-spec#1295 for significant clarification of $vocabulary's behavior and use cases - no change from the intent of 2019-09 and 2020-12, but hopefully the implementation guidance is more clear.