feat: open discriminated unions

biome.jsonc

@@ -51,7 +51,7 @@
       "test": "recommended"
     },
     "rules": {
-      "recommended": true,
+      "preset": "recommended",
       "complexity": {
         "noForEach": "error"
       },

packages/documentation/src/lib/playground.tsx

@@ -60,6 +60,7 @@ const defaultConfig = {
   tsIsEsmProject: false,
   tsServerImplementationMethod: "type",
   enumExtensibility: "",
+  unionExtensibility: "",
 } satisfies Config
 
 const EditorFileSelectorWrapper: React.FC<PropsWithChildren> = ({children}) => {

packages/documentation/src/lib/playground/config-form.tsx

@@ -19,6 +19,7 @@ const schema = configSchema.pick({
   tsServerImplementationMethod: true,
   tsIsEsmProject: true,
   enumExtensibility: true,
+  unionExtensibility: true,
 })
 
 type Inputs = z.infer<typeof schema>
@@ -40,6 +41,7 @@ export const ConfigForm: React.FC<{
       tsServerImplementationMethod: config.tsServerImplementationMethod,
       tsIsEsmProject: config.tsIsEsmProject,
       enumExtensibility: config.enumExtensibility,
+      unionExtensibility: config.unionExtensibility,
     } as const,
   })
 
@@ -108,6 +110,12 @@ export const ConfigForm: React.FC<{
         label={"--enum-extensibility"}
         values={schema.shape.enumExtensibility.options}
       />
+      <ControlledSelect
+        name={"unionExtensibility"}
+        control={control}
+        label={"--union-extensibility"}
+        values={schema.shape.unionExtensibility.options}
+      />
     </div>
   )
 }

packages/openapi-code-generator/src/cli.ts

@@ -148,6 +148,16 @@ const program = new Command()
       .default("")
       .makeOptionMandatory(),
   )
+  .addOption(
+    new Option(
+      "--union-extensibility <value>",
+      "Whether discriminated unions should be open to unknown values, or closed. Defaults to open for client templates, and closed for server templates.",
+    )
+      .env("OPENAPI_UNION_EXTENSIBILITY")
+      .choices(["open", "closed"] as const)
+      .default("")
+      .makeOptionMandatory(),
+  )
   .addOption(
     new Option(
       "--grouping-strategy <value>",

packages/openapi-code-generator/src/config.ts

@@ -25,6 +25,7 @@ export type Config = {
   groupingStrategy: "none" | "first-slug" | "first-tag"
   filenameConvention: IdentifierConvention
   enumExtensibility: "" | "open" | "closed"
+  unionExtensibility: "" | "open" | "closed"
   tsAllowAny: boolean
   tsServerImplementationMethod: ServerImplementationMethod
   tsIsEsmProject: boolean
@@ -63,6 +64,7 @@ export const configSchema = z.object({
     "snake-case",
   ]),
   enumExtensibility: z.enum(["", "open", "closed"]),
+  unionExtensibility: z.enum(["", "open", "closed"]),
   tsAllowAny: z.boolean(),
   tsServerImplementationMethod: tsServerImplementationSchema,
   tsIsEsmProject: z.boolean(),

packages/openapi-code-generator/src/core/input.ts

@@ -35,6 +35,7 @@ export type OperationGroupStrategy = "none" | "first-tag" | "first-slug"
 export type InputConfig = {
   extractInlineSchemas: boolean
   enumExtensibility: "open" | "closed"
+  unionExtensibility: "open" | "closed"
 }
 
 export interface ISchemaProvider {

packages/openapi-code-generator/src/core/normalization/parameter-normalizer.spec.ts

@@ -26,6 +26,7 @@ describe("ParameterNormalizer", () => {
       {
         extractInlineSchemas: true,
         enumExtensibility: "open",
+        unionExtensibility: "open",
       },
       fakeSchemaProvider,
     )

packages/openapi-code-generator/src/core/normalization/schema-normalizer.spec.ts

@@ -14,6 +14,7 @@ describe("core/input - SchemaNormalizer", () => {
       {
         extractInlineSchemas: true,
         enumExtensibility: "open",
+        unionExtensibility: "open",
       },
       schemaProvider,
     )
@@ -455,6 +456,7 @@ describe("core/input - SchemaNormalizer", () => {
         ir.union({
           nullable: true,
           schemas: [ir.number(), {$ref: "#/components/schemas/RefModel"}],
+          "x-union-extensibility": "open",
         }),
       )
     })
@@ -473,6 +475,7 @@ describe("core/input - SchemaNormalizer", () => {
         ir.union({
           nullable: true,
           schemas: [ir.number(), {$ref: "#/components/schemas/Another"}],
+          "x-union-extensibility": "open",
         }),
       )
     })
@@ -557,6 +560,7 @@ describe("core/input - SchemaNormalizer", () => {
                   },
                 }),
               ],
+              "x-union-extensibility": "open",
             }),
           ],
         }),
@@ -598,6 +602,7 @@ describe("core/input - SchemaNormalizer", () => {
                   },
                 }),
               ],
+              "x-union-extensibility": "open",
             }),
           ],
         }),
@@ -635,6 +640,7 @@ describe("core/input - SchemaNormalizer", () => {
                 ir.object({properties: {foo: ir.string()}, required: ["foo"]}),
                 ir.object({properties: {bar: ir.string()}, required: ["bar"]}),
               ],
+              "x-union-extensibility": "open",
             }),
           ],
         }),
@@ -688,6 +694,7 @@ describe("core/input - SchemaNormalizer", () => {
               ir.ref("/components/schemas/Foo"),
               ir.ref("/components/schemas/Bar"),
             ],
+            "x-union-extensibility": "open",
           }),
         )
       })
@@ -736,6 +743,7 @@ describe("core/input - SchemaNormalizer", () => {
               ir.ref("/components/schemas/Foo", "/absolute/path.yaml"),
               ir.ref("/components/schemas/Bar", "/absolute/path.yaml"),
             ],
+            "x-union-extensibility": "open",
           }),
         )
       })
@@ -823,6 +831,7 @@ describe("core/input - SchemaNormalizer", () => {
               ir.ref("/components/schemas/Foo"),
               ir.ref("/components/schemas/Bar"),
             ],
+            "x-union-extensibility": "open",
           }),
         )
       })
@@ -940,6 +949,7 @@ describe("core/input - SchemaNormalizer", () => {
             ir.object({properties: {type: ir.string()}}),
             ir.ref("/components/schemas/Bar"),
           ],
+          "x-union-extensibility": "open",
         }),
       )
     })
@@ -977,6 +987,7 @@ describe("core/input - SchemaNormalizer", () => {
             ir.ref("/components/schemas/Foo"),
             ir.ref("/components/schemas/Bar"),
           ],
+          "x-union-extensibility": "open",
         }),
       )
     })
@@ -1008,6 +1019,7 @@ describe("core/input - SchemaNormalizer", () => {
             ir.ref("/components/schemas/Foo"),
             ir.ref("/components/schemas/Bar"),
           ],
+          "x-union-extensibility": "open",
         }),
       )
     })
@@ -1039,6 +1051,7 @@ describe("core/input - SchemaNormalizer", () => {
             ir.ref("/components/schemas/Foo"),
             ir.ref("/components/schemas/Bar"),
           ],
+          "x-union-extensibility": "open",
         }),
       )
     })
@@ -1198,6 +1211,7 @@ describe("core/input - SchemaNormalizer", () => {
       expect(actual).toStrictEqual(
         ir.union({
           schemas: [ir.string({nullable: true}), ir.number({nullable: true})],
+          "x-union-extensibility": "open",
         }),
       )
     })

packages/openapi-code-generator/src/core/normalization/schema-normalizer.ts

@@ -47,6 +47,16 @@ export class SchemaNormalizer {
     )
   }
 
+  private getUnionExtensibility(
+    schemaObject: {"x-union-extensibility"?: "open" | "closed" | undefined},
+    enumValues: unknown[],
+  ) {
+    return (
+      schemaObject["x-union-extensibility"] ??
+      (enumValues.length === 1 ? "closed" : this.config.unionExtensibility)
+    )
+  }
+
   private hasPropertiesOrComposition(schema: SchemaObject): boolean {
     return Boolean(
       schema.allOf?.length ||
@@ -209,6 +219,7 @@ export class SchemaNormalizer {
           {...base, nullable},
           [...oneOf, ...anyOf],
           schemaObject.discriminator,
+          this.getUnionExtensibility(schemaObject, [...oneOf, ...anyOf]),
         )
 
         if (maybeIntersection && maybeUnion) {
@@ -657,6 +668,7 @@ export class SchemaNormalizer {
     base: IRModelBase,
     schemas: MaybeIRModel[],
     discriminator: Discriminator | undefined,
+    extensibility: "open" | "closed" | undefined,
   ): MaybeIRModel | IRModelUnion | undefined {
     // (A|B)|(C|D) is the same as (A|B|C|D)
     // todo: merge repeated in-line schemas
@@ -668,7 +680,12 @@ export class SchemaNormalizer {
     if (isNonEmptyArray(schemas)) {
       if (schemas.length === 1) {
         if (base.nullable) {
-          return {...base, type: "union", schemas}
+          return {
+            ...base,
+            type: "union",
+            schemas,
+            "x-union-extensibility": extensibility,
+          }
         }
         return schemas[0]
       }
@@ -678,6 +695,7 @@ export class SchemaNormalizer {
         type: "union",
         discriminator: this.normalizeDiscriminator(discriminator, schemas),
         schemas,
+        "x-union-extensibility": extensibility,
       }
     }
 

packages/openapi-code-generator/src/core/openapi-types-normalized.ts

@@ -90,6 +90,7 @@ export interface IRModelUnion extends IRModelBase {
         //todo: support defaultMapping
       }
     | undefined
+  "x-union-extensibility"?: "open" | "closed" | undefined
 }
 
 export interface IRModelObject extends IRModelBase {

packages/openapi-code-generator/src/core/openapi-types.ts

@@ -274,6 +274,7 @@ export interface SchemaBase {
    */
   "x-internal-preprocess"?: xInternalPreproccess | Reference | undefined
   "x-enum-extensibility"?: "open" | "closed" | undefined
+  "x-union-extensibility"?: "open" | "closed" | undefined
 }
 
 export interface SchemaNumber extends SchemaBase {

packages/openapi-code-generator/src/generate.ts

@@ -30,6 +30,25 @@ function enumExtensibility(
   throw new Error(`Unsupported generator type '${generator.type}'`)
 }
 
+function unionExtensibility(
+  config: Config,
+  generator: OpenapiGenerator,
+): "open" | "closed" {
+  if (config.unionExtensibility) {
+    return config.unionExtensibility
+  }
+
+  if (generator.type === "client") {
+    return "open"
+  }
+
+  if (generator.type === "server") {
+    return "closed"
+  }
+
+  throw new Error(`Unsupported generator type '${generator.type}'`)
+}
+
 export async function generate(
   config: Config,
   fsAdaptor: IFsAdaptor,
@@ -63,6 +82,7 @@ export async function generate(
     {
       extractInlineSchemas: config.extractInlineSchemas,
       enumExtensibility: enumExtensibility(config, generator),
+      unionExtensibility: unionExtensibility(config, generator),
     },
     generator.syntheticNameGenerator,
   )

packages/openapi-code-generator/src/test/input.test-utils.ts

@@ -54,6 +54,7 @@ export async function unitTestInput(
   const config = {
     extractInlineSchemas: true,
     enumExtensibility: "closed",
+    unionExtensibility: "closed",
   } satisfies InputConfig
 
   return {
@@ -87,5 +88,6 @@ export async function createTestInputFromYamlString(
   return new Input(loader, {
     extractInlineSchemas: true,
     enumExtensibility: "closed",
+    unionExtensibility: "closed",
   })
 }

packages/openapi-code-generator/src/test/ir-model.fixtures.test-utils.ts

@@ -116,6 +116,7 @@ const extension = {
     nullable: false,
     default: undefined,
     discriminator: undefined,
+    "x-union-extensibility": undefined,
     "x-internal-preprocess": undefined,
   } satisfies IRModelUnion,
   null: {