hey-api · mrlubos · Nov 8, 2025 · Nov 7, 2025 · Nov 8, 2025 · Nov 8, 2025
diff --git a/.changeset/chilled-wolves-pump.md b/.changeset/chilled-wolves-pump.md
@@ -0,0 +1,5 @@
+---
+"@hey-api/openapi-ts": patch
+---
+
+parser: merge `default` keyword with `$ref` in OpenAPI 3.1
diff --git a/...ges/openapi-ts-tests/main/test/__snapshots__/3.1.x/plugins/valibot/default/valibot.gen.ts b/...ges/openapi-ts-tests/main/test/__snapshots__/3.1.x/plugins/valibot/default/valibot.gen.ts
@@ -1455,7 +1455,9 @@ export const vCallWithDefaultParametersData = v.object({
             'Error'
         ])),
         parameterModel: v.optional(v.union([
-            vModelWithString,
+            v.optional(vModelWithString, {
+                prop: 'Hello World!'
+            }),
             v.null()
         ]))
     }))
@@ -1473,7 +1475,9 @@ export const vCallWithDefaultOptionalParametersData = v.object({
             'Warning',
             'Error'
         ])),
-        parameterModel: v.optional(vModelWithString)
+        parameterModel: v.optional(vModelWithString, {
+            prop: 'Hello World!'
+        })
     }))
 });
 

diff --git a/packages/openapi-ts-tests/zod/v3/__snapshots__/3.1.x/mini/default/zod.gen.ts b/packages/openapi-ts-tests/zod/v3/__snapshots__/3.1.x/mini/default/zod.gen.ts
@@ -1486,7 +1486,9 @@ export const zCallWithDefaultParametersData = z.object({
             'Error'
         ])),
         parameterModel: z.optional(z.union([
-            zModelWithString,
+            z._default(zModelWithString, {
+                prop: 'Hello World!'
+            }),
             z.null()
         ]))
     }))
@@ -1504,7 +1506,9 @@ export const zCallWithDefaultOptionalParametersData = z.object({
             'Warning',
             'Error'
         ])),
-        parameterModel: z.optional(zModelWithString)
+        parameterModel: z._default(z.optional(zModelWithString), {
+            prop: 'Hello World!'
+        })
     }))
 });
 

diff --git a/packages/openapi-ts-tests/zod/v3/__snapshots__/3.1.x/v3/default/zod.gen.ts b/packages/openapi-ts-tests/zod/v3/__snapshots__/3.1.x/v3/default/zod.gen.ts
@@ -1484,7 +1484,9 @@ export const zCallWithDefaultParametersData = z.object({
             'Error'
         ]).optional(),
         parameterModel: z.union([
-            zModelWithString,
+            zModelWithString.default({
+                prop: 'Hello World!'
+            }),
             z.null()
         ]).optional()
     }).optional()
@@ -1502,7 +1504,9 @@ export const zCallWithDefaultOptionalParametersData = z.object({
             'Warning',
             'Error'
         ]).optional(),
-        parameterModel: zModelWithString.optional()
+        parameterModel: zModelWithString.optional().default({
+            prop: 'Hello World!'
+        })
     }).optional()
 });
 

diff --git a/packages/openapi-ts-tests/zod/v3/__snapshots__/3.1.x/v4/default/zod.gen.ts b/packages/openapi-ts-tests/zod/v3/__snapshots__/3.1.x/v4/default/zod.gen.ts
@@ -1486,7 +1486,9 @@ export const zCallWithDefaultParametersData = z.object({
             'Error'
         ])),
         parameterModel: z.optional(z.union([
-            zModelWithString,
+            zModelWithString.default({
+                prop: 'Hello World!'
+            }),
             z.null()
         ]))
     }))
@@ -1504,7 +1506,9 @@ export const zCallWithDefaultOptionalParametersData = z.object({
             'Warning',
             'Error'
         ])),
-        parameterModel: z.optional(zModelWithString)
+        parameterModel: z.optional(zModelWithString).default({
+            prop: 'Hello World!'
+        })
     }))
 });
 

diff --git a/packages/openapi-ts-tests/zod/v4/__snapshots__/3.1.x/mini/default/zod.gen.ts b/packages/openapi-ts-tests/zod/v4/__snapshots__/3.1.x/mini/default/zod.gen.ts
@@ -1486,7 +1486,9 @@ export const zCallWithDefaultParametersData = z.object({
             'Error'
         ])),
         parameterModel: z.optional(z.union([
-            zModelWithString,
+            z._default(zModelWithString, {
+                prop: 'Hello World!'
+            }),
             z.null()
         ]))
     }))
@@ -1504,7 +1506,9 @@ export const zCallWithDefaultOptionalParametersData = z.object({
             'Warning',
             'Error'
         ])),
-        parameterModel: z.optional(zModelWithString)
+        parameterModel: z._default(z.optional(zModelWithString), {
+            prop: 'Hello World!'
+        })
     }))
 });
 

diff --git a/...s/openapi-ts-tests/zod/v4/__snapshots__/3.1.x/mini/defaults-with-ref-and-anyof/zod.gen.ts b/...s/openapi-ts-tests/zod/v4/__snapshots__/3.1.x/mini/defaults-with-ref-and-anyof/zod.gen.ts
@@ -0,0 +1,40 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import * as z from 'zod/mini';
+
+export const zAudioFormat = z.enum([
+    'pcm_16bit_44.1khz',
+    'pcm_16bit_24khz'
+]);
+
+export const zLanguage = z.enum([
+    'en',
+    'es',
+    'fr'
+]);
+
+export const zNestedConfig = z.object({
+    model: z._default(z.string(), 'gpt-4'),
+    temperature: z._default(z.number(), 1)
+});
+
+export const zTestSchema = z.object({
+    primitiveDefault: z._default(z.number(), 42),
+    refWithPrimitiveDefault: z._default(zAudioFormat, 'pcm_16bit_44.1khz'),
+    refWithObjectDefault: z._default(zNestedConfig, {
+        model: 'gpt-4',
+        temperature: 1
+    }),
+    anyOfWithNullDefault: z._default(z.union([
+        z.number(),
+        z.null()
+    ]), null),
+    anyOfWithRefAndNullDefault: z._default(z.union([
+        zLanguage,
+        z.null()
+    ]), null),
+    optionalAnyOfWithDefault: z._default(z.optional(z.union([
+        z.string(),
+        z.null()
+    ])), null)
+});
diff --git a/packages/openapi-ts-tests/zod/v4/__snapshots__/3.1.x/v3/default/zod.gen.ts b/packages/openapi-ts-tests/zod/v4/__snapshots__/3.1.x/v3/default/zod.gen.ts
@@ -1484,7 +1484,9 @@ export const zCallWithDefaultParametersData = z.object({
             'Error'
         ]).optional(),
         parameterModel: z.union([
-            zModelWithString,
+            zModelWithString.default({
+                prop: 'Hello World!'
+            }),
             z.null()
         ]).optional()
     }).optional()
@@ -1502,7 +1504,9 @@ export const zCallWithDefaultOptionalParametersData = z.object({
             'Warning',
             'Error'
         ]).optional(),
-        parameterModel: zModelWithString.optional()
+        parameterModel: zModelWithString.optional().default({
+            prop: 'Hello World!'
+        })
     }).optional()
 });
 

diff --git a/...ges/openapi-ts-tests/zod/v4/__snapshots__/3.1.x/v3/defaults-with-ref-and-anyof/zod.gen.ts b/...ges/openapi-ts-tests/zod/v4/__snapshots__/3.1.x/v3/defaults-with-ref-and-anyof/zod.gen.ts
@@ -0,0 +1,40 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import { z } from 'zod/v3';
+
+export const zAudioFormat = z.enum([
+    'pcm_16bit_44.1khz',
+    'pcm_16bit_24khz'
+]);
+
+export const zLanguage = z.enum([
+    'en',
+    'es',
+    'fr'
+]);
+
+export const zNestedConfig = z.object({
+    model: z.string().default('gpt-4'),
+    temperature: z.number().default(1)
+});
+
+export const zTestSchema = z.object({
+    primitiveDefault: z.number().default(42),
+    refWithPrimitiveDefault: zAudioFormat.default('pcm_16bit_44.1khz'),
+    refWithObjectDefault: zNestedConfig.default({
+        model: 'gpt-4',
+        temperature: 1
+    }),
+    anyOfWithNullDefault: z.union([
+        z.number(),
+        z.null()
+    ]).default(null),
+    anyOfWithRefAndNullDefault: z.union([
+        zLanguage,
+        z.null()
+    ]).default(null),
+    optionalAnyOfWithDefault: z.union([
+        z.string(),
+        z.null()
+    ]).optional().default(null)
+});
diff --git a/packages/openapi-ts-tests/zod/v4/__snapshots__/3.1.x/v4/default/zod.gen.ts b/packages/openapi-ts-tests/zod/v4/__snapshots__/3.1.x/v4/default/zod.gen.ts
@@ -1486,7 +1486,9 @@ export const zCallWithDefaultParametersData = z.object({
             'Error'
         ])),
         parameterModel: z.optional(z.union([
-            zModelWithString,
+            zModelWithString.default({
+                prop: 'Hello World!'
+            }),
             z.null()
         ]))
     }))
@@ -1504,7 +1506,9 @@ export const zCallWithDefaultOptionalParametersData = z.object({
             'Warning',
             'Error'
         ])),
-        parameterModel: z.optional(zModelWithString)
+        parameterModel: z.optional(zModelWithString).default({
+            prop: 'Hello World!'
+        })
     }))
 });
 

diff --git a/...ges/openapi-ts-tests/zod/v4/__snapshots__/3.1.x/v4/defaults-with-ref-and-anyof/zod.gen.ts b/...ges/openapi-ts-tests/zod/v4/__snapshots__/3.1.x/v4/defaults-with-ref-and-anyof/zod.gen.ts
@@ -0,0 +1,40 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import { z } from 'zod';
+
+export const zAudioFormat = z.enum([
+    'pcm_16bit_44.1khz',
+    'pcm_16bit_24khz'
+]);
+
+export const zLanguage = z.enum([
+    'en',
+    'es',
+    'fr'
+]);
+
+export const zNestedConfig = z.object({
+    model: z.string().default('gpt-4'),
+    temperature: z.number().default(1)
+});
+
+export const zTestSchema = z.object({
+    primitiveDefault: z.number().default(42),
+    refWithPrimitiveDefault: zAudioFormat.default('pcm_16bit_44.1khz'),
+    refWithObjectDefault: zNestedConfig.default({
+        model: 'gpt-4',
+        temperature: 1
+    }),
+    anyOfWithNullDefault: z.union([
+        z.number(),
+        z.null()
+    ]).default(null),
+    anyOfWithRefAndNullDefault: z.union([
+        zLanguage,
+        z.null()
+    ]).default(null),
+    optionalAnyOfWithDefault: z.optional(z.union([
+        z.string(),
+        z.null()
+    ])).default(null)
+});
diff --git a/packages/openapi-ts-tests/zod/v4/test/3.1.x.test.ts b/packages/openapi-ts-tests/zod/v4/test/3.1.x.test.ts
@@ -42,6 +42,13 @@ for (const zodVersion of zodVersions) {
         description:
           'generates correct array when items are oneOf array with single item',
       },
+      {
+        config: createConfig({
+          input: 'defaults-with-ref-and-anyof.json',
+          output: 'defaults-with-ref-and-anyof',
+        }),
+        description: 'preserves defaults with $ref and anyOf',
+      },
       {
         config: createConfig({
           input: 'enum-null.json',

diff --git a/packages/openapi-ts/src/openApi/3.1.x/parser/schema.ts b/packages/openapi-ts/src/openApi/3.1.x/parser/schema.ts
@@ -382,6 +382,7 @@ const parseAllOf = ({
   state: SchemaState;
 }): IR.SchemaObject => {
   let irSchema = initIrSchema({ schema });
+  parseSchemaMeta({ irSchema, schema });
 
   const schemaItems: Array<IR.SchemaObject> = [];
   const schemaTypes = getSchemaTypes({ schema });
@@ -543,6 +544,7 @@ const parseAnyOf = ({
   state: SchemaState;
 }): IR.SchemaObject => {
   let irSchema = initIrSchema({ schema });
+  parseSchemaMeta({ irSchema, schema });
 
   const schemaItems: Array<IR.SchemaObject> = [];
   const schemaTypes = getSchemaTypes({ schema });
@@ -699,6 +701,7 @@ const parseOneOf = ({
   state: SchemaState;
 }): IR.SchemaObject => {
   let irSchema = initIrSchema({ schema });
+  parseSchemaMeta({ irSchema, schema });
 
   let schemaItems: Array<IR.SchemaObject> = [];
   const schemaTypes = getSchemaTypes({ schema });
@@ -817,6 +820,7 @@ const parseRef = ({
   }
 
   let irSchema = initIrSchema({ schema });
+  parseSchemaMeta({ irSchema, schema });
 
   const irRefSchema: IR.SchemaObject = {};