Skip to content

v3.1.2: Allow xml field/keyword in any schema as a MAY #4613

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

Closed
wants to merge 1 commit into from

Conversation

handrews
Copy link
Member

Suggested by @ralfhandl in #4576 (comment) on the grounds that some vendors already do this anyway.

This allows implementations to support the xml Schema Object field / JSON Schema extension keyword in any Schema Object, with a recommendation that the behavior be forward-compatible with OAS 3.2.

This does not break 3.1 compatibility, but it is a bit unusual as a patch release change as it does allow for additional functionality, and unlike the additional MAY guidance on $dynamicRef in 3.1.1, it is not just adding guidance to an area where we were silent.

On the other hand, we can look at it as a "we're not adding a new feature, we're just telling you how you can be compatible with future changes" thing. idk how that fits with our compatibility story.

I'm fine with including this in 3.1.2, and I'm fine rejecting it and just letting people figure out that they can, of course, "backport" 3.2 functionality as "extensions". But I figured it was worth a quick write-up based on @ralfhandl 's comment.

  • 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

This allows implementations to support the `xml` Schema Object
field / JSON Schema extension keyword in any Schema Object, with
a recommendation that the behavior be forward-compatible with
OAS 3.2.
@handrews handrews added this to the v3.1.2 milestone May 18, 2025
@handrews handrews requested review from a team as code owners May 18, 2025 16:20
@handrews handrews added xml media and encoding Issues regarding media type support and how to encode data (outside of query/path params) labels May 18, 2025
@ralfhandl ralfhandl requested a review from a team May 19, 2025 12:11
@lornajane
Copy link
Contributor

I'm really not sure we should allow these fields in new places in a patch release. I like the idea, are we doing it in 3.2 anyway?

@handrews
Copy link
Member Author

@lornajane We are doing it in 3.2. Whatever you and @ralfhandl can agree on is fine with me, I posted this because he advocated for it.

@ralfhandl
Copy link
Contributor

Let's do this in 3.2 and not in 3.1.2

@handrews
Copy link
Member Author

Seems like we can close this- thanks for sorting it out, folks!

@handrews handrews closed this May 23, 2025
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) xml
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants