-
Notifications
You must be signed in to change notification settings - Fork 9.1k
v3.2: Guidance on searching and evaluating schemas #4743
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: v3.2-dev
Are you sure you want to change the base?
Conversation
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.
@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. |
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. |
Move things under the Schema Object, organize by use case and by the point in the process at which things occur, and link directly from more parts of the spec so that the parts in the Schema Object section can stay more focused.
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:
I do not think that has changed anything substantial, but it's essentially a new PR now. |
@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. |
Co-authored-by: Karen Etheridge <ether@cpan.org>
Also clarify that there is no one set list of keywords to search for, but rather each use case defines what is relevant.
@karenetheridge I trimmed back the multi-valued |
@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. |
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
andallOf
.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.