Skip to content

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

Open
wants to merge 6 commits into
base: v3.2-dev
Choose a base branch
from

Conversation

handrews
Copy link
Member

@handrews handrews commented Jun 21, 2025

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

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.
@handrews handrews added this to the v3.2.0 milestone Jun 21, 2025
@handrews handrews requested a review from a team as a code owner June 21, 2025 01:12
@handrews handrews requested a review from a team as a code owner June 21, 2025 01:12
@handrews handrews added the media and encoding Issues regarding media type support and how to encode data (outside of query/path params) label Jun 21, 2025
@handrews
Copy link
Member Author

@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 handrews marked this pull request as draft June 22, 2025 03:57
@handrews
Copy link
Member Author

handrews commented Jun 22, 2025

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.
@handrews
Copy link
Member Author

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 handrews marked this pull request as ready for review June 22, 2025 22:08
@handrews
Copy link
Member Author

@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 and others added 2 commits June 27, 2025 15:06
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.
@handrews
Copy link
Member Author

@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
Copy link
Member Author

handrews commented Jul 9, 2025

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
media and encoding Issues regarding media type support and how to encode data (outside of query/path params) schema-object
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants