From 004105f01b062286051fa51c326fbf81bb3db04a Mon Sep 17 00:00:00 2001
From: EduardF1 <50618110+EduardF1@users.noreply.github.com>
Date: Fri, 26 Jun 2026 16:21:44 +0200
Subject: [PATCH] fix(openapi-typescript): emit $defs as optional property
 (#2664)

The generated $defs container was emitted as a required property,
forcing consumers to supply it when using a schema as an input type
even though $defs only hosts reusable subschema definitions. Mark it
optional so it is no longer required on input; $refs that index into
$defs continue to resolve.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .changeset/defs-optional-property.md                        | 5 +++++
 packages/openapi-typescript/src/transform/schema-object.ts  | 2 +-
 packages/openapi-typescript/test/index.test.ts              | 6 +++---
 .../test/transform/schema-object/object.test.ts             | 4 ++--
 4 files changed, 11 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/defs-optional-property.md

diff --git a/.changeset/defs-optional-property.md b/.changeset/defs-optional-property.md
new file mode 100644
index 000000000..461907c42
--- /dev/null
+++ b/.changeset/defs-optional-property.md
@@ -0,0 +1,5 @@
+---
+"openapi-typescript": patch
+---
+
+Emit the generated `$defs` container as an optional property so schemas that declare `$defs` are no longer required to provide it when used as input types. `$refs` that index into `$defs` continue to resolve.
diff --git a/packages/openapi-typescript/src/transform/schema-object.ts b/packages/openapi-typescript/src/transform/schema-object.ts
index caab5e10f..58b92ef1e 100644
--- a/packages/openapi-typescript/src/transform/schema-object.ts
+++ b/packages/openapi-typescript/src/transform/schema-object.ts
@@ -655,7 +655,7 @@ function transformSchemaObjectCore(schemaObject: SchemaObject, options: Transfor
         ts.factory.createPropertySignature(
           /* modifiers     */ undefined,
           /* name          */ tsPropertyIndex("$defs"),
-          /* questionToken */ undefined,
+          /* questionToken */ QUESTION_TOKEN,
           /* type          */ ts.factory.createTypeLiteralNode(defKeys),
         ),
       );
diff --git a/packages/openapi-typescript/test/index.test.ts b/packages/openapi-typescript/test/index.test.ts
index ea8f55426..04a62c5ab 100644
--- a/packages/openapi-typescript/test/index.test.ts
+++ b/packages/openapi-typescript/test/index.test.ts
@@ -590,18 +590,18 @@ export interface components {
             rootDef?: $defs["StringType"];
             nestedDef?: components["schemas"]["OtherObject"]["$defs"]["nestedDef"];
             remoteDef?: components["schemas"]["remoteDef"];
-            $defs: {
+            $defs?: {
                 hasDefs: boolean;
             };
         };
         ArrayOfDefs: $defs["StringType"][];
         OtherObject: {
-            $defs: {
+            $defs?: {
                 nestedDef: boolean;
             };
         };
         RemoteDefs: {
-            $defs: {
+            $defs?: {
                 remoteDef: components["schemas"]["remoteDef"];
             };
         };
diff --git a/packages/openapi-typescript/test/transform/schema-object/object.test.ts b/packages/openapi-typescript/test/transform/schema-object/object.test.ts
index 0ef611a95..72051b1d2 100644
--- a/packages/openapi-typescript/test/transform/schema-object/object.test.ts
+++ b/packages/openapi-typescript/test/transform/schema-object/object.test.ts
@@ -340,7 +340,7 @@ describe("transformSchemaObject > object", () => {
         },
         want: `{
     foo?: string;
-    $defs: {
+    $defs?: {
         /** @enum {string} */
         defEnum: "one" | "two" | "three";
     };
@@ -612,7 +612,7 @@ describe("transformSchemaObject > object", () => {
         },
         want: `{
     foo?: string;
-    $defs: {
+    $defs?: {
         readOnlyDef: $Read<string>;
         writeOnlyDef: $Write<number>;
         normalDef: boolean;