[BUG][core] OAS 3.1 property with a bare type: "null" resolves to a never-generated Null / ModelNull model (regression in 7.17.0)

[renechoi]

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 normalizeProperties would 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: correct

7.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

1. Generate with 7.16.0 → models/parent-bare-null.ts declares 'dyn'?: any | null;, 'dynList'?: Array<any | null>;, 'dynRef'?: any | null; and imports only Child.
2. Generate the same spec with 7.17.0 or later → Null, Array<Null>, Null plus an import of ./null, while models/ contains only child.ts, index.ts and parent-bare-null.ts.
3. Run tsc --strict on the output → exits 0. Assign a number, a string or an object to any of the three → still exits 0.
4. Repeat with -g java --library webclient → private ModelNull dyn, private List<ModelNull> dynList, private ModelNull dynRef, with no ModelNull.java; model/ holds only Child.java and ParentBareNull.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)) checks ModelUtils.isNullTypeSchema(openAPI, additionalProperties) before recursing. That interception is [BUG][core] Normalize OAS 3.1 type: null map value (additionalProperties) under NORMALIZE_31SPEC #23967, and it is why rows 1–2 above are fixed.
• properties (normalizeProperties) calls normalizeSchema(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: null map 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 lifting null out 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: $ref bug. Unrelated code path: whole-tree diff -r between 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.

[rony-remedio]

Thanks for writing this up properly — the bisect and the OpenAPINormalizer.java:940 root 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:

	7.16.0	7.24.0
?: any | null;	4	0
?: Null;	0	4
models/null.ts generated	no	no

A 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 for type: "null". 7.24.0 produces Null, which is neither. So the regression costs the | null in addition to substituting a fictional model, and that part is invisible even in Java, where the missing ModelNull.java at 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' with null.ts never generated — but nothing referenced Null, so the @ts-ignore above 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 silent any. 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 ./null are 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]

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 a null type into a schema: bare, single-entry array, $ref to a null-typed component, array items, map values, anyOf/oneOf members, null-first type arrays, null enum) and ran it through 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, plus java --library webclient on 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 declared type: ["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 referenced Null" 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

dyn:
  type: "null"
  enum: [null]

generates import type { Null } from './null' while the property types as S12NullEnumDynEnum | null. The import is emitted and never used, on 7.17.0 through 7.24.0.

ModelUtils.isNullTypeSchema returns true for a single-entry enum of null (the branch above the getTypes() one), so this schema takes the same untouched path as a bare type: "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

	7.16.0	7.17.0 → 7.24.0
items: {type: "null"}, typescript-axios	Array<any | null>	Array<Null>
items: {type: "null"}, java webclient	List<Object>	List<ModelNull>, no ModelNull.java

A property that $refs a component schema which is itself a bare type: "null" degrades the same way, and resolves to Null rather than to the alias's own name. Neither null.ts nor 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:

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
map value	$ref → bare-null alias	any	Null	any | null — fixed
parent's own type array	$ref → type: [null, object] alias	Null	Null	NullObjectAlias | null — fixed
property	type: "null" / ["null"] / + 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 import	unused import

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:

1. This is not a "revert the 7.17.0 early return" situation. The third row was broken before 7.17.0 and stayed broken until 7.24.0. Dropping the early return would put it back.
2. The gap is a child interception, not a parent one. In normalizeSchema, the properties branch and the array branch hand each child straight back to normalizeSchema, where the isNullTypeSchema early return returns it untouched. The map branch does not: [BUG][core] Normalize OAS 3.1 type: null map value (additionalProperties) under NORMALIZE_31SPEC #23967 added an explicit isNullTypeSchema(additionalProperties) check in the parent's branch, before the child is recursed into. normalizeNullTypeArray31 in 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 -r between 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 normalizeProperties would be enough, and array items make that too narrow.

[rony-remedio]

Checked the shape you asked about. It is not a $ref to a null-typed alias — it is the nullable map from #24519, and the three files are exactly the three that PR changes.

# 5 properties across 2 of the 3 schemas
someCounts:
  type: ["null", "object"]
  additionalProperties: {type: integer, format: int32}

# 1 property in the third
devices:
  type: ["null", "object"]
  additionalProperties: {$ref: "#/components/schemas/<ValueSchema>"}

So my "nothing referenced Null" holds on this spec — Null appears 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:

shape	7.16.0	7.24.0	unused Null import
type: ["null", object] + additionalProperties	correct type, no | null	correct type, no | null	yes, both versions
type: "null" + enum: [null]	no import	typed from inline enum	yes, 7.17.0+

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:

• 2 files use Null — 4 properties, the bare-null regression, this issue. Unchanged by [BUG] Normalize OAS 3.1 nullable map type array under NORMALIZE_31SPEC #24519.
• 3 files do not — the nullable maps. [BUG] Normalize OAS 3.1 nullable map type array under NORMALIZE_31SPEC #24519 drops the import and adds the missing | 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.ts never generated, but nothing referenced Null" 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 missed Array<Null> or a map value. On this spec it happens not to matter, since those three files mention Null exactly 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]

That shape closes it, and it turns my 7.16.0 result around. I added it to the probe as two schemas — someCounts with an int32 value and devices with a $ref value — and regenerated typescript-axios on 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.

property	generated	./null imported	Null referenced
type: ["null", object] + additionalProperties: {type: integer}	'someCounts'?: { [key: string]: number; };	yes	no
type: ["null", object] + additionalProperties: {$ref: Child}	'devices'?: { [key: string]: Child; };, no Child import	yes	no

Both 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/ and docs/ 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: bare type: "null", type: ["null"], a $ref to 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 --strict over the probe models: 1 error before (TS2304: Cannot find name 'Child', the $ref map), 0 after. The six remaining dangling imports stay invisible to tsc either way, since the @ts-ignore suppresses the unresolved module and Null then resolves to any where 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 testNullableMapWithPrimitiveValueKeepsNullability asserts the generated model has no ./null import, 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, but Array<Null> and { [key: string]: Null; } both occur on the probe, so it is worth widening if you re-run it on anything else.