[dinwwwh]

Requested by dinwwwh · project thread

Summary

A record whose values are a nullable $ref to an enum, such as z.record(z.string(), Status.nullable()) with Status registered by .meta({ id }), has additionalProperties: { anyOf: [{ $ref }, { type: "null" }] } in 3.1. In 3.0 that becomes a oneOf of the $ref and the "null" branch, as designed.

OpenAPI Generator 7.26 merges those two branches into an inline enum (the SIMPLIFY_ONEOF_ANYOF_ENUM normalizer the README already names). Its Kotlin client then types a map of an inline enum as the enum itself, so the property is generated as val v: Request.V and not as a map. Every map is rejected, with Moshi and with kotlinx.serialization alike:

JsonDataException: Expected a string but was BEGIN_OBJECT at path $.v

From 3.1, the same property is Map<String, E?> and every value round-trips.

The README line about OpenAPI Generator leaving null out of array items and map values listed Kotlin. In 7.26, Kotlin keeps null for array items (inline or $ref), so this PR moves Kotlin out of that sentence and adds one about the map.

What was checked

I compiled each shape with -g kotlin (Gradle) from the 3.1 input and from the 3.0 output, then decoded and re-encoded valid instances with the client's serializer.

Shape	3.1	3.0
required or optional map of nullable enum $ref	Map<String, E?>, ok	the enum, rejects every map
map of non-null enum $ref	ok	ok
map of nullable string	ok	ok
array of nullable enum, $ref or inline	ok	ok
map of inline enum, nullable or not	the enum in both versions	same

With --openapi-normalizer SIMPLIFY_ONEOF_ANYOF_ENUM=false, the 3.0 map is kept, but its values become a wrapper class that still rejects every non-null value. So the README doesn't suggest the flag here.

Only README text changes. uncheck passes.

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed]

Merging this PR will not alter performance

1 warning

⚠️ 1 benchmark is dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

✅ 29 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing claude/project-thread-fvev8j (3742761) with main (63c5996)}

Footnotes

1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[pullfrog]

✅ No new issues found.

Reviewed changes

• Kotlin moved out of the null-dropping sentence — the OpenAPI Generator limitations bullet now names only TypeScript and Swift as clients that "leave null out of the type of an array item or map value" that is a nullable $ref or enum.
• Added Kotlin map-of-nullable-enum note — in 7.26, OAG's Kotlin client reads a map whose values are a nullable $ref to an enum (e.g. z.record of a registered z.enum with .nullable()) as that enum, rejecting every such map; the caveat now says 3.1 "keeps the null and the map".

The new claim checks out against OpenAPI Generator v7.26.0: kotlin-client/data_class_{req,opt}_var.mustache has no {{#isMap}} branch inside {{#isEnum}}, so a map-of-enum property is typed as the enum and the Map is dropped (upstream issue #25453, open fix #25474). The path runs through the default SIMPLIFY_ONEOF_ANYOF_ENUM merge already documented one bullet above, which turns the nullable $ref into an inline enum. uncheck packages/downgrader/README.md passes.

  ^{｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}