Repository navigation
Description
Bug Report Checklist
- Have you provided a full/minimal spec to reproduce the issue?
- Have you validated the input using an OpenAPI validator?
- Have you tested with the latest master to confirm the issue still exists?
- Have you searched for related issues/PRs?
- What's the actual output vs expected output?
- [Optional] Sponsorship to speed up the bug fix or feature request
Description
A schema of a bare type: "null" is resolved to a model named Null / ModelNull that is never generated. This regressed at 7.17.0 and affects every generator, because the cause is in OpenAPINormalizer, not in a language template.
Updated after probing. The first revision of this report described this as a property-level defect and suggested that handling it in
normalizePropertieswould be enough. That was too narrow. Probing 18 null-bearing shapes across 7.16.0–7.24.0 shows three container sites are affected, and one neighbouring case regressed and was fixed again in a way that rules out the obvious revert. Everything below is the widened version.
Affected sites, all in one model:
// generated by 7.24.0 — none of these three names exist; models/ holds only child.ts and parent-bare-null.ts
'dyn'?: Null; // property: type: "null"
'dynList'?: Array<Null>; // array items: items: {type: "null"}
'dynRef'?: Null; // $ref to a component schema that is itself type: "null"
'child'?: Child; // control: correct7.16.0 produced any | null, Array<any | null> and any | null for the same three. So the regression costs the | null as well as substituting a fictional model.
The failure mode differs by generator, and the quieter one is worse:
| 7.16.0 | 7.17.0 → 7.24.0 | |
|---|---|---|
typescript-axios |
any | null, no import |
Null + import type { Null } from './null', and null.ts is never written |
java (--library webclient) |
JsonNullable<Object> / List<Object> |
ModelNull / List<ModelNull>, and ModelNull.java is never written |
Java fails to compile, which is at least visible. TypeScript does not, because the generated // May contain unused imports in some cases / // @ts-ignore pair sits directly above the dangling import and suppresses it. The properties then silently degrade to any while reading as real named types:
const a: ParentBareNull = { dyn: 12345 };
const b: ParentBareNull = { dyn: 'a string instead' };
const c: ParentBareNull = { dynList: [1, 'two', { three: true }], dynRef: { anything: 'goes' } };
const d = (v: ParentBareNull) => v.dynList![0].whateverMethod().deeply.nested;tsc --strict exits 0 on all of them.
The shape is not hand-written exotica. @rony-remedio, who found this, reports that Swashbuckle emits a bare type: "null" for an untyped / dynamic member, and measured it on a production 3.1.1 spec (490 component schemas, 486 generated models): it occurs on 4 properties there, all silently degraded to any, confirming the 7.16.0 → 7.24.0 swap four-for-four. Those production figures are theirs; everything else here is from the minimal spec below.
Where this sits relative to what is already fixed
Measured on an 18-shape probe spec with typescript-axios, on 7.16.0, 7.17.0, 7.18.0, 7.19.0, 7.20.0, 7.21.0, 7.22.0, 7.23.0 and 7.24.0:
| container branch | child shape | 7.16.0 | 7.17.0–7.23.0 | 7.24.0 |
|---|---|---|---|---|
| map value | type: "null" |
any | null |
Null |
any | null — fixed by #23967 |
| map value | $ref → bare-null alias |
any |
Null |
any | null — fixed by #23967 |
| parent's own type array | $ref → type: [null, object] alias |
Null |
Null |
NullObjectAlias | null — fixed by #24140 |
| property | type: "null" / ["null"] / with description |
any | null |
Null |
Null |
| property | $ref → bare-null alias |
any | null |
Null |
Null |
| array items | type: "null" |
Array<any | null> |
Array<Null> |
Array<Null> |
| property | type: "null" + enum: [null] |
no import | unused Null import |
unused Null import |
Two things follow.
This is not a "revert the 7.17.0 early return" situation. Row 3 was broken before 7.17.0 and stayed broken until 7.24.0; dropping the early return would put it back. (Attribution of rows 1–3 is by release boundary plus diff inspection; I did not build the intermediate commits.)
The last row is a separate, smaller defect: type: "null" with enum: [null] emits the Null import while typing the property from the inline-enum path, so the import is emitted by something other than what picks the property type.
openapi-generator version
Regression. Bisected on typescript-axios: correct on 7.12.0–7.16.0, broken from 7.17.0 through 7.24.0. A 7.25.0-SNAPSHOT build of the current tree produces output byte-identical to 7.24.0's for this spec (diff -r clean apart from the version stamp), so master is still affected. java --library webclient bisects to the same 7.17.0 boundary.
OpenAPI declaration file content or url
openapi: 3.1.0
info:
title: Repro bare null property
version: 1.0.0
components:
schemas:
Child:
type: object
properties:
name:
type: string
# a component schema that is itself a bare null type
NullAlias:
type: "null"
ParentBareNull:
type: object
properties:
# 1. property: Swashbuckle emits this shape for an untyped / `dynamic` member
dyn:
type: "null"
# 2. array items
dynList:
type: array
items:
type: "null"
# 3. property that $refs a null-typed component schema
dynRef:
$ref: "#/components/schemas/NullAlias"
# control: an ordinary $ref property, which stays correct
child:
$ref: "#/components/schemas/Child"Generation Details
openapi-generator-cli generate -i spec.yaml -g typescript-axios -o out \
--additional-properties=withSeparateModelsAndApi=true,modelPackage=models,apiPackage=api
Output is byte-identical with and without --openapi-normalizer NORMALIZE_31SPEC=true (diff -r clean), so the rule is not involved either way.
Steps to reproduce
- Generate with 7.16.0 →
models/parent-bare-null.tsdeclares'dyn'?: any | null;,'dynList'?: Array<any | null>;,'dynRef'?: any | null;and imports onlyChild. - Generate the same spec with 7.17.0 or later →
Null,Array<Null>,Nullplus an import of./null, whilemodels/contains onlychild.ts,index.tsandparent-bare-null.ts. - Run
tsc --stricton the output → exits 0. Assign a number, a string or an object to any of the three → still exits 0. - Repeat with
-g java --library webclient→private ModelNull dyn,private List<ModelNull> dynList,private ModelNull dynRef, with noModelNull.java;model/holds onlyChild.javaandParentBareNull.java.
Suggested cause
OpenAPINormalizer#normalizeSchema gained this guard in 7.17.0 (absent at v7.16.0, present at v7.17.0); it is currently at OpenAPINormalizer.java:940:
if (ModelUtils.isNullTypeSchema(openAPI, schema)) {
return schema;
}ModelUtils.isNullTypeSchema dereferences $refs and returns true for a single-entry type array of "null" (and for a single-entry enum of null), so such a schema is returned untouched no matter which normalizer rules are enabled, and DefaultCodegen#getPrimitiveType then resolves it to the literal type name "null", which becomes a model reference.
Because the early return is inside normalizeSchema itself, a null-type schema can only be rewritten by its parent — and the parent branches do not treat their children alike:
- map (
else if (schema.getAdditionalProperties() instanceof Schema)) checksModelUtils.isNullTypeSchema(openAPI, additionalProperties)before recursing. That interception is [BUG][core] Normalize OAS 3.1type: nullmap value (additionalProperties) under NORMALIZE_31SPEC #23967, and it is why rows 1–2 above are fixed. - properties (
normalizeProperties) callsnormalizeSchema(property, new HashSet<>())on each child with no such check. - array calls
normalizeSchema(result.getItems(), visitedSchemas)with no such check.
normalizeNullTypeArray31, present in both the properties and map branches, handles the parent's own type array; that is a different axis (it is what #24140 added and what fixed row 3), which is why the parent-level fix left rows 4–6 broken.
So the missing piece is a child-level interception in the properties and array branches, mirroring what the map branch already does.
Related issues/PRs
- [BUG][MULTIPLE][OAS 3.1] Nullable map with additionalProperties type null breaks codegen (Null/ModelNull) with NORMALIZE_31SPEC (7.17+) #23945 / [BUG][core] Normalize OAS 3.1
type: nullmap value (additionalProperties) under NORMALIZE_31SPEC #23967 — the map-value form of this, fixed by intercepting in the map branch. - fix: normalize OAS 3.1 schemas with type:[object,"null"] to set nullable:true correctly #24140 — the
type: [object, "null"]parent form, fixed by liftingnullout of the parent's type array. - [BUG] [webclient] Missing default null value for Object #23908 — the Java-side report of this property form.
- fix(java): map OpenAPI 3.1 null type to Object to prevent ModelNull generation #23961 — a proposed fix in
AbstractJavaCodegen; that would leave the other generators broken, since the cause is in the normalizer. - [BUG][typescript-axios] Missing import for a $ref under additionalProperties on a 3.1 nullable property #24517 / [BUG] Normalize OAS 3.1 nullable map type array under NORMALIZE_31SPEC #24519 — a separate
type: [null, object]+additionalProperties: $refbug. Unrelated code path: whole-treediff -rbetween 7.24.0 output and that branch is empty apart from.openapi-generator/VERSION, on all 18 probe shapes.
Found by @rony-remedio while reviewing #24519; filed separately so it doesn't widen that PR's scope.
Activity
rony-remedio commentedon Jul 29, 2026
Thanks for writing this up properly — the bisect and the
OpenAPINormalizer.java:940root cause are the whole substance here.Confirming your 7.16.0 → 7.17.0 boundary on the production spec rather than a minimal one, since a real-world regression is a different argument from a hand-written repro. Same spec, same options, no normalizer rules enabled, only the generator version differs:
?: any | null;?: Null;models/null.tsgeneratedA clean four-for-four swap, matching your table exactly. The four affected properties live in two model files.
Two details that may be worth having in the report:
The nullability is lost as well as the type. 7.16.0 produced
any | null— honest about being unconstrained, and still nullable, which is correct fortype: "null". 7.24.0 producesNull, which is neither. So the regression costs the| nullin addition to substituting a fictional model, and that part is invisible even in Java, where the missingModelNull.javaat least stops the build.The dangling import predates the regression, harmlessly. In 7.16.0 three model files already carried
import type { Null } from './null'withnull.tsnever generated — but nothing referencedNull, so the@ts-ignoreabove it made them genuinely unused imports, exactly as the boilerplate comment claims. 7.17.0 did not introduce the bogus import; it started using it as a property type, which is what turned inert boilerplate into a silentany. That may narrow where to look, since whatever emits the import was already doing so before the regression.Relationship to #24519. On this spec the two are cleanly separable: after building that branch,
?: Null;is still 4, and the two files that still import./nullare precisely the two holding these four properties. So #24519 neither fixes nor worsens this, which matches what you found — the map-branch fix and this property-branch gap are independent.Happy to re-measure on any branch that attempts this one; the spec and the tooling are set up.
renechoi commentedon Jul 29, 2026
Both of your points measured. One of them came out the other way, and chasing it turned up two more sites.
I built an 18-shape probe spec (
S1..S18, every way I could construct anulltype into a schema: bare, single-entry array,$refto a null-typed component, array items, map values,anyOf/oneOfmembers, null-first type arrays, null enum) and ran it throughtypescript-axioson 7.16.0, 7.17.0, 7.18.0, 7.19.0, 7.20.0, 7.21.0, 7.22.0, 7.23.0 and 7.24.0, plusjava --library webclienton the endpoints.The unused import at 7.16.0 does not reproduce here
At 7.16.0 exactly one file in the whole output tree imports
./null, and it uses the import. Zero unused ones, across all 18 shapes.That one file is a property that
$refs a component schema declaredtype: ["null", "object"]— which, as it happens, is broken at 7.16.0 and correct at 7.24.0 (fourth row of the table below). If the three files on your spec are that shape, the import would match but the "nothing referencedNull" part would not. Could you check what those three property schemas look like? It is the one part of your report I can't put a shape to.The separation you describe is real — the witness is at 7.24.0, not 7.16.0
generates
import type { Null } from './null'while the property types asS12NullEnumDynEnum | null. The import is emitted and never used, on 7.17.0 through 7.24.0.ModelUtils.isNullTypeSchemareturns true for a single-entry enum ofnull(the branch above thegetTypes()one), so this schema takes the same untouched path as a baretype: "null", but the datatype then comes from the inline-enum handling while the import still comes from the type name. So your read is right: whatever emits the import is not what picks the property type.The regression is wider than properties — array items are hit identically
items: {type: "null"}, typescript-axiosArray<any | null>Array<Null>items: {type: "null"}, java webclientList<Object>List<ModelNull>, noModelNull.javaA property that
$refs a component schema which is itself a baretype: "null"degrades the same way, and resolves toNullrather than to the alias's own name. Neithernull.tsnor the alias model is written in any version I tested.Two members of this family are already fixed in-tree
Full matrix, all measured on the probe spec:
type: "null"any | nullNullany | null— fixed$ref→ bare-null aliasanyNullany | null— fixed$ref→type: [null, object]aliasNullNullNullObjectAlias | null— fixedtype: "null"/["null"]/ + descriptionany | nullNullNull$ref→ bare-null aliasany | nullNullNulltype: "null"Array<any | null>Array<Null>Array<Null>type: "null"+enum: [null]The first two rows are #23967. The third is #24140 — I attribute it by the release boundary (broken through 7.23.0, correct at 7.24.0) and by its diff, which is the only change in that range touching this path; I did not build the intermediate commits to confirm.
Two consequences for whoever fixes this:
normalizeSchema, the properties branch and the array branch hand each child straight back tonormalizeSchema, where theisNullTypeSchemaearly return returns it untouched. The map branch does not: [BUG][core] Normalize OAS 3.1type: nullmap value (additionalProperties) under NORMALIZE_31SPEC #23967 added an explicitisNullTypeSchema(additionalProperties)check in the parent's branch, before the child is recursed into.normalizeNullTypeArray31in the properties and map branches handles the parent's own type array, which is a different axis and is why the parent-level fix in fix: normalize OAS 3.1 schemas with type:[object,"null"] to set nullable:true correctly #24140 left these three rows broken.On #24519 separability
Whole-tree
diff -rbetween 7.24.0 output and that branch is empty apart from.openapi-generator/VERSION— on 18 shapes rather than one, including all six broken rows above. Matches what you measured; that PR neither causes nor fixes any of this.I'm widening the report body: it currently describes a property-level defect and suggests that handling
normalizePropertieswould be enough, and array items make that too narrow.rony-remedio commentedon Jul 29, 2026
Checked the shape you asked about. It is not a
$refto a null-typed alias — it is the nullable map from #24519, and the three files are exactly the three that PR changes.So my "nothing referenced
Null" holds on this spec —Nullappears on the import line and nowhere else in all three files, at 7.16.0 and at 7.24.0 — but the producer is a shape your probe wouldn't have flagged as an unused-import case, because at 7.16.0 it is not otherwise broken. That makes it a third member of the family rather than a contradiction of your enum witness:Nullimporttype: ["null", object]+additionalProperties| null| nulltype: "null"+enum: [null]Two things follow.
The separation you identified is visible across a wider version range than the enum witness. This shape emits the import at 7.16.0 too, where nothing is broken and the property types correctly as a map. So whatever emits the import has been decoupled from the datatype since before 7.17.0 — the regression made that decoupling harmful for bare-null properties, it did not create it.
#24519 removes three unused imports as a side effect, which neither of us noted. Full 7.24.0 account on this spec, five importers of
./null:Null— 4 properties, the bare-null regression, this issue. Unchanged by [BUG] Normalize OAS 3.1 nullable map type array under NORMALIZE_31SPEC #24519.| null.So the two issues partition our five importers exactly, with no overlap, which is a stronger form of the separability we both measured.
On my earlier claim, one correction. I said "three files already carried the import with
null.tsnever generated, but nothing referencedNull" and offered it as evidence for the emitter/type split. The observation is right and I've re-verified it, but I reached it by grepping?: Null;— which would have missedArray<Null>or a map value. On this spec it happens not to matter, since those three files mentionNullexactly once each. It was a narrower check than the claim deserved, and your probe spec is the right instrument for that question rather than one production spec.Nothing here changes the array-items finding or your matrix — I have no shape in this spec that exercises
items: {type: "null"}, so I can't corroborate that row either way.renechoi commentedon Jul 29, 2026
That shape closes it, and it turns my 7.16.0 result around. I added it to the probe as two schemas —
someCountswith anint32value anddeviceswith a$refvalue — and regeneratedtypescript-axioson 7.16.0 through 7.24.0.You are right, and my "does not reproduce" was a hole in the spec rather than a measurement: the 18 shapes contained no nullable map, only maps whose values were null-typed, so nothing in that tree could emit the import without also using it.
./nullimportedNullreferencedtype: ["null", object]+additionalProperties: {type: integer}'someCounts'?: { [key: string]: number; };type: ["null", object]+additionalProperties: {$ref: Child}'devices'?: { [key: string]: Child; };, noChildimportBoth rows are byte-identical on all nine releases I have jars for (7.16.0, 7.17.0, 7.18.0, 7.19.0, 7.20.0, 7.21.0, 7.22.0, 7.23.0, 7.24.0). So the decoupling you describe is not just older than 7.17.0 — nothing in that whole range touches it.
That makes #24517 not a regression at all, which I had not stated anywhere. I re-ran the PR's fixture — these two shapes plus the nullable-array control — on each of those nine releases:
models/anddocs/are identical throughout. So the two issues differ in age as well as in mechanism. #24520 bisects to 7.17.0; the map gap has been there for at least the last nine releases, and they only resemble each other because they meet at the same import emitter.The partition reproduces on the probe. At 7.24.0, 8 files import
./null. The #24519 branch leaves 6, and they are exactly the bare-null family: baretype: "null",type: ["null"], a$refto a null-typed alias,items: {type: "null"}, the null enum, and the described variant. The two it removes are the two nullable maps. Same shape as your 3 + 2, no overlap.tsc --strictover the probe models: 1 error before (TS2304: Cannot find name 'Child', the$refmap), 0 after. The six remaining dangling imports stay invisible totsceither way, since the@ts-ignoresuppresses the unresolved module andNullthen resolves toanywhere it is used — which is the #24520 symptom rather than a separate one.One correction on "neither of us noted": the import removal is in the PR description's primitive-map before/after, and
testNullableMapWithPrimitiveValueKeepsNullabilityasserts the generated model has no./nullimport, so that half is guarded. What is new is the partition itself — that framing is what makes the two separable rather than merely independent-looking, and I have added the version range to the PR description.On the
?: Null;grep: it happened not to matter here, butArray<Null>and{ [key: string]: Null; }both occur on the probe, so it is worth widening if you re-run it on anything else.rony-remedio commentedon Jul 29, 2026
Corroborated on the production spec, and your correction stands.
The three nullable-map files are byte-identical between 7.16.0 and 7.24.0 — 0 differing lines each — and no map property carries
| nullin either version. So the map gap is unchanged across that range on real-world input too, and #24517 is not a regression. My report didn't claim it was, but it didn't say it wasn't either, and "these two look like the same bug" was the natural reading given they surface at the same import. Worth having stated explicitly.I also widened the grep as you suggested:
Array<Null>and{ [key: string]: Null; }are both zero on this spec, in both versions. So its five importers really are just the two shapes, and the partition is not hiding a third case behind my narrow pattern. Your probe is the better instrument for that — this spec only exercises two of the seven rows in your matrix.Fair on "neither of us noted": the import removal is in the primitive-map before/after and
testNullableMapWithPrimitiveValueKeepsNullabilityasserts it. I overstated — the partition framing was the new part, not the removal.Net from my side: #24519 is verified on 486 real models (1 → 0
tscerrors, 6 map properties gaining| null, nothing else moving), and #24520 has a real-world witness for its 7.17.0 boundary at 4 properties. Nothing outstanding that I can measure. I'll keep the build and the trees around, so ping me if a fix lands for this one and I'll re-run the same two checks against it.Thanks for the depth on both of these — going from "the import is missing" to a seven-row matrix with the age of each row is a lot more than the report deserved.
renechoi commentedon Sep 7, 2026
The obvious normalizer fix is the wrong layer, which may be why the property branch was never done alongside #24558.
Intercepting a bare
type: "null"innormalizePropertiesfixes this but breaksOas31GeneratedIrTest.generatesTypedJsonValuesForOpenApi31Schemas:cpp-boost-beast-clientmaps a null property tostd::nullptr_ton purpose. That class is 11/11 on master, 10/11 with the change.So the null type has to survive the normalizer. Generators with no
nulltypeMapping fall throughDefaultCodegen.getSingleSchemaTypetotoModelName("null"), which is whereNullcomes from.renechoi commentedon Sep 13, 2026
Re-measured on master (
7.26.0-20260911.085220-74): the TypeScript row above understates this, because the silent-anyoutcome is layout-dependent.withSeparateModelsAndApi=true— the@ts-ignoreabove the danglingimport type { Null } from './null'suppresses it andtsc --strictexits 0, as reported.Nullis simply an undeclared name andtsc --strictfails with 3 x TS2304: the property, the array items, and the$refto a bare-null alias.Map values come out correct on master. Those three sites do not.
[core] Normalize bare null properties and array items in OAS 3.1 specs
[core] Normalize bare null properties and array items in OAS 3.1 specs