v3.2: Guidance on searching and evaluating schemas

[handrews]

NOTE 1: This is intended to clarify requirements that already exist but have never been well-defined, both by making certain things required and stating clearly that other things are not. It is particularly relevant in light of the Encoding Object changes, although the vaguely-defined behavior predates the new features.

Some OAS features casually state that they depend on the type of data being examined, or implicitly carry ambiguity about how to determine how to parse the data.

This section attempts to provide some guidance and limits, requiring only that implementations follow the unambiguous, statically deterministic keywords $ref and allOf.

It also provides for just validating the data (when possible) and using the actual in-memory type when a schema is too complex to analyze statically.

One use of this is breaking apart schemas to use them with mixed binary and JSON-compatible data, and a new section has been added to address that.

Finally, a typo in a related section was fixed.

• schema changes are included in this pull request
• schema changes are needed for this pull request but not done yet
• no schema changes are needed for this pull request

[handrews]

@karenetheridge while I have your attention, do you think this is fine where it is or should it go under the Schema Object somewhere? I really could not decide.

[handrews]

I'm putting this in draft because based on @karenetheridge's feedback I'm going to rework it fairly substantially, but it's still of use when understanding how it fits with the other related PRs.

The effect of the rewrite should be the same, but I think the wording and organization will be significantly different. It's clear that the different use cases here need to be separated out and clarified. I think this ended up being a bit oddly abstract because of how I tried to split things up into PRs that don't conflict.

[handrews]

I have added a commit that almost totally rewrites this- you probably just want to review the whole thing and not look at the per-commit diff as it will be a mess. The new version:

• Puts most things under the Schema Object
• Organizes use cases by the point in the process they occur relative to schema evaluation
• Links from elsewhere in the spec so that we do not need to include quite as much in the main part of the text

I do not think that has changed anything substantial, but it's essentially a new PR now.

[handrews]

@karenetheridge I'm going to mark various threads as resolved since the text is now so different that they are confusing- please do not take that to mean I'm dismissing open questions, please just re-start whatever is needed with comments on the new text, or as new top-level comments. Apologies for the inconvenience.

[handrews]

@karenetheridge I trimmed back the multi-valued type requirements as from our discussion I just see too many ways it can go wrong. Now it's just "if you have [X, "null"] treat it like X" and everything else is optional guidance. How does that sit with you?

[handrews]

@karenetheridge I'm marking various threads resolved as I think subsequent commits addressed them, and it's a lot of at least somewhat outdated discussion for folks to have to read through before tomorrow's call. Please feel free to re-raise anything that is still not addressed.