Repository navigation
docs(downgrader): note OpenAPI Generator merging a nullable string enum $ref - #81
Conversation
…um `$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) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014n2RNMbadzMyFHr9E2AJou
![macroscopeapp[bot]](https://avatars.githubusercontent.com/in/900172?s=60&v=4){kind=small}
ApprovabilityVerdict: Approved at Macroscope's review found this PR approvable — This PR adds one limitation/workaround note to the downgrader README and changes no executable code or configuration. It has no runtime or production-path impact. You can add or adjust custom eligibility rules. Learn more. |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
![pullfrog[bot]](https://avatars.githubusercontent.com/in/1768019?s=60&v=4){kind=small}
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
packages/downgrader/README.md— adds one limitation bullet noting that OpenAPI Generator's defaultSIMPLIFY_ONEOF_ANYOF_ENUMnormalizer merges the"null"branch beside a string-enum$refinto a new inline enum, losing the reference, and recommending--openapi-normalizer SIMPLIFY_ONEOF_ANYOF_ENUM=falseto preserve it.
I checked the claim against upstream: .openapi-normalizer SIMPLIFY_ONEOF_ANYOF_ENUM is a real rule (default-on since 7.0.0), and in OpenAPINormalizer the enum-merge (processSimplifyAnyOfEnum, line 1384) runs before the null-stripping processSimplifyAnyOf (line 1406), so disabling it is indeed the flag that keeps the $ref. The documented null-branch shape matches what onlyNull() emits in packages/downgrader/src/v3.1-to-v3.0.ts:462. Flag syntax and bullet style match the surrounding docs.
deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏
) <!-- claude-projects-attribution: {"github_login":"dinwwwh"} --> _Requested by **dinwwwh** · [project thread](https://claude.ai/code/project/chan_01UcKMz91tMarPV1kWLVgLYE?thread=cmsg_01UcKMz91tMarPV1kWLVgLYEC8ii77bvJTYMXNpA7YYZXA)_ Adds one line to the 3.1 → 3.0 Schema limitations in `packages/downgrader/README.md`, next to the OpenAPI Generator line from #81. Kiota 1.36 reads the `type: "string"` of the `"null"` branch (`{ type: "string", nullable: true, enum: [null] }`, from #72 and #78) as a real type. So from the 3.0 output, `z.array(User.nullable())` items and a nullable union of several types come out as strings. Kiota also reads 3.1, which types them correctly. The null-branch shape stays as is, since every other shape tried breaks some other tool (an untyped or bare null shape fixes Kiota but breaks Ajv or hey-api). `pnpm run check` passes. --- _Generated by [Claude Code](https://claude.ai/code/session_01ABAx6Ud1HPRYdomPGUkrKG)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
Requested by dinwwwh · project thread
Adds one line to the 3.1 → 3.0 Schema limitations in
packages/downgrader/README.md.OpenAPI Generator's default
SIMPLIFY_ONEOF_ANYOF_ENUMnormalizer merges the"null"branch from #72 ({ type: "string", nullable: true, enum: [null] }) beside a$refto a string enum into a new inline enum, so the generated 3.0 client loses the referenced enum type. The null-branch shape stays as is, since every other shape tried breaks some other tool (oapi-codegen, datamodel-codegen, Ajv). The README now names the flag that keeps the reference:--openapi-normalizer SIMPLIFY_ONEOF_ANYOF_ENUM=false.Docs only.
pnpm run checkpasses.Generated by Claude Code