Repository navigation
Support the OpenAPI 3.1 forms of nullability - #193
Merged
svix-jplatte merged 2 commits intoOct 26, 2026
Merged
Conversation
The codegen only understood the OpenAPI 3.0 spelling, `nullable: true`.
Fed a spec that uses the correct 3.1 forms it silently dropped most of
the API: a field typed `"type": ["string", "null"]` made its whole
containing type unsupported, and an `anyOf`-wrapped $ref query
parameter made the whole operation unsupported.
Add a normalisation step in the schema conversion that rewrites the
3.1 forms before dispatch:
- `"type": [T, "null"]` becomes `"type": T`, nullable
- `anyOf`/`oneOf` with a `{"type": "null"}` variant unwraps to the
other variant (carrying over siblings like `description`/`default`),
nullable
The legacy `nullable: true` keeps working, and `Field.nullable` is now
set from either spelling, so the templates need no changes. Path/header
parameter validation accepts the array form too.
Verified with the debug IR dump against svix-webhooks'
codegen/lib-openapi.json (678 nullable sites) converted to the 3.1
forms with the jq recipe from svix/svix-webhooks#2551: before, the IR
kept 36 of 252 types and 118 of 141 operations; with this change it is
byte-identical to the IR produced from the current (3.0-spelling) spec,
and the output for the current spec is unchanged.
Member
Thanks for the PR! The first change is what I was thinking of pretty much. The latter doesn't seem terribly important to support, but why not I guess :) So the approach sounds right, I'll review the actual code changes now. |
svix-jplatte
approved these changes
Oct 26, 2026
svix-jplatte
left a comment
Member
There was a problem hiding this comment.
Looks good to me. There's probably some things that can be simplified, but this is already less awkward than the status quo 😄
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
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.
Hi Jonas — this is the openapi-codegen side of svix/svix-webhooks#2551, following up on your comment there.
The problem, as I ran into it: the codegen only understands the 3.0 spelling,
nullable: true. Feed it a spec that uses the correct 3.1 forms and it quietly loses most of the API, because both new spellings bail out in the schema conversion:"type": ["string", "null"]on a field makes the whole containing type "unsupported", so the type is dropped with just a warning"anyOf": [{"$ref": "…"}, {"type": "null"}]on a query parameter makes the whole operation unsupportedWhat I changed is a small normalisation step in
src/api/types.rsthat runs before the existing dispatch:typearray containing"null"collapses to the other type, marked nullableanyOf/oneOfpair with a{"type": "null"}variant unwraps to the other variant, carrying over siblings likedescriptionanddefault, marked nullableField::from_schemanow derivesnullablefrom either spelling (the legacynullable: truekeeps working), andFieldTypesees the unwrapped schema — including nested positions like array items and map values, since those recurse through the same function. No template changes needed, they already key offfield.nullable. I also let the path/header parameter check accept the array form.How I checked it: I took the current
codegen/lib-openapi.jsonfrom svix-webhooks (678nullablesites) and rewrote it into the 3.1 forms with the jq recipe from the original issue report, then comparedopenapi-codegen debugoutput:So once this (or something like it) lands, the server side should be able to stop rewriting the correct form into the incorrect one. Happy to adjust the approach if you'd rather see it handled somewhere else.