Skip to content

Support the OpenAPI 3.1 forms of nullability - #193

Merged
svix-jplatte merged 2 commits into
svix:mainfrom
ToniAdreal:support-openapi-31-nullable-forms
Oct 26, 2026
Merged

svix-jplatte merged 2 commits into
svix:mainfrom
ToniAdreal:support-openapi-31-nullable-forms

Conversation

@ToniAdreal

Copy link
Copy Markdown
Contributor

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 unsupported

What I changed is a small normalisation step in src/api/types.rs that runs before the existing dispatch:

  • a type array containing "null" collapses to the other type, marked nullable
  • an anyOf/oneOf pair with a {"type": "null"} variant unwraps to the other variant, carrying over siblings like description and default, marked nullable

Field::from_schema now derives nullable from either spelling (the legacy nullable: true keeps working), and FieldType sees 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 off field.nullable. I also let the path/header parameter check accept the array form.

How I checked it: I took the current codegen/lib-openapi.json from svix-webhooks (678 nullable sites) and rewrote it into the 3.1 forms with the jq recipe from the original issue report, then compared openapi-codegen debug output:

  • before this change: 36 of 252 types and 118 of 141 operations survive
  • with this change: byte-identical IR to what the current spec produces, and the output for the current spec itself is unchanged

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.

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.
@ToniAdreal
ToniAdreal requested a review from a team as a code owner October 26, 2026 11:31
@svix-jplatte

Copy link
Copy Markdown
Member

What I changed is a small normalisation step in src/api/types.rs that runs before the existing dispatch:

  • a type array containing "null" collapses to the other type, marked nullable
  • an anyOf/oneOf pair with a {"type": "null"} variant unwraps to the other variant, carrying over siblings like description and default, marked nullable

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 svix-jplatte left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me. There's probably some things that can be simplified, but this is already less awkward than the status quo 😄

Comment thread src/api/resources.rs Resolved
@svix-jplatte
svix-jplatte merged commit bf50d4c into svix:main Oct 26, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants