Target: OpenAPITools/openapi-generator
Issue: OpenAPITools/openapi-generator#23550
PR: OpenAPITools/openapi-generator#24022
This field test targeted a Kotlin generator bug in OpenAPI Generator where a boolean const: true schema value was rendered into generated Kotlin code as the string "true" instead of the boolean literal true.
The visible issue was simple:
- an OpenAPI 3.1 schema defines a boolean constant value
- the generated Kotlin model treats the enum value as kotlin.Boolean
- the generator emits "true" as a string literal
- the resulting Kotlin code does not compile
That is a small surface area, but it is exactly the kind of failure that matters in code generators.
A generator does not get to be “almost right” when it emits source code. If the emitted literal does not match the target language type, the downstream project inherits a broken compile artifact.
The diagnostic question here was not:
How do we special-case this one schema?
The better question was:
Where does OpenAPI Generator already decide how enum values become Kotlin literals, and which primitive boundary is missing?
Field Lab record
The public case record for this field test is available in the Scarab Field Lab:
SDS result
This field test was run in SDS field-test posture against a disposable OpenAPI Generator arena.
The useful diagnostic output was not a broad rewrite recommendation.
It was a boundary read.
The failure lived in a very specific place:
- OpenAPI schema truth
- generator model metadata
- Kotlin enum literal rendering
- generated source compilation
That chain left very little room for a broad architectural patch.
The right repair was not to alter OpenAPI 3.1 interpretation globally.
It was not to change Kotlin model typing.
It was not to rewrite enum handling.
It was to correct the Kotlin generator’s literal emission for boolean enum values so kotlin.Boolean values are emitted as Kotlin boolean literals, matching the existing primitive handling pattern already present for types such as Int and Long.
Failure shape
The failure shape was a type/literal mismatch.
The source schema expressed a boolean value.
The generated Kotlin type expected a boolean.
But the emitted enum value was rendered as a string.
That creates uncompilable Kotlin because the generated code tries to assign a string literal where the Kotlin type is kotlin.Boolean.
In plain English:
the generator knew the target type was boolean, but the literal printer still treated the value like text
That is not a schema problem.
That is not a Kotlin language problem.
That is not a user configuration problem.
That is a generator boundary problem.
A code generator has to preserve semantic type truth when it crosses from schema representation into target-language source text.
Boundary
The boundary here is:
schema-level boolean truth versus target-language literal rendering
OpenAPI Generator does not merely copy schema values into files. It translates schema information into compilable source code for a specific language.
That translation layer is where the bug lived.
The boolean value true is valid schema data.
The Kotlin type kotlin.Boolean is valid generated typing.
The invalid part was the stringified source literal "true".
So the repair stayed inside the Kotlin generator’s enum-value rendering path.
It did not reinterpret the OpenAPI schema.
It did not alter the broader model-generation pipeline.
It did not introduce a Kotlin-only workaround outside the existing generator structure.
It added the missing primitive literal handling where the generator already converts values into Kotlin enum output.
That is the Scarab boundary:
preserve the schema truth, but repair only the translation surface that broke it
What changed
The PR updates the Kotlin generator so boolean enum values are emitted as boolean literals when the target enum value type is kotlin.Boolean.
That means the generated Kotlin output uses:
true
instead of:
"true"
The change follows the existing primitive-handling pattern already used for numeric values such as Int and Long.
That is important because this repair does not invent a new enum system. It extends the existing literal-emission logic to cover the missing boolean case.
The patch adds two focused regression checks:
- a direct toEnumValue assertion for boolean literal rendering
- a generated-output regression fixture using an OpenAPI 3.1 const: true boolean schema
Together, those tests cover both the small rendering function and the actual generated Kotlin output path.
Why this was not a broad generator rewrite
The tempting mistake in generator bugs is to make the patch bigger than the failure.
Because OpenAPI Generator supports many languages, schema forms, and target-specific behaviors, a small bug can appear to invite a large abstraction change.
That would have been the wrong move here.
The reported failure did not prove that enum handling was globally broken.
It did not prove that OpenAPI 3.1 const support needed a broad redesign.
It did not prove that Kotlin model typing was wrong.
It proved one narrower thing:
a boolean value that should be emitted as a Kotlin boolean literal was being emitted as a string literal
So the patch stayed at that level.
That is the discipline of this kind of repair.
When the failure is a missing primitive case, the patch should add the missing primitive case.
Why the diagnostic result mattered
This case is useful because the patch looks small, but the boundary is still important.
In a generator project, output correctness depends on tiny translation decisions.
A single quote mark can be the difference between valid source code and a broken generated project.
SDS helped keep the repair framed around the actual ownership surface:
- OpenAPI Generator owns the generated Kotlin source text.
- The Kotlin generator owns how schema-derived enum values are rendered into Kotlin literals.
- The boolean schema value should remain boolean when emitted into a kotlin.Boolean enum context.
That framing kept the repair from drifting into unrelated schema interpretation, target typing, or broad generator behavior.
The result was a small patch with direct evidence.
Validation
The patch was validated with the targeted Kotlin regression test and full project checks.
Validation passed for:
- targeted Kotlin regression test
- ./mvnw clean package
- ./bin/generate-samples.sh ./bin/configs/*.yaml
- ./bin/utils/export_docs_generators.sh
- git diff --check
At the time of this report, the PR is open and mergeable.
The Cubic AI reviewer passed.
CircleCI node0 passed, while node1, node2, and node3 were still pending at the time of drafting.
For the full validation record and public status, see the Field Lab case record:
Field test result
This was a bounded Kotlin generator literal-emission repair candidate for OpenAPI Generator.
The issue reduced to:
- an OpenAPI 3.1 boolean const: true schema reached the Kotlin generator
- the generated enum value type was kotlin.Boolean
- the emitted value was incorrectly stringified as "true"
- the generated Kotlin was uncompilable
- OpenAPI Generator already had primitive literal handling for values such as Int and Long
- the Kotlin generator was missing the matching boolean literal path
- the PR adds that narrow boolean handling and focused regression coverage
That is the repair lane.
This patch does not claim to redesign OpenAPI 3.1 support.
It does not claim to rewrite enum generation.
It does not claim to alter Kotlin model typing.
It fixes the boundary where boolean schema truth becomes Kotlin source text.
Public claim
The correct claim for this field test is:
Scarab/SDS helped drive a bounded repair candidate for OpenAPITools/openapi-generator#23550, where the Kotlin generator emitted OpenAPI 3.1 boolean const: true enum values as "true" strings even though the generated enum value type was kotlin.Boolean. The upstream PR adds narrow Kotlin generator handling so boolean enum values are emitted as Kotlin boolean literals, matching the existing primitive handling pattern for types such as Int and Long. The repair includes a focused toEnumValue assertion and a generated-output regression fixture. Validation passed through the targeted Kotlin regression test, full Maven package build, sample generation, generator docs export, and whitespace checks. This does not claim to redesign OpenAPI 3.1 support or enum generation broadly; it fixes the boolean literal-emission boundary that produced uncompilable Kotlin.
Disclosure: This field report was prepared with AI-assisted editing from my own field-test notes, public issue and PR records, validation summary, and repair record. The technical claims and final wording were reviewed before publication.
Top comments (0)