Split "unevaluated*" into separate vocab for separate support indications

[handrews]

While responding at ajv-validator/ajv#1082 (comment) I was reminded that we technically allow validators to make an independent decision about supporting unevaluatedProperties and unevaluatedItems due to their dependence on annotation collection, which is not required for basic spec conformance.

We did that before the $vocabulary process had been developed. Which means that whether or not these keywords are considered errors is totally outside of that process, which is otherwise how we give schema authors control over ensuring support for the features on which they depend.

We could split those keywords out of the "applicator" vocabulary (perhaps in to an "annotated-applicator" vocabulary, or just "unevaluated", or something, the name isn't that important).

Then we could provide (or just tell people they can write, like we do with the different "format" vocabulary options) a meta-schema that is just like the standard one, but with the "unevaluated" (or whatever) vocabulary declared with false, or omitted entirely.

This would require meta-schema updates, but given that 2019-09 has barely been implemented at all and still does not even have a full test suite, rolling everything forward to a 2020-03 or 2020-04 that is aligned with OpenAPI 3.1 would be pretty reasonable. I will file a separate issue for tracking the question of whether the draft-08-patch1 release should be one with a new meta-schema or not.

[Relequestual]

Hum. Initially I was like 😕 but now I'm like 👌.

I think getting implementers prepared to support different standard setups is a good idea.

Splitting the unevaluated keywords and making them an optional vocabualry (declared with false value) would send the right signals to the lay user who maybe looks at the meta-schema but is unlikely to delve into the RFC documents (because we have to remember normal people don't do that very often... and it's not always easy).

I'm kinda for this.

In terms of "new draft release", I think it shouldn't be too hard to sell OAS on this, especially as it includes a number of fixes for them.

[handrews]

@Relequestual I think we would, by default, want to require them to be supported- they're in high demand and we want to encourage them to be adopted. But we can easily offer (or encourage people to create) a meta-schema that does not require them to be supported, which would be preferable for some scenarios.

[handrews]

TL;DR:

Options are

1. Do nothing. unevaluated* are part of the applicator vocabulary, but an implementation can more or less silently ignore them. This seems very bad.
2. Split them into their own vocabulary. Now schema authors can indicate whether they need the keywords supported.
   1. Default meta-schema requires them
   2. Default meta-schema does not require them
3. Just require them all the time and leave them in with the other applicators. It's not clear that anyone is implementing 2019 but not implementing unevaluated* anyway.

I favor 2.i: split them into their own vocabulary, but leave that vocabulary required by default.

[Relequestual]

I agree with the 2.i approach. That's the most ideal as it gives everyone what they want in some way, and makes it easier, but not advised, to not support unevaluated*.

They are the only keywords which currently depends on annotation collection, right?

[Julian]

I don't know that I have an opinion here yet, but is it the same with contentMediaType / content*?

[handrews]

@Julian sort-of. unevaluated* when fully implemented are actual assertions and can fail the schema validation. So having them be unpredictably implemented causes unpredictable validation results.

content* (contentEncoding, contentMediaType, and contentSchema) are all in their own vocabulary. There are also (as of draft 2019-09) purely annotations and not assertions.

There's some wording that says something like "applications are allowed to use contentEncoding and contentMediaType to parse the string, and then apply contentSchema to it, but the results of applying contentSchema MUST be returned separately from the main schema's results."

Which basically means that none of the content* keywords will directly cause a validation failure. But you can run the contentSchema separately which may fail even though the first schema containing the contentSchema passed.

This is covered in section 8.2, and if that's not clear then wording improvements would be welcome.

[Julian]

Thanks! Most of that makes sense I think to me (despite not being up to speed fully yet). Will have a look there.

[Relequestual]

Giving this the green light for a PR.