zod-openapi 3.1.1 → 3.3.0

package/README.md

@@ -276,6 +276,7 @@ const { schema, components } = createSchema(job, {
   schemaType: 'input'; // This controls whether this should be rendered as a request (`input`) or response (`output`). Defaults to `output`
   openapi: '3.0.0'; // OpenAPI version to use, defaults to `'3.1.0'`
   components: { jobId: z.string() } // Additional components to use and create while rendering the schema
+  componentRefPath: '#/definitions/' // Defaults to #/components/schemas/
 })
 ```
 
@@ -468,7 +469,7 @@ createDocument({
 
 ##### Zod Effects
 
-`.transform()`, `.default()` and `.pipe()` are complicated because they technically comprise of two types (input & output). This means that we need to understand which type you are creating. In particular with transform it is very difficult to infer the output type. This library will automatically select which _type_ to use by checking how the schema is used based on the following rules:
+`.transform()`, `.catch()`, `.default()` and `.pipe()` are complicated because they technically comprise of two types (input & output). This means that we need to understand which type you are creating. In particular with transform it is very difficult to infer the output type. This library will automatically select which _type_ to use by checking how the schema is used based on the following rules:
 
 _Input_: Request Bodies, Request Parameters, Headers
 
@@ -693,6 +694,8 @@ For example in `z.string().nullable()` will be rendered differently
 - ZodBoolean
 - ZodBranded
 - ZodCatch
+  - Treated as ZodDefault
+- ZodCustom
 - ZodDate
   - `type` is mapped as `string` by default
 - ZodDefault

package/dist/components.chunk.cjs

@@ -55,7 +55,18 @@ const createBooleanSchema = (_zodBoolean) => ({
   }
 });
 const createBrandedSchema = (zodBranded, state) => createSchemaObject(zodBranded._def.type, state, ["brand"]);
-const createCatchSchema = (zodCatch, state) => createSchemaObject(zodCatch._def.innerType, state, ["catch"]);
+const createCatchSchema = (zodCatch, state) => {
+  const schemaObject = createSchemaObject(zodCatch._def.innerType, state, [
+    "default"
+  ]);
+  const catchResult = zodCatch.safeParse(void 0);
+  const maybeDefaultValue = catchResult.success ? {
+    default: catchResult.data
+  } : void 0;
+  return enhanceWithMetadata(schemaObject, {
+    ...maybeDefaultValue
+  });
+};
 const createDateSchema = (_zodDate, state) => {
   var _a;
   return {
@@ -565,74 +576,7 @@ const getZodNumberChecks = (zodNumber) => zodNumber._def.checks.reduce((acc, che
 }, {});
 const mapNumberType = (zodNumberChecks) => zodNumberChecks.int ? "integer" : "number";
 const createOptionalSchema = (zodOptional, state) => createSchemaObject(zodOptional.unwrap(), state, ["optional"]);
-const isOptionalSchema = (zodSchema, state) => {
-  var _a, _b, _c;
-  if (isZodType(zodSchema, "ZodOptional") || isZodType(zodSchema, "ZodNever") || isZodType(zodSchema, "ZodUndefined") || isZodType(zodSchema, "ZodLiteral") && zodSchema._def.value === void 0) {
-    return { optional: true };
-  }
-  if (isZodType(zodSchema, "ZodDefault")) {
-    if (((_a = zodSchema._def.openapi) == null ? void 0 : _a.effectType) === "input") {
-      return { optional: true };
-    }
-    if (((_b = zodSchema._def.openapi) == null ? void 0 : _b.effectType) === "output") {
-      return { optional: false };
-    }
-    return {
-      optional: state.type === "input",
-      effects: [
-        {
-          type: "schema",
-          creationType: state.type,
-          zodType: zodSchema,
-          path: [...state.path]
-        }
-      ]
-    };
-  }
-  if (isZodType(zodSchema, "ZodNullable") || isZodType(zodSchema, "ZodCatch")) {
-    return isOptionalSchema(zodSchema._def.innerType, state);
-  }
-  if (isZodType(zodSchema, "ZodEffects")) {
-    return isOptionalSchema(zodSchema._def.schema, state);
-  }
-  if (isZodType(zodSchema, "ZodUnion") || isZodType(zodSchema, "ZodDiscriminatedUnion")) {
-    const results = zodSchema._def.options.map(
-      (schema) => isOptionalSchema(schema, state)
-    );
-    return results.reduce(
-      (acc, result) => ({
-        optional: acc.optional || result.optional,
-        effects: flattenEffects([acc.effects, result.effects])
-      }),
-      { optional: false }
-    );
-  }
-  if (isZodType(zodSchema, "ZodIntersection")) {
-    const results = [zodSchema._def.left, zodSchema._def.right].map(
-      (schema) => isOptionalSchema(schema, state)
-    );
-    return results.reduce(
-      (acc, result) => ({
-        optional: acc.optional || result.optional,
-        effects: flattenEffects([acc.effects, result.effects])
-      }),
-      { optional: false }
-    );
-  }
-  if (isZodType(zodSchema, "ZodPipeline")) {
-    const type = ((_c = zodSchema._def.openapi) == null ? void 0 : _c.effectType) ?? state.type;
-    if (type === "input") {
-      return isOptionalSchema(zodSchema._def.in, state);
-    }
-    if (type === "output") {
-      return isOptionalSchema(zodSchema._def.out, state);
-    }
-  }
-  if (isZodType(zodSchema, "ZodLazy")) {
-    return isOptionalSchema(zodSchema._def.getter(), state);
-  }
-  return { optional: zodSchema.isOptional() };
-};
+const isOptionalObjectKey = (zodSchema) => isZodType(zodSchema, "ZodNever") || isZodType(zodSchema, "ZodUndefined") || isZodType(zodSchema, "ZodLiteral") && zodSchema._def.value === void 0;
 const createObjectSchema = (zodObject, state) => {
   var _a;
   const extendedSchema = createExtendedSchema(
@@ -653,7 +597,7 @@ const createObjectSchema = (zodObject, state) => {
   );
 };
 const createExtendedSchema = (zodObject, baseZodObject, state) => {
-  var _a;
+  var _a, _b;
   if (!baseZodObject) {
     return void 0;
   }
@@ -693,7 +637,14 @@ const createExtendedSchema = (zodObject, baseZodObject, state) => {
   return {
     type: "schema",
     schema: {
-      allOf: [{ $ref: createComponentSchemaRef(completeComponent.ref) }],
+      allOf: [
+        {
+          $ref: createComponentSchemaRef(
+            completeComponent.ref,
+            (_b = state.documentOptions) == null ? void 0 : _b.componentRefPath
+          )
+        }
+      ],
       ...extendedSchema.schema
     },
     effects: flattenEffects([
@@ -735,7 +686,7 @@ const createShapeDiff = (baseObj, extendedObj) => {
 };
 const createObjectSchemaFromShape = (shape, { unknownKeys, catchAll }, state) => {
   const properties = mapProperties(shape, state);
-  const required = mapRequired(shape, state);
+  const required = mapRequired(properties, shape, state);
   const additionalProperties = !isZodType(catchAll, "ZodNever") ? createSchemaObject(catchAll, state, ["additional properties"]) : void 0;
   return {
     type: "schema",
@@ -755,17 +706,38 @@ const createObjectSchemaFromShape = (shape, { unknownKeys, catchAll }, state) =>
     ])
   };
 };
-const mapRequired = (shape, state) => {
-  const { required, effects: allEffects } = Object.entries(shape).reduce(
-    (acc, [key, zodSchema]) => {
-      state.path.push(`property: ${key}`);
-      const { optional, effects } = isOptionalSchema(zodSchema, state);
-      state.path.pop();
-      if (!optional) {
+const mapRequired = (properties, shape, state) => {
+  if (!properties) {
+    return void 0;
+  }
+  const { required, effects } = Object.entries(properties.schemas).reduce(
+    (acc, [key, schemaOrRef]) => {
+      const zodSchema = shape[key];
+      if (!zodSchema) {
+        throw new Error("Property somehow doesn't exist in shape");
+      }
+      const result = zodSchema.safeParse(void 0);
+      if (!result.success) {
         acc.required.push(key);
+        return acc;
       }
-      if (effects) {
-        acc.effects.push(effects);
+      if (result.data !== void 0) {
+        const baseEffect = {
+          zodType: zodSchema,
+          path: [...state.path, `property: ${key}`]
+        };
+        const effect = schemaOrRef.type === "ref" ? {
+          ...baseEffect,
+          type: "component"
+        } : {
+          ...baseEffect,
+          type: "schema",
+          creationType: state.type
+        };
+        acc.effects.push(effect);
+        if (state.type === "output") {
+          acc.required.push(key);
+        }
       }
       return acc;
     },
@@ -774,7 +746,7 @@ const mapRequired = (shape, state) => {
       effects: []
     }
   );
-  return { required, effects: flattenEffects(allEffects) };
+  return { required, effects };
 };
 const mapProperties = (shape, state) => {
   const shapeEntries = Object.entries(shape);
@@ -783,17 +755,17 @@ const mapProperties = (shape, state) => {
   }
   return shapeEntries.reduce(
     (acc, [key, zodSchema]) => {
-      if (isZodType(zodSchema, "ZodNever") || isZodType(zodSchema, "ZodUndefined")) {
+      if (isOptionalObjectKey(zodSchema)) {
         return acc;
       }
-      const property = createSchemaObject(zodSchema, state, [
-        `property: ${key}`
-      ]);
-      acc.properties[key] = property.schema;
-      acc.effects.push(property.effects);
+      const schema = createSchemaObject(zodSchema, state, [`property: ${key}`]);
+      acc.schemas[key] = schema;
+      acc.properties[key] = schema.schema;
+      acc.effects.push(schema.effects);
       return acc;
     },
     {
+      schemas: {},
       properties: {},
       effects: []
     }
@@ -1134,9 +1106,12 @@ const mapPrefixItems = (items, state) => {
 };
 const createUnionSchema = (zodUnion, state) => {
   var _a, _b;
-  const schemas = zodUnion.options.map(
-    (option, index) => createSchemaObject(option, state, [`union option ${index}`])
-  );
+  const schemas = zodUnion.options.reduce((acc, option, index) => {
+    if (!isOptionalObjectKey(option)) {
+      acc.push(createSchemaObject(option, state, [`union option ${index}`]));
+    }
+    return acc;
+  }, []);
   if (((_a = zodUnion._def.openapi) == null ? void 0 : _a.unionOneOf) ?? ((_b = state.documentOptions) == null ? void 0 : _b.unionOneOf)) {
     return {
       type: "schema",
@@ -1281,6 +1256,7 @@ const createNewSchema = (zodSchema, state) => {
   return schemaWithMetadata;
 };
 const createNewRef = (ref, zodSchema, state) => {
+  var _a;
   state.components.schemas.set(zodSchema, {
     type: "in-progress",
     ref
@@ -1297,7 +1273,12 @@ const createNewRef = (ref, zodSchema, state) => {
   });
   return {
     type: "ref",
-    schema: { $ref: createComponentSchemaRef(ref) },
+    schema: {
+      $ref: createComponentSchemaRef(
+        ref,
+        (_a = state.documentOptions) == null ? void 0 : _a.componentRefPath
+      )
+    },
     effects: newSchema.effects ? [
       {
         type: "component",
@@ -1309,10 +1290,16 @@ const createNewRef = (ref, zodSchema, state) => {
   };
 };
 const createExistingRef = (zodSchema, component, state) => {
+  var _a, _b;
   if (component && component.type === "complete") {
     return {
       type: "ref",
-      schema: { $ref: createComponentSchemaRef(component.ref) },
+      schema: {
+        $ref: createComponentSchemaRef(
+          component.ref,
+          (_a = state.documentOptions) == null ? void 0 : _a.componentRefPath
+        )
+      },
       effects: component.effects ? [
         {
           type: "component",
@@ -1326,7 +1313,12 @@ const createExistingRef = (zodSchema, component, state) => {
   if (component && component.type === "in-progress") {
     return {
       type: "ref",
-      schema: { $ref: createComponentSchemaRef(component.ref) },
+      schema: {
+        $ref: createComponentSchemaRef(
+          component.ref,
+          (_b = state.documentOptions) == null ? void 0 : _b.componentRefPath
+        )
+      },
       effects: [
         {
           type: "component",
@@ -1417,7 +1409,7 @@ const createContent = (contentObject, components, type, subpath, documentOptions
 );
 const createComponentParamRef = (ref) => `#/components/parameters/${ref}`;
 const createBaseParameter = (schema, components, subpath, documentOptions) => {
-  var _a, _b, _c;
+  var _a, _b;
   const { ref, ...rest } = ((_a = schema._def.openapi) == null ? void 0 : _a.param) ?? {};
   const state = {
     components,
@@ -1427,8 +1419,8 @@ const createBaseParameter = (schema, components, subpath, documentOptions) => {
     documentOptions
   };
   const schemaObject = createSchema(schema, state, [...subpath, "schema"]);
-  const required = !((_b = isOptionalSchema(schema, state)) == null ? void 0 : _b.optional);
-  const description = ((_c = schema._def.openapi) == null ? void 0 : _c.description) ?? schema._def.description;
+  const required = !schema.isOptional();
+  const description = ((_b = schema._def.openapi) == null ? void 0 : _b.description) ?? schema._def.description;
   return {
     ...description && { description },
     ...rest,
@@ -1625,7 +1617,7 @@ const createHeaderOrRef = (schema, components, documentOptions) => {
   return baseHeader;
 };
 const createBaseHeader = (schema, components, documentOptions) => {
-  var _a, _b;
+  var _a;
   const { ref, ...rest } = ((_a = schema._def.openapi) == null ? void 0 : _a.header) ?? {};
   const state = {
     components,
@@ -1635,7 +1627,8 @@ const createBaseHeader = (schema, components, documentOptions) => {
     documentOptions
   };
   const schemaObject = createSchema(schema, state, ["header"]);
-  const required = !((_b = isOptionalSchema(schema, state)) == null ? void 0 : _b.optional);
+  const optionalResult = schema.safeParse(void 0);
+  const required = !optionalResult.success || optionalResult !== void 0;
   return {
     ...rest,
     ...schema && { schema: schemaObject },
@@ -1998,7 +1991,7 @@ const getCallbacks = (callbacks, components) => {
     });
   });
 };
-const createComponentSchemaRef = (schemaRef) => `#/components/schemas/${schemaRef}`;
+const createComponentSchemaRef = (schemaRef, componentPath) => `${componentPath ?? "#/components/schemas/"}${schemaRef}`;
 const createComponentResponseRef = (responseRef) => `#/components/responses/${responseRef}`;
 const createComponentRequestBodyRef = (requestBodyRef) => `#/components/requestBodies/${requestBodyRef}`;
 const createComponentCallbackRef = (callbackRef) => `#/components/callbacks/${callbackRef}`;

package/dist/components.chunk.mjs

@@ -54,7 +54,18 @@ const createBooleanSchema = (_zodBoolean) => ({
   }
 });
 const createBrandedSchema = (zodBranded, state) => createSchemaObject(zodBranded._def.type, state, ["brand"]);
-const createCatchSchema = (zodCatch, state) => createSchemaObject(zodCatch._def.innerType, state, ["catch"]);
+const createCatchSchema = (zodCatch, state) => {
+  const schemaObject = createSchemaObject(zodCatch._def.innerType, state, [
+    "default"
+  ]);
+  const catchResult = zodCatch.safeParse(void 0);
+  const maybeDefaultValue = catchResult.success ? {
+    default: catchResult.data
+  } : void 0;
+  return enhanceWithMetadata(schemaObject, {
+    ...maybeDefaultValue
+  });
+};
 const createDateSchema = (_zodDate, state) => {
   var _a;
   return {
@@ -564,74 +575,7 @@ const getZodNumberChecks = (zodNumber) => zodNumber._def.checks.reduce((acc, che
 }, {});
 const mapNumberType = (zodNumberChecks) => zodNumberChecks.int ? "integer" : "number";
 const createOptionalSchema = (zodOptional, state) => createSchemaObject(zodOptional.unwrap(), state, ["optional"]);
-const isOptionalSchema = (zodSchema, state) => {
-  var _a, _b, _c;
-  if (isZodType(zodSchema, "ZodOptional") || isZodType(zodSchema, "ZodNever") || isZodType(zodSchema, "ZodUndefined") || isZodType(zodSchema, "ZodLiteral") && zodSchema._def.value === void 0) {
-    return { optional: true };
-  }
-  if (isZodType(zodSchema, "ZodDefault")) {
-    if (((_a = zodSchema._def.openapi) == null ? void 0 : _a.effectType) === "input") {
-      return { optional: true };
-    }
-    if (((_b = zodSchema._def.openapi) == null ? void 0 : _b.effectType) === "output") {
-      return { optional: false };
-    }
-    return {
-      optional: state.type === "input",
-      effects: [
-        {
-          type: "schema",
-          creationType: state.type,
-          zodType: zodSchema,
-          path: [...state.path]
-        }
-      ]
-    };
-  }
-  if (isZodType(zodSchema, "ZodNullable") || isZodType(zodSchema, "ZodCatch")) {
-    return isOptionalSchema(zodSchema._def.innerType, state);
-  }
-  if (isZodType(zodSchema, "ZodEffects")) {
-    return isOptionalSchema(zodSchema._def.schema, state);
-  }
-  if (isZodType(zodSchema, "ZodUnion") || isZodType(zodSchema, "ZodDiscriminatedUnion")) {
-    const results = zodSchema._def.options.map(
-      (schema) => isOptionalSchema(schema, state)
-    );
-    return results.reduce(
-      (acc, result) => ({
-        optional: acc.optional || result.optional,
-        effects: flattenEffects([acc.effects, result.effects])
-      }),
-      { optional: false }
-    );
-  }
-  if (isZodType(zodSchema, "ZodIntersection")) {
-    const results = [zodSchema._def.left, zodSchema._def.right].map(
-      (schema) => isOptionalSchema(schema, state)
-    );
-    return results.reduce(
-      (acc, result) => ({
-        optional: acc.optional || result.optional,
-        effects: flattenEffects([acc.effects, result.effects])
-      }),
-      { optional: false }
-    );
-  }
-  if (isZodType(zodSchema, "ZodPipeline")) {
-    const type = ((_c = zodSchema._def.openapi) == null ? void 0 : _c.effectType) ?? state.type;
-    if (type === "input") {
-      return isOptionalSchema(zodSchema._def.in, state);
-    }
-    if (type === "output") {
-      return isOptionalSchema(zodSchema._def.out, state);
-    }
-  }
-  if (isZodType(zodSchema, "ZodLazy")) {
-    return isOptionalSchema(zodSchema._def.getter(), state);
-  }
-  return { optional: zodSchema.isOptional() };
-};
+const isOptionalObjectKey = (zodSchema) => isZodType(zodSchema, "ZodNever") || isZodType(zodSchema, "ZodUndefined") || isZodType(zodSchema, "ZodLiteral") && zodSchema._def.value === void 0;
 const createObjectSchema = (zodObject, state) => {
   var _a;
   const extendedSchema = createExtendedSchema(
@@ -652,7 +596,7 @@ const createObjectSchema = (zodObject, state) => {
   );
 };
 const createExtendedSchema = (zodObject, baseZodObject, state) => {
-  var _a;
+  var _a, _b;
   if (!baseZodObject) {
     return void 0;
   }
@@ -692,7 +636,14 @@ const createExtendedSchema = (zodObject, baseZodObject, state) => {
   return {
     type: "schema",
     schema: {
-      allOf: [{ $ref: createComponentSchemaRef(completeComponent.ref) }],
+      allOf: [
+        {
+          $ref: createComponentSchemaRef(
+            completeComponent.ref,
+            (_b = state.documentOptions) == null ? void 0 : _b.componentRefPath
+          )
+        }
+      ],
       ...extendedSchema.schema
     },
     effects: flattenEffects([
@@ -734,7 +685,7 @@ const createShapeDiff = (baseObj, extendedObj) => {
 };
 const createObjectSchemaFromShape = (shape, { unknownKeys, catchAll }, state) => {
   const properties = mapProperties(shape, state);
-  const required = mapRequired(shape, state);
+  const required = mapRequired(properties, shape, state);
   const additionalProperties = !isZodType(catchAll, "ZodNever") ? createSchemaObject(catchAll, state, ["additional properties"]) : void 0;
   return {
     type: "schema",
@@ -754,17 +705,38 @@ const createObjectSchemaFromShape = (shape, { unknownKeys, catchAll }, state) =>
     ])
   };
 };
-const mapRequired = (shape, state) => {
-  const { required, effects: allEffects } = Object.entries(shape).reduce(
-    (acc, [key, zodSchema]) => {
-      state.path.push(`property: ${key}`);
-      const { optional, effects } = isOptionalSchema(zodSchema, state);
-      state.path.pop();
-      if (!optional) {
+const mapRequired = (properties, shape, state) => {
+  if (!properties) {
+    return void 0;
+  }
+  const { required, effects } = Object.entries(properties.schemas).reduce(
+    (acc, [key, schemaOrRef]) => {
+      const zodSchema = shape[key];
+      if (!zodSchema) {
+        throw new Error("Property somehow doesn't exist in shape");
+      }
+      const result = zodSchema.safeParse(void 0);
+      if (!result.success) {
         acc.required.push(key);
+        return acc;
       }
-      if (effects) {
-        acc.effects.push(effects);
+      if (result.data !== void 0) {
+        const baseEffect = {
+          zodType: zodSchema,
+          path: [...state.path, `property: ${key}`]
+        };
+        const effect = schemaOrRef.type === "ref" ? {
+          ...baseEffect,
+          type: "component"
+        } : {
+          ...baseEffect,
+          type: "schema",
+          creationType: state.type
+        };
+        acc.effects.push(effect);
+        if (state.type === "output") {
+          acc.required.push(key);
+        }
       }
       return acc;
     },
@@ -773,7 +745,7 @@ const mapRequired = (shape, state) => {
       effects: []
     }
   );
-  return { required, effects: flattenEffects(allEffects) };
+  return { required, effects };
 };
 const mapProperties = (shape, state) => {
   const shapeEntries = Object.entries(shape);
@@ -782,17 +754,17 @@ const mapProperties = (shape, state) => {
   }
   return shapeEntries.reduce(
     (acc, [key, zodSchema]) => {
-      if (isZodType(zodSchema, "ZodNever") || isZodType(zodSchema, "ZodUndefined")) {
+      if (isOptionalObjectKey(zodSchema)) {
         return acc;
       }
-      const property = createSchemaObject(zodSchema, state, [
-        `property: ${key}`
-      ]);
-      acc.properties[key] = property.schema;
-      acc.effects.push(property.effects);
+      const schema = createSchemaObject(zodSchema, state, [`property: ${key}`]);
+      acc.schemas[key] = schema;
+      acc.properties[key] = schema.schema;
+      acc.effects.push(schema.effects);
       return acc;
     },
     {
+      schemas: {},
       properties: {},
       effects: []
     }
@@ -1133,9 +1105,12 @@ const mapPrefixItems = (items, state) => {
 };
 const createUnionSchema = (zodUnion, state) => {
   var _a, _b;
-  const schemas = zodUnion.options.map(
-    (option, index) => createSchemaObject(option, state, [`union option ${index}`])
-  );
+  const schemas = zodUnion.options.reduce((acc, option, index) => {
+    if (!isOptionalObjectKey(option)) {
+      acc.push(createSchemaObject(option, state, [`union option ${index}`]));
+    }
+    return acc;
+  }, []);
   if (((_a = zodUnion._def.openapi) == null ? void 0 : _a.unionOneOf) ?? ((_b = state.documentOptions) == null ? void 0 : _b.unionOneOf)) {
     return {
       type: "schema",
@@ -1280,6 +1255,7 @@ const createNewSchema = (zodSchema, state) => {
   return schemaWithMetadata;
 };
 const createNewRef = (ref, zodSchema, state) => {
+  var _a;
   state.components.schemas.set(zodSchema, {
     type: "in-progress",
     ref
@@ -1296,7 +1272,12 @@ const createNewRef = (ref, zodSchema, state) => {
   });
   return {
     type: "ref",
-    schema: { $ref: createComponentSchemaRef(ref) },
+    schema: {
+      $ref: createComponentSchemaRef(
+        ref,
+        (_a = state.documentOptions) == null ? void 0 : _a.componentRefPath
+      )
+    },
     effects: newSchema.effects ? [
       {
         type: "component",
@@ -1308,10 +1289,16 @@ const createNewRef = (ref, zodSchema, state) => {
   };
 };
 const createExistingRef = (zodSchema, component, state) => {
+  var _a, _b;
   if (component && component.type === "complete") {
     return {
       type: "ref",
-      schema: { $ref: createComponentSchemaRef(component.ref) },
+      schema: {
+        $ref: createComponentSchemaRef(
+          component.ref,
+          (_a = state.documentOptions) == null ? void 0 : _a.componentRefPath
+        )
+      },
       effects: component.effects ? [
         {
           type: "component",
@@ -1325,7 +1312,12 @@ const createExistingRef = (zodSchema, component, state) => {
   if (component && component.type === "in-progress") {
     return {
       type: "ref",
-      schema: { $ref: createComponentSchemaRef(component.ref) },
+      schema: {
+        $ref: createComponentSchemaRef(
+          component.ref,
+          (_b = state.documentOptions) == null ? void 0 : _b.componentRefPath
+        )
+      },
       effects: [
         {
           type: "component",
@@ -1416,7 +1408,7 @@ const createContent = (contentObject, components, type, subpath, documentOptions
 );
 const createComponentParamRef = (ref) => `#/components/parameters/${ref}`;
 const createBaseParameter = (schema, components, subpath, documentOptions) => {
-  var _a, _b, _c;
+  var _a, _b;
   const { ref, ...rest } = ((_a = schema._def.openapi) == null ? void 0 : _a.param) ?? {};
   const state = {
     components,
@@ -1426,8 +1418,8 @@ const createBaseParameter = (schema, components, subpath, documentOptions) => {
     documentOptions
   };
   const schemaObject = createSchema(schema, state, [...subpath, "schema"]);
-  const required = !((_b = isOptionalSchema(schema, state)) == null ? void 0 : _b.optional);
-  const description = ((_c = schema._def.openapi) == null ? void 0 : _c.description) ?? schema._def.description;
+  const required = !schema.isOptional();
+  const description = ((_b = schema._def.openapi) == null ? void 0 : _b.description) ?? schema._def.description;
   return {
     ...description && { description },
     ...rest,
@@ -1624,7 +1616,7 @@ const createHeaderOrRef = (schema, components, documentOptions) => {
   return baseHeader;
 };
 const createBaseHeader = (schema, components, documentOptions) => {
-  var _a, _b;
+  var _a;
   const { ref, ...rest } = ((_a = schema._def.openapi) == null ? void 0 : _a.header) ?? {};
   const state = {
     components,
@@ -1634,7 +1626,8 @@ const createBaseHeader = (schema, components, documentOptions) => {
     documentOptions
   };
   const schemaObject = createSchema(schema, state, ["header"]);
-  const required = !((_b = isOptionalSchema(schema, state)) == null ? void 0 : _b.optional);
+  const optionalResult = schema.safeParse(void 0);
+  const required = !optionalResult.success || optionalResult !== void 0;
   return {
     ...rest,
     ...schema && { schema: schemaObject },
@@ -1997,7 +1990,7 @@ const getCallbacks = (callbacks, components) => {
     });
   });
 };
-const createComponentSchemaRef = (schemaRef) => `#/components/schemas/${schemaRef}`;
+const createComponentSchemaRef = (schemaRef, componentPath) => `${componentPath ?? "#/components/schemas/"}${schemaRef}`;
 const createComponentResponseRef = (responseRef) => `#/components/responses/${responseRef}`;
 const createComponentRequestBodyRef = (requestBodyRef) => `#/components/requestBodies/${requestBodyRef}`;
 const createComponentCallbackRef = (callbackRef) => `#/components/callbacks/${callbackRef}`;

package/dist/create/schema/single.d.ts

@@ -22,6 +22,10 @@ interface CreateSchemaOptions extends CreateDocumentOptions {
      * Additional components to use and create while rendering the schema
      */
     components?: Record<string, ZodType>;
+    /**
+     * The $ref path to use for the component. Defaults to `#/components/schemas/`
+     */
+    componentRefPath?: string;
 }
 declare const createSchema: (zodType: ZodType, opts?: CreateSchemaOptions) => SchemaResult;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod-openapi",
-  "version": "3.1.1",
+  "version": "3.3.0",
   "description": "Convert Zod Schemas to OpenAPI v3.x documentation",
   "keywords": [
     "typescript",
@@ -74,12 +74,12 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "0.16.4",
     "@crackle/cli": "0.15.5",
-    "@redocly/cli": "1.25.5",
+    "@redocly/cli": "1.25.9",
     "@types/node": "^20.3.0",
     "eslint-plugin-zod-openapi": "^1.0.0-beta.0",
     "openapi3-ts": "4.4.0",
-    "skuba": "9.0.1",
-    "yaml": "2.5.1",
+    "skuba": "9.1.0",
+    "yaml": "2.6.0",
     "zod": "3.23.8"
   },
   "peerDependencies": {