From 9bcc822f2187a6b7bfc6aebc43b54c28303e590e Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 24 Oct 2026 06:34:05 +0000 Subject: [PATCH] docs(downgrader): note OpenAPI Generator merging a nullable string enum `$ref` OpenAPI Generator's default SIMPLIFY_ONEOF_ANYOF_ENUM normalizer merges the `"null"` branch beside a `$ref` to a string enum into a new inline enum, losing the reference. List it under the 3.1 to 3.0 Schema limitations with the flag that keeps it. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_014n2RNMbadzMyFHr9E2AJou --- packages/downgrader/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/downgrader/README.md b/packages/downgrader/README.md index cf344b9..a193e67 100644 --- a/packages/downgrader/README.md +++ b/packages/downgrader/README.md @@ -245,6 +245,7 @@ Accepts the default OAS dialect, which adds `discriminator`, `xml`, `externalDoc - Older drafts are not supported. `definitions` is read as `$defs`, but other keywords that only draft-07 or 2019-09 define, such as `dependencies` and `additionalItems`, become extensions unconverted, so `$ref`s into them dangle, and array-form `items` passes through. Convert such schemas to 2020-12 first. - `patternProperties` that matches every name, as TypeBox emits for a record, is removed with its value schema rather than turned into `additionalProperties`. - An untyped schema that gains a `format` from `contentEncoding` or `contentMediaType` also gains `type: "string"`, as 3.0 binary strings need, so it rejects non-string values it accepted. 3.0 tools find file uploads only by `type: "string"` with `format: "binary"`. +- OpenAPI Generator merges the `"null"` branch beside a `$ref` to a string enum into a new enum, so the reference is lost. Pass `--openapi-normalizer SIMPLIFY_ONEOF_ANYOF_ENUM=false` to keep it. ## Performance