Skip to content

fix(openapi3): set nullable on each variant of a nullable union in OpenAPI 3.0 - #12631

Open
om singhal (Om-singhaI) wants to merge 2 commits into
microsoft:mainfrom
Om-singhaI:fix/openapi3-nullable-union-variants
Open

om singhal (Om-singhaI) wants to merge 2 commits into
microsoft:mainfrom
Om-singhaI:fix/openapi3-nullable-union-variants

Conversation

@Om-singhaI

Copy link
Copy Markdown
Contributor

Fixes #8661

With openapi-versions: ["3.0.0"], a union of more than one type plus null puts nullable: true on the anyOf wrapper. OpenAPI 3.0 only honors nullable when type is set on the same schema, so the flag is ignored and strict validators reject the schema. For bar: string | int32 | null, main emits

bar:
  anyOf:
    - type: string
    - type: integer
      format: int32
  nullable: true

and this branch emits

bar:
  anyOf:
    - type: string
      nullable: true
    - type: integer
      format: int32
      nullable: true

This follows the approach suggested in the issue: nullable: true on each variant. The emitter already does this when one of the variants is a reference, so that path and the single variant case are unchanged. Without a reference, union level constraints such as the description stay on the wrapper. OpenAPI 3.1 and 3.2 output is not affected, and none of the OpenAPI 3.0 documents checked into the repo change. References that the emitter wraps in allOf, such as an enum or a named union, keep their current output.

One limitation: @oneOf unions get the same treatment, so null matches every variant and oneOf still rejects it. Ajv now accepts "a" and 5 there but not null, where before it could not compile the schema at all. The reference path already puts nullable on every variant, so I kept the two consistent. I can put nullable on a single oneOf variant instead if you prefer.

In packages/openapi3/test/union-schema.test.ts I updated the 3.0 test defines nullable properties with multiple variants, which asserted the wrapper nullable, and added cases for a literal mixed with a scalar, a named union with a doc comment, and a @oneOf union. I also added a changeset.

Testing, in packages/openapi3 on current main:

  • vitest run test/union-schema.test.ts test/nullable-properties.test.ts: 145 passed. With src/schema-emitter-3-0.ts from main, the 4 changed or new cases fail and the other 141 pass.
  • The same run plus enums, merge-patch, models and primitive-types tests: 6 files, 616 passed.
  • Ajv 8.20.0 on the emitted bar schema: the one from main throws "nullable" cannot be used without "type", the new one accepts null, "a" and 5.

…enAPI 3.0

A union such as `string | int32 | null` was emitted as an `anyOf` with
`nullable: true` on the wrapper. OpenAPI 3.0 ignores `nullable` unless
`type` is set on the same schema, so null was not accepted and strict
validators reject the schema. Put `nullable: true` on each variant
instead, as the emitter already does when one of the variants is a
reference.

Fixes microsoft#8661
@azure-pipelines

Copy link
Copy Markdown
Azure Pipelines:
Successfully started running 1 pipeline(s).
1 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

emitter:openapi3 Issues for @typespec/openapi3 emitter

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: @typespec/openapi3 Nullable union expression generates invalid openapi3

1 participant