fix(schema): keep oneof validation out of rendered variants - #280
Merged
sudorandom merged 1 commit intoSep 11, 2026
Merged
Conversation
A protobuf oneof permits at most one member, and documentation renderers display every oneOf and anyOf branch as a variant. Encoding the at-most-one guard as one of those branches renders an untitled, propertyless option beside the real fields. Render the members as an anyOf of titled field schemas and assert at-most-one under not, which no renderer reads as a list of variants. The assertion holds when some member is set but not exactly one, so it stays proportional to the number of members. The member properties stay at the root of the message schema, which leaves nothing to merge into allOf and nothing for the request body to recover from there, so both are gone. (buf.validate.oneof).required still layers exactly-one as a sibling allOf.
Owner
|
Thanks for this! Mapping protobuf oneOf to OpenAPI has continuously been more complex than expected. This implementation checks out |
sudorandom
added a commit
that referenced
this pull request
Sep 11, 2026
The oneof encoding introduced in #280 composes per-container at-most-one constraints as separate allOf branches, but no fixture exercised more than one real oneof container in a single message. Add a two-container message with request-validation cases asserting each container's exclusivity applies independently: one member from each container is valid, two members of the same container are not.
Contributor
Author
|
most welcome! Honestly, mapping proto to OpenAPI in general is a pain, but thank you for maintaining this project! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This fixes a an issue introduced in #264.
While that PR introduced a fix to match protobuf's expected
oneofat-most-once behavior, it did so by introducing an extra, untitled branch that resulted in a phantom variant in documentation renderers (e.g. Mintlify).An alternative way of expressing the same rule is to have a sibling
notrule which is seemingly ignored by doc renderers.Additionally, the member properties now stay at the root of the message schema, which leaves nothing to merge into allOf and nothing for the request body to recover from there, so both are gone.