json-schema-spec icon indicating copy to clipboard operation
json-schema-spec copied to clipboard

Strengthen requirements around optional vocabularies

Open handrews opened this issue 3 years ago • 2 comments

Issue #1294 (implemented by PR #1295) includes a better explanation of optional vocabulary use cases, specifically supporting annotation-only vocabularies without needing any custom code.

Currently, implementations SHOULD process optional vocabularies that they do not understand, and SHOULD handle unrecognized keywords as annotations.

I don't remember why the first SHOULD exists - since it's already possible to disable annotation collection (if it's supported at all), and if annotations can't be collected then unrecognized keywords MUST be ignored, I think it makes sense to upgrade this to a MUST. Any negative impact can be mitigated by disabling annotation collection.

The second SHOULD ought to be converted to a MUST collect as annotations when annotations are enabled, and a MUST ignore otherwise. It was a SHOULD to avoid forcing collecting large values (e.g. subschemas of unknown applicators), which was a concern with non-vocabulary keywords. However, a vocabulary with such keywords can be included as required to avoid collecting applicators as annotations, so there's now another way to avoid that problem that makes more sense. If we keep non-vocabulary keywords, annotation collection can remain a SHOULD for those.

Finally, we should overall make it mandatory to support unrecognized optional vocabularies. We want people to make these as they don't require code, so we want them to be widely supported. Doing so is trivial (again, if annotations aren't supported then supporting unrecognized optional vocabularies means literally doing nothing).

handrews avatar Sep 19 '22 15:09 handrews

Given that #1294 is merged, can this be closed?

gregsdennis avatar Jan 17 '23 21:01 gregsdennis

@gregsdennis no, I had mistyped "PR 1294" when I meant issue 1294 which is implemented by PR 1295 (I've updated the text in the main description to match this).

This issue is about changing SHOULDs to MUSTs. 1294/95 clarified a lot of things, but did not change the requirement level as I was not confident there would be consensus on it.

I can go ahead and make a PR for this, though, seeing as no one has objected.

handrews avatar Jan 18 '23 18:01 handrews

This needs to be incorporated in the proposal for whatever vocabularies ends up being.

gregsdennis avatar Jun 18 '24 10:06 gregsdennis