@strapi/openapi 0.0.0-experimental.6340da17068c3bed7fb006e7bcc554c71129e282 → 0.0.0-experimental.63624e21eb5b0713345a0cf2f68f1c40eab427bc

package/dist/utils/zod.d.ts

@@ -1,14 +1,64 @@
 import * as z from 'zod/v4';
+import type { Core } from '@strapi/types';
 import type { OpenAPIV3_1 } from 'openapi-types';
+/**
+ * OpenAPI 3.1 uses the JSON Schema 2020-12 dialect. Zod 4.4.3 has no `openapi-3.1`
+ * target, so `draft-2020-12` preserves valid 3.1 schemas. Explicit output mode preserves
+ * the conversion direction used before these defaults were pinned.
+ */
+export declare const OPENAPI_SCHEMA_CONVERSION_OPTIONS: {
+    readonly target: "draft-2020-12";
+    readonly io: "output";
+};
+/**
+ * Zod 4.4.3 embeds `$id` in registry `toJSONSchema` output when `uri` is configured.
+ * Strip it so OpenAPI documents stay stable — inline schemas use random UUIDs
+ * as registry IDs.
+ */
+export declare const stripJsonSchemaId: <T extends object>(schema: T) => T;
+/**
+ * Generates a path string for referencing a component schema by its identifier.
+ *
+ * @param id - The identifier of the component schema.
+ * @returns The constructed path string for the specified component schema.
+ */
+export declare const toComponentsPath: (id: string) => string;
+/**
+ * Moves Zod's sibling `__shared` bucket into named component schemas and rewrites
+ * `$ref`s that targeted that bucket.
+ *
+ * Zod 4.4.3 emits `#/components/schemas/__shared#/$defs/<id>` when an identified
+ * nested schema is not in the conversion registry. Those definitions must become
+ * first-class `components.schemas` entries; `__shared` is never written out.
+ *
+ * @returns Named schemas lifted from `__shared` (after `$id` stripping). Route
+ *   conversion copies these into the shared harvest bag so ComponentsWriter can
+ *   merge them into the document.
+ */
+export declare const liftZodSharedDefinitions: (schemas: Record<string, unknown>) => Record<string, OpenAPIV3_1.SchemaObject>;
+export type ZodToOpenAPIOptions = {
+    /**
+     * Shared harvest bag filled with named schemas lifted from Zod's `__shared`
+     * bucket. Assemblers pass `context.registries.extractedComponentSchemas` so
+     * ComponentsWriter can merge them into `components.schemas`.
+     */
+    extractedComponentSchemas?: Record<string, OpenAPIV3_1.SchemaObject>;
+};
 /**
  * Converts a Zod schema to an OpenAPI Schema Object.
  *
  * @description
  * Takes a Zod schema and converts it into an OpenAPI Schema Object (v3.1).
  * It uses a local registry to handle the conversion process and generates the appropriate
- * OpenAPI components.
+ * OpenAPI components. Identified nested schemas that Zod would otherwise park in
+ * `__shared` are rewritten to `#/components/schemas/<id>` and copied into
+ * `options.extractedComponentSchemas` when that bag is provided.
  *
  * @param zodSchema - The Zod schema to convert to OpenAPI format. Can be any valid Zod schema.
+ * @param schemaStore - The application-owned content-API schema store to copy named
+ *   component definitions from. Conversion uses a local registry and does not read a
+ *   live Zod registry from the store.
+ * @param options - Optional harvest bag shared across assemblers and ComponentsWriter.
  *
  * @returns An OpenAPI Schema Object representing the input Zod schema structure.
  * If the conversion cannot be completed, returns undefined.
@@ -25,15 +75,8 @@ import type { OpenAPIV3_1 } from 'openapi-types';
  * });
  *
  * // Convert to OpenAPI schema
- * const openAPISchema = zodToOpenAPI(userSchema);
+ * const openAPISchema = zodToOpenAPI(userSchema, strapi.contentAPISchemaRegistry);
  * ```
  */
-export declare const zodToOpenAPI: (zodSchema: z.ZodType) => OpenAPIV3_1.SchemaObject | OpenAPIV3_1.ReferenceObject;
-/**
- * Generates a path string for referencing a component schema by its identifier.
- *
- * @param id - The identifier of the component schema.
- * @returns The constructed path string for the specified component schema.
- */
-export declare const toComponentsPath: (id: string) => string;
+export declare const zodToOpenAPI: (zodSchema: z.ZodType, schemaStore: Core.ContentAPISchemaRegistry, options?: ZodToOpenAPIOptions) => OpenAPIV3_1.SchemaObject | OpenAPIV3_1.ReferenceObject;
 //# sourceMappingURL=zod.d.ts.map

package/dist/utils/zod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zod.d.ts","sourceRoot":"","sources":["../../src/utils/zod.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,eAAO,MAAM,YAAY,GACvB,WAAW,CAAC,CAAC,OAAO,KACnB,WAAW,CAAC,YAAY,GAAG,WAAW,CAAC,eAsBzC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,IAAI,MAAM,WAAiC,CAAC"}
+{"version":3,"file":"zod.d.ts","sourceRoot":"","sources":["../../src/utils/zod.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,iCAAiC;;;CAG+B,CAAC;AAc9E;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,MAAM,EAAE,QAAQ,CAAC,KAAG,CAK/D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,IAAI,MAAM,WAAiC,CAAC;AA4C7E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,GACnC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC/B,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,YAAY,CAoCzC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC;;;;OAIG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;CACtE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,YAAY,GACvB,WAAW,CAAC,CAAC,OAAO,EACpB,aAAa,IAAI,CAAC,wBAAwB,EAC1C,UAAU,mBAAmB,KAC5B,WAAW,CAAC,YAAY,GAAG,WAAW,CAAC,eA+BzC,CAAC"}

package/dist/utils/zod.js

@@ -23,15 +23,127 @@ function _interopNamespace(e) {
 
 var z__namespace = /*#__PURE__*/_interopNamespace(z);
 
+/**
+ * OpenAPI 3.1 uses the JSON Schema 2020-12 dialect. Zod 4.4.3 has no `openapi-3.1`
+ * target, so `draft-2020-12` preserves valid 3.1 schemas. Explicit output mode preserves
+ * the conversion direction used before these defaults were pinned.
+ */ const OPENAPI_SCHEMA_CONVERSION_OPTIONS = {
+    target: 'draft-2020-12',
+    io: 'output'
+};
+const ZOD_SHARED_BUCKET = '__shared';
+/**
+ * Zod 4.4.3 emits `#/components/schemas/__shared#/$defs/<id>` (and close variants)
+ * when an identified nested schema is missing from the conversion registry.
+ */ const ZOD_SHARED_REF_RE = /^#\/components\/schemas\/__shared#?\/(?:\$defs|definitions)\/(.+)$/;
+const isPlainObject = (value)=>{
+    return typeof value === 'object' && value !== null && Array.isArray(value) === false;
+};
+/**
+ * Zod 4.4.3 embeds `$id` in registry `toJSONSchema` output when `uri` is configured.
+ * Strip it so OpenAPI documents stay stable — inline schemas use random UUIDs
+ * as registry IDs.
+ */ const stripJsonSchemaId = (schema)=>{
+    if ('$id' in schema) {
+        delete schema.$id;
+    }
+    return schema;
+};
+/**
+ * Generates a path string for referencing a component schema by its identifier.
+ *
+ * @param id - The identifier of the component schema.
+ * @returns The constructed path string for the specified component schema.
+ */ const toComponentsPath = (id)=>`#/components/schemas/${id}`;
+const rewriteZodSharedRef = (ref)=>{
+    const match = ZOD_SHARED_REF_RE.exec(ref);
+    const id = match?.[1];
+    if (id === undefined || id.length === 0) {
+        return ref;
+    }
+    return toComponentsPath(id);
+};
+const rewriteZodSharedRefs = (value, seen = new WeakSet())=>{
+    if (Array.isArray(value)) {
+        if (seen.has(value)) {
+            return;
+        }
+        seen.add(value);
+        for (const item of value){
+            rewriteZodSharedRefs(item, seen);
+        }
+        return;
+    }
+    if (isPlainObject(value) === false) {
+        return;
+    }
+    if (seen.has(value)) {
+        return;
+    }
+    seen.add(value);
+    const ref = value.$ref;
+    if (typeof ref === 'string') {
+        value.$ref = rewriteZodSharedRef(ref);
+    }
+    for (const nested of Object.values(value)){
+        rewriteZodSharedRefs(nested, seen);
+    }
+};
+/**
+ * Moves Zod's sibling `__shared` bucket into named component schemas and rewrites
+ * `$ref`s that targeted that bucket.
+ *
+ * Zod 4.4.3 emits `#/components/schemas/__shared#/$defs/<id>` when an identified
+ * nested schema is not in the conversion registry. Those definitions must become
+ * first-class `components.schemas` entries; `__shared` is never written out.
+ *
+ * @returns Named schemas lifted from `__shared` (after `$id` stripping). Route
+ *   conversion copies these into the shared harvest bag so ComponentsWriter can
+ *   merge them into the document.
+ */ const liftZodSharedDefinitions = (schemas)=>{
+    const harvested = {};
+    const shared = schemas[ZOD_SHARED_BUCKET];
+    if (isPlainObject(shared)) {
+        const defs = shared.$defs ?? shared.definitions;
+        if (isPlainObject(defs)) {
+            for (const [id, def] of Object.entries(defs)){
+                if (isPlainObject(def) === false) {
+                    continue;
+                }
+                const cleaned = stripJsonSchemaId(def);
+                harvested[id] = cleaned;
+                if (schemas[id] === undefined) {
+                    schemas[id] = cleaned;
+                }
+            }
+        }
+        delete schemas[ZOD_SHARED_BUCKET];
+    }
+    const seen = new WeakSet();
+    rewriteZodSharedRefs(schemas, seen);
+    rewriteZodSharedRefs(harvested, seen);
+    for (const schema of Object.values(schemas)){
+        if (isPlainObject(schema)) {
+            stripJsonSchemaId(schema);
+        }
+    }
+    return harvested;
+};
 /**
  * Converts a Zod schema to an OpenAPI Schema Object.
  *
  * @description
  * Takes a Zod schema and converts it into an OpenAPI Schema Object (v3.1).
  * It uses a local registry to handle the conversion process and generates the appropriate
- * OpenAPI components.
+ * OpenAPI components. Identified nested schemas that Zod would otherwise park in
+ * `__shared` are rewritten to `#/components/schemas/<id>` and copied into
+ * `options.extractedComponentSchemas` when that bag is provided.
  *
  * @param zodSchema - The Zod schema to convert to OpenAPI format. Can be any valid Zod schema.
+ * @param schemaStore - The application-owned content-API schema store to copy named
+ *   component definitions from. Conversion uses a local registry and does not read a
+ *   live Zod registry from the store.
+ * @param options - Optional harvest bag shared across assemblers and ComponentsWriter.
  *
  * @returns An OpenAPI Schema Object representing the input Zod schema structure.
  * If the conversion cannot be completed, returns undefined.
@@ -48,9 +160,9 @@ var z__namespace = /*#__PURE__*/_interopNamespace(z);
  * });
  *
  * // Convert to OpenAPI schema
- * const openAPISchema = zodToOpenAPI(userSchema);
+ * const openAPISchema = zodToOpenAPI(userSchema, strapi.contentAPISchemaRegistry);
  * ```
- */ const zodToOpenAPI = (zodSchema)=>{
+ */ const zodToOpenAPI = (zodSchema, schemaStore, options)=>{
     try {
         const id = node_crypto.randomUUID();
         const registry = z__namespace.registry();
@@ -58,30 +170,32 @@ var z__namespace = /*#__PURE__*/_interopNamespace(z);
         registry.add(zodSchema, {
             id
         });
-        // Copy the global registry definitions into the local registry to make sure references are resolved
-        // This prevent "__shared" definitions from being created
-        for (const [key, value] of z__namespace.globalRegistry._idmap){
+        // Copy Strapi-owned definitions into the local registry so references resolve without
+        // generating "__shared" definitions.
+        for (const [key, value] of schemaStore.entries()){
             registry.add(value, {
                 id: key
             });
         }
         // Generate the schemas and only return the one we want, transform the URI path to be OpenAPI compliant
         const { schemas } = z__namespace.toJSONSchema(registry, {
+            ...OPENAPI_SCHEMA_CONVERSION_OPTIONS,
             uri: toComponentsPath
         });
+        const harvested = isPlainObject(schemas) ? liftZodSharedDefinitions(schemas) : {};
+        if (options?.extractedComponentSchemas !== undefined) {
+            Object.assign(options.extractedComponentSchemas, harvested);
+        }
         // TODO: make sure it's compliant
-        return schemas[id];
-    } catch (e) {
+        return stripJsonSchemaId(schemas[id]);
+    } catch  {
         throw new Error("Couldn't transform the zod schema into an OpenAPI schema");
     }
 };
-/**
- * Generates a path string for referencing a component schema by its identifier.
- *
- * @param id - The identifier of the component schema.
- * @returns The constructed path string for the specified component schema.
- */ const toComponentsPath = (id)=>`#/components/schemas/${id}`;
 
+exports.OPENAPI_SCHEMA_CONVERSION_OPTIONS = OPENAPI_SCHEMA_CONVERSION_OPTIONS;
+exports.liftZodSharedDefinitions = liftZodSharedDefinitions;
+exports.stripJsonSchemaId = stripJsonSchemaId;
 exports.toComponentsPath = toComponentsPath;
 exports.zodToOpenAPI = zodToOpenAPI;
 //# sourceMappingURL=zod.js.map

package/dist/utils/zod.js.map

@@ -1 +1 @@
-{"version":3,"file":"zod.js","sources":["../../src/utils/zod.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\nimport * as z from 'zod/v4';\n\nimport type { OpenAPIV3_1 } from 'openapi-types';\n\n/**\n * Converts a Zod schema to an OpenAPI Schema Object.\n *\n * @description\n * Takes a Zod schema and converts it into an OpenAPI Schema Object (v3.1).\n * It uses a local registry to handle the conversion process and generates the appropriate\n * OpenAPI components.\n *\n * @param zodSchema - The Zod schema to convert to OpenAPI format. Can be any valid Zod schema.\n *\n * @returns An OpenAPI Schema Object representing the input Zod schema structure.\n * If the conversion cannot be completed, returns undefined.\n *\n * @example\n * ```typescript\n * import * as z from 'zod/v4';\n *\n * // Create a Zod schema\n * const userSchema = z.object({\n *   id: z.number(),\n *   name: z.string(),\n *   email: z.string().email()\n * });\n *\n * // Convert to OpenAPI schema\n * const openAPISchema = zodToOpenAPI(userSchema);\n * ```\n */\n\nexport const zodToOpenAPI = (\n  zodSchema: z.ZodType\n): OpenAPIV3_1.SchemaObject | OpenAPIV3_1.ReferenceObject => {\n  try {\n    const id = randomUUID();\n    const registry = z.registry<{ id: string }>();\n\n    // Add the schema to the local registry with a custom, unique ID\n    registry.add(zodSchema, { id });\n\n    // Copy the global registry definitions into the local registry to make sure references are resolved\n    // This prevent \"__shared\" definitions from being created\n    for (const [key, value] of z.globalRegistry._idmap) {\n      registry.add(value, { id: key });\n    }\n\n    // Generate the schemas and only return the one we want, transform the URI path to be OpenAPI compliant\n    const { schemas } = z.toJSONSchema(registry, { uri: toComponentsPath });\n\n    // TODO: make sure it's compliant\n    return schemas[id] as OpenAPIV3_1.SchemaObject;\n  } catch (e) {\n    throw new Error(\"Couldn't transform the zod schema into an OpenAPI schema\");\n  }\n};\n\n/**\n * Generates a path string for referencing a component schema by its identifier.\n *\n * @param id - The identifier of the component schema.\n * @returns The constructed path string for the specified component schema.\n */\nexport const toComponentsPath = (id: string) => `#/components/schemas/${id}`;\n"],"names":["zodToOpenAPI","zodSchema","id","randomUUID","registry","z","add","key","value","globalRegistry","_idmap","schemas","toJSONSchema","uri","toComponentsPath","e","Error"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;IA6BO,MAAMA,YAAAA,GAAe,CAC1BC,SAAAA,GAAAA;IAEA,IAAI;AACF,QAAA,MAAMC,EAAAA,GAAKC,sBAAAA,EAAAA;QACX,MAAMC,QAAAA,GAAWC,aAAED,QAAQ,EAAA;;QAG3BA,QAAAA,CAASE,GAAG,CAACL,SAAAA,EAAW;AAAEC,YAAAA;AAAG,SAAA,CAAA;;;QAI7B,KAAK,MAAM,CAACK,GAAAA,EAAKC,KAAAA,CAAM,IAAIH,YAAAA,CAAEI,cAAc,CAACC,MAAM,CAAE;YAClDN,QAAAA,CAASE,GAAG,CAACE,KAAAA,EAAO;gBAAEN,EAAAA,EAAIK;AAAI,aAAA,CAAA;AAChC,QAAA;;AAGA,QAAA,MAAM,EAAEI,OAAO,EAAE,GAAGN,YAAAA,CAAEO,YAAY,CAACR,QAAAA,EAAU;YAAES,GAAAA,EAAKC;AAAiB,SAAA,CAAA;;QAGrE,OAAOH,OAAO,CAACT,EAAAA,CAAG;AACpB,IAAA,CAAA,CAAE,OAAOa,CAAAA,EAAG;AACV,QAAA,MAAM,IAAIC,KAAAA,CAAM,0DAAA,CAAA;AAClB,IAAA;AACF;AAEA;;;;;UAMaF,gBAAAA,GAAmB,CAACZ,KAAe,CAAC,qBAAqB,EAAEA,EAAAA,CAAAA;;;;;"}
+{"version":3,"file":"zod.js","sources":["../../src/utils/zod.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\nimport * as z from 'zod/v4';\n\nimport type { Core } from '@strapi/types';\nimport type { OpenAPIV3_1 } from 'openapi-types';\n\n/**\n * OpenAPI 3.1 uses the JSON Schema 2020-12 dialect. Zod 4.4.3 has no `openapi-3.1`\n * target, so `draft-2020-12` preserves valid 3.1 schemas. Explicit output mode preserves\n * the conversion direction used before these defaults were pinned.\n */\nexport const OPENAPI_SCHEMA_CONVERSION_OPTIONS = {\n  target: 'draft-2020-12',\n  io: 'output',\n} as const satisfies Pick<z.core.RegistryToJSONSchemaParams, 'target' | 'io'>;\n\nconst ZOD_SHARED_BUCKET = '__shared';\n\n/**\n * Zod 4.4.3 emits `#/components/schemas/__shared#/$defs/<id>` (and close variants)\n * when an identified nested schema is missing from the conversion registry.\n */\nconst ZOD_SHARED_REF_RE = /^#\\/components\\/schemas\\/__shared#?\\/(?:\\$defs|definitions)\\/(.+)$/;\n\nconst isPlainObject = (value: unknown): value is Record<string, unknown> => {\n  return typeof value === 'object' && value !== null && Array.isArray(value) === false;\n};\n\n/**\n * Zod 4.4.3 embeds `$id` in registry `toJSONSchema` output when `uri` is configured.\n * Strip it so OpenAPI documents stay stable — inline schemas use random UUIDs\n * as registry IDs.\n */\nexport const stripJsonSchemaId = <T extends object>(schema: T): T => {\n  if ('$id' in schema) {\n    delete (schema as { $id?: string }).$id;\n  }\n  return schema;\n};\n\n/**\n * Generates a path string for referencing a component schema by its identifier.\n *\n * @param id - The identifier of the component schema.\n * @returns The constructed path string for the specified component schema.\n */\nexport const toComponentsPath = (id: string) => `#/components/schemas/${id}`;\n\nconst rewriteZodSharedRef = (ref: string): string => {\n  const match = ZOD_SHARED_REF_RE.exec(ref);\n  const id = match?.[1];\n\n  if (id === undefined || id.length === 0) {\n    return ref;\n  }\n\n  return toComponentsPath(id);\n};\n\nconst rewriteZodSharedRefs = (value: unknown, seen: WeakSet<object> = new WeakSet()): void => {\n  if (Array.isArray(value)) {\n    if (seen.has(value)) {\n      return;\n    }\n    seen.add(value);\n    for (const item of value) {\n      rewriteZodSharedRefs(item, seen);\n    }\n    return;\n  }\n\n  if (isPlainObject(value) === false) {\n    return;\n  }\n\n  if (seen.has(value)) {\n    return;\n  }\n  seen.add(value);\n\n  const ref = value.$ref;\n  if (typeof ref === 'string') {\n    value.$ref = rewriteZodSharedRef(ref);\n  }\n\n  for (const nested of Object.values(value)) {\n    rewriteZodSharedRefs(nested, seen);\n  }\n};\n\n/**\n * Moves Zod's sibling `__shared` bucket into named component schemas and rewrites\n * `$ref`s that targeted that bucket.\n *\n * Zod 4.4.3 emits `#/components/schemas/__shared#/$defs/<id>` when an identified\n * nested schema is not in the conversion registry. Those definitions must become\n * first-class `components.schemas` entries; `__shared` is never written out.\n *\n * @returns Named schemas lifted from `__shared` (after `$id` stripping). Route\n *   conversion copies these into the shared harvest bag so ComponentsWriter can\n *   merge them into the document.\n */\nexport const liftZodSharedDefinitions = (\n  schemas: Record<string, unknown>\n): Record<string, OpenAPIV3_1.SchemaObject> => {\n  const harvested: Record<string, OpenAPIV3_1.SchemaObject> = {};\n  const shared = schemas[ZOD_SHARED_BUCKET];\n\n  if (isPlainObject(shared)) {\n    const defs = shared.$defs ?? shared.definitions;\n\n    if (isPlainObject(defs)) {\n      for (const [id, def] of Object.entries(defs)) {\n        if (isPlainObject(def) === false) {\n          continue;\n        }\n\n        const cleaned = stripJsonSchemaId(def) as OpenAPIV3_1.SchemaObject;\n        harvested[id] = cleaned;\n\n        if (schemas[id] === undefined) {\n          schemas[id] = cleaned;\n        }\n      }\n    }\n\n    delete schemas[ZOD_SHARED_BUCKET];\n  }\n\n  const seen = new WeakSet<object>();\n  rewriteZodSharedRefs(schemas, seen);\n  rewriteZodSharedRefs(harvested, seen);\n\n  for (const schema of Object.values(schemas)) {\n    if (isPlainObject(schema)) {\n      stripJsonSchemaId(schema);\n    }\n  }\n\n  return harvested;\n};\n\nexport type ZodToOpenAPIOptions = {\n  /**\n   * Shared harvest bag filled with named schemas lifted from Zod's `__shared`\n   * bucket. Assemblers pass `context.registries.extractedComponentSchemas` so\n   * ComponentsWriter can merge them into `components.schemas`.\n   */\n  extractedComponentSchemas?: Record<string, OpenAPIV3_1.SchemaObject>;\n};\n\n/**\n * Converts a Zod schema to an OpenAPI Schema Object.\n *\n * @description\n * Takes a Zod schema and converts it into an OpenAPI Schema Object (v3.1).\n * It uses a local registry to handle the conversion process and generates the appropriate\n * OpenAPI components. Identified nested schemas that Zod would otherwise park in\n * `__shared` are rewritten to `#/components/schemas/<id>` and copied into\n * `options.extractedComponentSchemas` when that bag is provided.\n *\n * @param zodSchema - The Zod schema to convert to OpenAPI format. Can be any valid Zod schema.\n * @param schemaStore - The application-owned content-API schema store to copy named\n *   component definitions from. Conversion uses a local registry and does not read a\n *   live Zod registry from the store.\n * @param options - Optional harvest bag shared across assemblers and ComponentsWriter.\n *\n * @returns An OpenAPI Schema Object representing the input Zod schema structure.\n * If the conversion cannot be completed, returns undefined.\n *\n * @example\n * ```typescript\n * import * as z from 'zod/v4';\n *\n * // Create a Zod schema\n * const userSchema = z.object({\n *   id: z.number(),\n *   name: z.string(),\n *   email: z.string().email()\n * });\n *\n * // Convert to OpenAPI schema\n * const openAPISchema = zodToOpenAPI(userSchema, strapi.contentAPISchemaRegistry);\n * ```\n */\nexport const zodToOpenAPI = (\n  zodSchema: z.ZodType,\n  schemaStore: Core.ContentAPISchemaRegistry,\n  options?: ZodToOpenAPIOptions\n): OpenAPIV3_1.SchemaObject | OpenAPIV3_1.ReferenceObject => {\n  try {\n    const id = randomUUID();\n    const registry = z.registry<{ id: string }>();\n\n    // Add the schema to the local registry with a custom, unique ID\n    registry.add(zodSchema, { id });\n\n    // Copy Strapi-owned definitions into the local registry so references resolve without\n    // generating \"__shared\" definitions.\n    for (const [key, value] of schemaStore.entries()) {\n      registry.add(value, { id: key });\n    }\n\n    // Generate the schemas and only return the one we want, transform the URI path to be OpenAPI compliant\n    const { schemas } = z.toJSONSchema(registry, {\n      ...OPENAPI_SCHEMA_CONVERSION_OPTIONS,\n      uri: toComponentsPath,\n    });\n\n    const harvested = isPlainObject(schemas) ? liftZodSharedDefinitions(schemas) : {};\n\n    if (options?.extractedComponentSchemas !== undefined) {\n      Object.assign(options.extractedComponentSchemas, harvested);\n    }\n\n    // TODO: make sure it's compliant\n    return stripJsonSchemaId(schemas[id] as OpenAPIV3_1.SchemaObject);\n  } catch {\n    throw new Error(\"Couldn't transform the zod schema into an OpenAPI schema\");\n  }\n};\n"],"names":["OPENAPI_SCHEMA_CONVERSION_OPTIONS","target","io","ZOD_SHARED_BUCKET","ZOD_SHARED_REF_RE","isPlainObject","value","Array","isArray","stripJsonSchemaId","schema","$id","toComponentsPath","id","rewriteZodSharedRef","ref","match","exec","undefined","length","rewriteZodSharedRefs","seen","WeakSet","has","add","item","$ref","nested","Object","values","liftZodSharedDefinitions","schemas","harvested","shared","defs","$defs","definitions","def","entries","cleaned","zodToOpenAPI","zodSchema","schemaStore","options","randomUUID","registry","z","key","toJSONSchema","uri","extractedComponentSchemas","assign","Error"],"mappings":"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"}

package/dist/utils/zod.mjs

@@ -1,15 +1,127 @@
 import { randomUUID } from 'node:crypto';
 import * as z from 'zod/v4';
 
+/**
+ * OpenAPI 3.1 uses the JSON Schema 2020-12 dialect. Zod 4.4.3 has no `openapi-3.1`
+ * target, so `draft-2020-12` preserves valid 3.1 schemas. Explicit output mode preserves
+ * the conversion direction used before these defaults were pinned.
+ */ const OPENAPI_SCHEMA_CONVERSION_OPTIONS = {
+    target: 'draft-2020-12',
+    io: 'output'
+};
+const ZOD_SHARED_BUCKET = '__shared';
+/**
+ * Zod 4.4.3 emits `#/components/schemas/__shared#/$defs/<id>` (and close variants)
+ * when an identified nested schema is missing from the conversion registry.
+ */ const ZOD_SHARED_REF_RE = /^#\/components\/schemas\/__shared#?\/(?:\$defs|definitions)\/(.+)$/;
+const isPlainObject = (value)=>{
+    return typeof value === 'object' && value !== null && Array.isArray(value) === false;
+};
+/**
+ * Zod 4.4.3 embeds `$id` in registry `toJSONSchema` output when `uri` is configured.
+ * Strip it so OpenAPI documents stay stable — inline schemas use random UUIDs
+ * as registry IDs.
+ */ const stripJsonSchemaId = (schema)=>{
+    if ('$id' in schema) {
+        delete schema.$id;
+    }
+    return schema;
+};
+/**
+ * Generates a path string for referencing a component schema by its identifier.
+ *
+ * @param id - The identifier of the component schema.
+ * @returns The constructed path string for the specified component schema.
+ */ const toComponentsPath = (id)=>`#/components/schemas/${id}`;
+const rewriteZodSharedRef = (ref)=>{
+    const match = ZOD_SHARED_REF_RE.exec(ref);
+    const id = match?.[1];
+    if (id === undefined || id.length === 0) {
+        return ref;
+    }
+    return toComponentsPath(id);
+};
+const rewriteZodSharedRefs = (value, seen = new WeakSet())=>{
+    if (Array.isArray(value)) {
+        if (seen.has(value)) {
+            return;
+        }
+        seen.add(value);
+        for (const item of value){
+            rewriteZodSharedRefs(item, seen);
+        }
+        return;
+    }
+    if (isPlainObject(value) === false) {
+        return;
+    }
+    if (seen.has(value)) {
+        return;
+    }
+    seen.add(value);
+    const ref = value.$ref;
+    if (typeof ref === 'string') {
+        value.$ref = rewriteZodSharedRef(ref);
+    }
+    for (const nested of Object.values(value)){
+        rewriteZodSharedRefs(nested, seen);
+    }
+};
+/**
+ * Moves Zod's sibling `__shared` bucket into named component schemas and rewrites
+ * `$ref`s that targeted that bucket.
+ *
+ * Zod 4.4.3 emits `#/components/schemas/__shared#/$defs/<id>` when an identified
+ * nested schema is not in the conversion registry. Those definitions must become
+ * first-class `components.schemas` entries; `__shared` is never written out.
+ *
+ * @returns Named schemas lifted from `__shared` (after `$id` stripping). Route
+ *   conversion copies these into the shared harvest bag so ComponentsWriter can
+ *   merge them into the document.
+ */ const liftZodSharedDefinitions = (schemas)=>{
+    const harvested = {};
+    const shared = schemas[ZOD_SHARED_BUCKET];
+    if (isPlainObject(shared)) {
+        const defs = shared.$defs ?? shared.definitions;
+        if (isPlainObject(defs)) {
+            for (const [id, def] of Object.entries(defs)){
+                if (isPlainObject(def) === false) {
+                    continue;
+                }
+                const cleaned = stripJsonSchemaId(def);
+                harvested[id] = cleaned;
+                if (schemas[id] === undefined) {
+                    schemas[id] = cleaned;
+                }
+            }
+        }
+        delete schemas[ZOD_SHARED_BUCKET];
+    }
+    const seen = new WeakSet();
+    rewriteZodSharedRefs(schemas, seen);
+    rewriteZodSharedRefs(harvested, seen);
+    for (const schema of Object.values(schemas)){
+        if (isPlainObject(schema)) {
+            stripJsonSchemaId(schema);
+        }
+    }
+    return harvested;
+};
 /**
  * Converts a Zod schema to an OpenAPI Schema Object.
  *
  * @description
  * Takes a Zod schema and converts it into an OpenAPI Schema Object (v3.1).
  * It uses a local registry to handle the conversion process and generates the appropriate
- * OpenAPI components.
+ * OpenAPI components. Identified nested schemas that Zod would otherwise park in
+ * `__shared` are rewritten to `#/components/schemas/<id>` and copied into
+ * `options.extractedComponentSchemas` when that bag is provided.
  *
  * @param zodSchema - The Zod schema to convert to OpenAPI format. Can be any valid Zod schema.
+ * @param schemaStore - The application-owned content-API schema store to copy named
+ *   component definitions from. Conversion uses a local registry and does not read a
+ *   live Zod registry from the store.
+ * @param options - Optional harvest bag shared across assemblers and ComponentsWriter.
  *
  * @returns An OpenAPI Schema Object representing the input Zod schema structure.
  * If the conversion cannot be completed, returns undefined.
@@ -26,9 +138,9 @@ import * as z from 'zod/v4';
  * });
  *
  * // Convert to OpenAPI schema
- * const openAPISchema = zodToOpenAPI(userSchema);
+ * const openAPISchema = zodToOpenAPI(userSchema, strapi.contentAPISchemaRegistry);
  * ```
- */ const zodToOpenAPI = (zodSchema)=>{
+ */ const zodToOpenAPI = (zodSchema, schemaStore, options)=>{
     try {
         const id = randomUUID();
         const registry = z.registry();
@@ -36,29 +148,28 @@ import * as z from 'zod/v4';
         registry.add(zodSchema, {
             id
         });
-        // Copy the global registry definitions into the local registry to make sure references are resolved
-        // This prevent "__shared" definitions from being created
-        for (const [key, value] of z.globalRegistry._idmap){
+        // Copy Strapi-owned definitions into the local registry so references resolve without
+        // generating "__shared" definitions.
+        for (const [key, value] of schemaStore.entries()){
             registry.add(value, {
                 id: key
             });
         }
         // Generate the schemas and only return the one we want, transform the URI path to be OpenAPI compliant
         const { schemas } = z.toJSONSchema(registry, {
+            ...OPENAPI_SCHEMA_CONVERSION_OPTIONS,
             uri: toComponentsPath
         });
+        const harvested = isPlainObject(schemas) ? liftZodSharedDefinitions(schemas) : {};
+        if (options?.extractedComponentSchemas !== undefined) {
+            Object.assign(options.extractedComponentSchemas, harvested);
+        }
         // TODO: make sure it's compliant
-        return schemas[id];
-    } catch (e) {
+        return stripJsonSchemaId(schemas[id]);
+    } catch  {
         throw new Error("Couldn't transform the zod schema into an OpenAPI schema");
     }
 };
-/**
- * Generates a path string for referencing a component schema by its identifier.
- *
- * @param id - The identifier of the component schema.
- * @returns The constructed path string for the specified component schema.
- */ const toComponentsPath = (id)=>`#/components/schemas/${id}`;
 
-export { toComponentsPath, zodToOpenAPI };
+export { OPENAPI_SCHEMA_CONVERSION_OPTIONS, liftZodSharedDefinitions, stripJsonSchemaId, toComponentsPath, zodToOpenAPI };
 //# sourceMappingURL=zod.mjs.map

package/dist/utils/zod.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"zod.mjs","sources":["../../src/utils/zod.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\nimport * as z from 'zod/v4';\n\nimport type { OpenAPIV3_1 } from 'openapi-types';\n\n/**\n * Converts a Zod schema to an OpenAPI Schema Object.\n *\n * @description\n * Takes a Zod schema and converts it into an OpenAPI Schema Object (v3.1).\n * It uses a local registry to handle the conversion process and generates the appropriate\n * OpenAPI components.\n *\n * @param zodSchema - The Zod schema to convert to OpenAPI format. Can be any valid Zod schema.\n *\n * @returns An OpenAPI Schema Object representing the input Zod schema structure.\n * If the conversion cannot be completed, returns undefined.\n *\n * @example\n * ```typescript\n * import * as z from 'zod/v4';\n *\n * // Create a Zod schema\n * const userSchema = z.object({\n *   id: z.number(),\n *   name: z.string(),\n *   email: z.string().email()\n * });\n *\n * // Convert to OpenAPI schema\n * const openAPISchema = zodToOpenAPI(userSchema);\n * ```\n */\n\nexport const zodToOpenAPI = (\n  zodSchema: z.ZodType\n): OpenAPIV3_1.SchemaObject | OpenAPIV3_1.ReferenceObject => {\n  try {\n    const id = randomUUID();\n    const registry = z.registry<{ id: string }>();\n\n    // Add the schema to the local registry with a custom, unique ID\n    registry.add(zodSchema, { id });\n\n    // Copy the global registry definitions into the local registry to make sure references are resolved\n    // This prevent \"__shared\" definitions from being created\n    for (const [key, value] of z.globalRegistry._idmap) {\n      registry.add(value, { id: key });\n    }\n\n    // Generate the schemas and only return the one we want, transform the URI path to be OpenAPI compliant\n    const { schemas } = z.toJSONSchema(registry, { uri: toComponentsPath });\n\n    // TODO: make sure it's compliant\n    return schemas[id] as OpenAPIV3_1.SchemaObject;\n  } catch (e) {\n    throw new Error(\"Couldn't transform the zod schema into an OpenAPI schema\");\n  }\n};\n\n/**\n * Generates a path string for referencing a component schema by its identifier.\n *\n * @param id - The identifier of the component schema.\n * @returns The constructed path string for the specified component schema.\n */\nexport const toComponentsPath = (id: string) => `#/components/schemas/${id}`;\n"],"names":["zodToOpenAPI","zodSchema","id","randomUUID","registry","z","add","key","value","globalRegistry","_idmap","schemas","toJSONSchema","uri","toComponentsPath","e","Error"],"mappings":";;;AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;IA6BO,MAAMA,YAAAA,GAAe,CAC1BC,SAAAA,GAAAA;IAEA,IAAI;AACF,QAAA,MAAMC,EAAAA,GAAKC,UAAAA,EAAAA;QACX,MAAMC,QAAAA,GAAWC,EAAED,QAAQ,EAAA;;QAG3BA,QAAAA,CAASE,GAAG,CAACL,SAAAA,EAAW;AAAEC,YAAAA;AAAG,SAAA,CAAA;;;QAI7B,KAAK,MAAM,CAACK,GAAAA,EAAKC,KAAAA,CAAM,IAAIH,CAAAA,CAAEI,cAAc,CAACC,MAAM,CAAE;YAClDN,QAAAA,CAASE,GAAG,CAACE,KAAAA,EAAO;gBAAEN,EAAAA,EAAIK;AAAI,aAAA,CAAA;AAChC,QAAA;;AAGA,QAAA,MAAM,EAAEI,OAAO,EAAE,GAAGN,CAAAA,CAAEO,YAAY,CAACR,QAAAA,EAAU;YAAES,GAAAA,EAAKC;AAAiB,SAAA,CAAA;;QAGrE,OAAOH,OAAO,CAACT,EAAAA,CAAG;AACpB,IAAA,CAAA,CAAE,OAAOa,CAAAA,EAAG;AACV,QAAA,MAAM,IAAIC,KAAAA,CAAM,0DAAA,CAAA;AAClB,IAAA;AACF;AAEA;;;;;UAMaF,gBAAAA,GAAmB,CAACZ,KAAe,CAAC,qBAAqB,EAAEA,EAAAA,CAAAA;;;;"}
+{"version":3,"file":"zod.mjs","sources":["../../src/utils/zod.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\nimport * as z from 'zod/v4';\n\nimport type { Core } from '@strapi/types';\nimport type { OpenAPIV3_1 } from 'openapi-types';\n\n/**\n * OpenAPI 3.1 uses the JSON Schema 2020-12 dialect. Zod 4.4.3 has no `openapi-3.1`\n * target, so `draft-2020-12` preserves valid 3.1 schemas. Explicit output mode preserves\n * the conversion direction used before these defaults were pinned.\n */\nexport const OPENAPI_SCHEMA_CONVERSION_OPTIONS = {\n  target: 'draft-2020-12',\n  io: 'output',\n} as const satisfies Pick<z.core.RegistryToJSONSchemaParams, 'target' | 'io'>;\n\nconst ZOD_SHARED_BUCKET = '__shared';\n\n/**\n * Zod 4.4.3 emits `#/components/schemas/__shared#/$defs/<id>` (and close variants)\n * when an identified nested schema is missing from the conversion registry.\n */\nconst ZOD_SHARED_REF_RE = /^#\\/components\\/schemas\\/__shared#?\\/(?:\\$defs|definitions)\\/(.+)$/;\n\nconst isPlainObject = (value: unknown): value is Record<string, unknown> => {\n  return typeof value === 'object' && value !== null && Array.isArray(value) === false;\n};\n\n/**\n * Zod 4.4.3 embeds `$id` in registry `toJSONSchema` output when `uri` is configured.\n * Strip it so OpenAPI documents stay stable — inline schemas use random UUIDs\n * as registry IDs.\n */\nexport const stripJsonSchemaId = <T extends object>(schema: T): T => {\n  if ('$id' in schema) {\n    delete (schema as { $id?: string }).$id;\n  }\n  return schema;\n};\n\n/**\n * Generates a path string for referencing a component schema by its identifier.\n *\n * @param id - The identifier of the component schema.\n * @returns The constructed path string for the specified component schema.\n */\nexport const toComponentsPath = (id: string) => `#/components/schemas/${id}`;\n\nconst rewriteZodSharedRef = (ref: string): string => {\n  const match = ZOD_SHARED_REF_RE.exec(ref);\n  const id = match?.[1];\n\n  if (id === undefined || id.length === 0) {\n    return ref;\n  }\n\n  return toComponentsPath(id);\n};\n\nconst rewriteZodSharedRefs = (value: unknown, seen: WeakSet<object> = new WeakSet()): void => {\n  if (Array.isArray(value)) {\n    if (seen.has(value)) {\n      return;\n    }\n    seen.add(value);\n    for (const item of value) {\n      rewriteZodSharedRefs(item, seen);\n    }\n    return;\n  }\n\n  if (isPlainObject(value) === false) {\n    return;\n  }\n\n  if (seen.has(value)) {\n    return;\n  }\n  seen.add(value);\n\n  const ref = value.$ref;\n  if (typeof ref === 'string') {\n    value.$ref = rewriteZodSharedRef(ref);\n  }\n\n  for (const nested of Object.values(value)) {\n    rewriteZodSharedRefs(nested, seen);\n  }\n};\n\n/**\n * Moves Zod's sibling `__shared` bucket into named component schemas and rewrites\n * `$ref`s that targeted that bucket.\n *\n * Zod 4.4.3 emits `#/components/schemas/__shared#/$defs/<id>` when an identified\n * nested schema is not in the conversion registry. Those definitions must become\n * first-class `components.schemas` entries; `__shared` is never written out.\n *\n * @returns Named schemas lifted from `__shared` (after `$id` stripping). Route\n *   conversion copies these into the shared harvest bag so ComponentsWriter can\n *   merge them into the document.\n */\nexport const liftZodSharedDefinitions = (\n  schemas: Record<string, unknown>\n): Record<string, OpenAPIV3_1.SchemaObject> => {\n  const harvested: Record<string, OpenAPIV3_1.SchemaObject> = {};\n  const shared = schemas[ZOD_SHARED_BUCKET];\n\n  if (isPlainObject(shared)) {\n    const defs = shared.$defs ?? shared.definitions;\n\n    if (isPlainObject(defs)) {\n      for (const [id, def] of Object.entries(defs)) {\n        if (isPlainObject(def) === false) {\n          continue;\n        }\n\n        const cleaned = stripJsonSchemaId(def) as OpenAPIV3_1.SchemaObject;\n        harvested[id] = cleaned;\n\n        if (schemas[id] === undefined) {\n          schemas[id] = cleaned;\n        }\n      }\n    }\n\n    delete schemas[ZOD_SHARED_BUCKET];\n  }\n\n  const seen = new WeakSet<object>();\n  rewriteZodSharedRefs(schemas, seen);\n  rewriteZodSharedRefs(harvested, seen);\n\n  for (const schema of Object.values(schemas)) {\n    if (isPlainObject(schema)) {\n      stripJsonSchemaId(schema);\n    }\n  }\n\n  return harvested;\n};\n\nexport type ZodToOpenAPIOptions = {\n  /**\n   * Shared harvest bag filled with named schemas lifted from Zod's `__shared`\n   * bucket. Assemblers pass `context.registries.extractedComponentSchemas` so\n   * ComponentsWriter can merge them into `components.schemas`.\n   */\n  extractedComponentSchemas?: Record<string, OpenAPIV3_1.SchemaObject>;\n};\n\n/**\n * Converts a Zod schema to an OpenAPI Schema Object.\n *\n * @description\n * Takes a Zod schema and converts it into an OpenAPI Schema Object (v3.1).\n * It uses a local registry to handle the conversion process and generates the appropriate\n * OpenAPI components. Identified nested schemas that Zod would otherwise park in\n * `__shared` are rewritten to `#/components/schemas/<id>` and copied into\n * `options.extractedComponentSchemas` when that bag is provided.\n *\n * @param zodSchema - The Zod schema to convert to OpenAPI format. Can be any valid Zod schema.\n * @param schemaStore - The application-owned content-API schema store to copy named\n *   component definitions from. Conversion uses a local registry and does not read a\n *   live Zod registry from the store.\n * @param options - Optional harvest bag shared across assemblers and ComponentsWriter.\n *\n * @returns An OpenAPI Schema Object representing the input Zod schema structure.\n * If the conversion cannot be completed, returns undefined.\n *\n * @example\n * ```typescript\n * import * as z from 'zod/v4';\n *\n * // Create a Zod schema\n * const userSchema = z.object({\n *   id: z.number(),\n *   name: z.string(),\n *   email: z.string().email()\n * });\n *\n * // Convert to OpenAPI schema\n * const openAPISchema = zodToOpenAPI(userSchema, strapi.contentAPISchemaRegistry);\n * ```\n */\nexport const zodToOpenAPI = (\n  zodSchema: z.ZodType,\n  schemaStore: Core.ContentAPISchemaRegistry,\n  options?: ZodToOpenAPIOptions\n): OpenAPIV3_1.SchemaObject | OpenAPIV3_1.ReferenceObject => {\n  try {\n    const id = randomUUID();\n    const registry = z.registry<{ id: string }>();\n\n    // Add the schema to the local registry with a custom, unique ID\n    registry.add(zodSchema, { id });\n\n    // Copy Strapi-owned definitions into the local registry so references resolve without\n    // generating \"__shared\" definitions.\n    for (const [key, value] of schemaStore.entries()) {\n      registry.add(value, { id: key });\n    }\n\n    // Generate the schemas and only return the one we want, transform the URI path to be OpenAPI compliant\n    const { schemas } = z.toJSONSchema(registry, {\n      ...OPENAPI_SCHEMA_CONVERSION_OPTIONS,\n      uri: toComponentsPath,\n    });\n\n    const harvested = isPlainObject(schemas) ? liftZodSharedDefinitions(schemas) : {};\n\n    if (options?.extractedComponentSchemas !== undefined) {\n      Object.assign(options.extractedComponentSchemas, harvested);\n    }\n\n    // TODO: make sure it's compliant\n    return stripJsonSchemaId(schemas[id] as OpenAPIV3_1.SchemaObject);\n  } catch {\n    throw new Error(\"Couldn't transform the zod schema into an OpenAPI schema\");\n  }\n};\n"],"names":["OPENAPI_SCHEMA_CONVERSION_OPTIONS","target","io","ZOD_SHARED_BUCKET","ZOD_SHARED_REF_RE","isPlainObject","value","Array","isArray","stripJsonSchemaId","schema","$id","toComponentsPath","id","rewriteZodSharedRef","ref","match","exec","undefined","length","rewriteZodSharedRefs","seen","WeakSet","has","add","item","$ref","nested","Object","values","liftZodSharedDefinitions","schemas","harvested","shared","defs","$defs","definitions","def","entries","cleaned","zodToOpenAPI","zodSchema","schemaStore","options","randomUUID","registry","z","key","toJSONSchema","uri","extractedComponentSchemas","assign","Error"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strapi/openapi",
-  "version": "0.0.0-experimental.6340da17068c3bed7fb006e7bcc554c71129e282",
+  "version": "0.0.0-experimental.63624e21eb5b0713345a0cf2f68f1c40eab427bc",
   "description": "A tool set to help generate and validate API documentation for Strapi projects",
   "homepage": "https://strapi.io",
   "bugs": {
@@ -47,22 +47,26 @@
     "build:types": "run -T tsc -p tsconfig.build.json --emitDeclarationOnly",
     "watch": "run -T rollup -c -w",
     "clean": "run -T rimraf ./dist",
-    "lint": "run -T eslint .",
+    "lint": "run -T eslint . --max-warnings=0",
     "prepublishOnly": "yarn clean && yarn build",
+    "test:ts": "run -T tsc -p tsconfig.json",
     "test:unit": "run -T jest",
     "test:unit:watch": "run -T jest --watch"
   },
   "engines": {
-    "node": ">=20.19.0 <=26.x.x",
+    "node": ">=20.0.0 <=26.x.x",
     "npm": ">=6.0.0"
   },
   "dependencies": {
     "debug": "4.3.4",
     "openapi-types": "12.1.3",
-    "zod": "3.25.67"
+    "zod": "4.4.3"
   },
   "devDependencies": {
-    "@strapi/types": "0.0.0-experimental.6340da17068c3bed7fb006e7bcc554c71129e282",
-    "@types/debug": "^4"
+    "@strapi/types": "0.0.0-experimental.63624e21eb5b0713345a0cf2f68f1c40eab427bc",
+    "@types/debug": "^4",
+    "@types/jest": "29.5.2",
+    "@types/node": "20.19.41",
+    "jest": "29.6.0"
   }
 }