OpenAPI to Zod Validation

Why convert OpenAPI to Zod

OpenAPI documents describe API contracts, while Zod validates data at runtime. Converting OpenAPI to Zod gives TypeScript apps a practical runtime guard at the API boundary, especially when a REST service, partner API, or generated spec owns the source of truth.

Supported OpenAPI schema coverage

FrameworkKit supports the common OpenAPI and Swagger shapes that matter for a first production pass: component objects, required arrays, optional fields, nullable values, string formats, enums, arrays, local $ref references, and simple oneOf/anyOf unions. More complex polymorphic schemas should stay visible in diagnostics and tests.

• Use OpenAPI 3.x `components.schemas` for modern specs.
• Use Swagger 2.0 `definitions` when the source contract is still legacy.
• Review unsupported custom formats before treating generated validators as final.

API response boundary

Validate raw network data before it reaches UI, cache, or service logic. After `safeParse` succeeds, use the parsed value as the trusted TypeScript value.

const result = UserSchema.safeParse(await response.json());

if (!result.success) {
  throw new Error("Unexpected API response");
}

return result.data;

Request body validation

Generated schemas can also guard outgoing request bodies when a frontend or service constructs payloads from user input, form state, or queued jobs.

Typed fetch wrapper recipe

Keep the OpenAPI-generated Zod schema near the client function that owns the endpoint. The wrapper should treat `response.json()` as unknown, parse once, then return the inferred type only after validation succeeds.

async function fetchWithSchema<TSchema extends z.ZodType>(
  url: string,
  schema: TSchema,
): Promise<z.infer<TSchema>> {
  const response = await fetch(url);
  const json: unknown = await response.json();

  return schema.parse(json);
}

Nullable and optional fields

OpenAPI documents often mix `required`, `nullable`, and missing properties. Review generated optional and nullable Zod fields with fixtures from real successful and failed responses because `nullable` controls value shape while `required` controls property presence.

• OpenAPI 3.0 commonly uses `nullable: true`.
• OpenAPI 3.1 can use `type: ["string", "null"]`.
• A field can be required and nullable at the same time.

Local references and component names

Local references such as `#/components/schemas/User` should become reusable schema references instead of duplicated inline objects. Stable component names make generated Zod output easier to review, diff, and test.

export const ProfileSchema = z.object({
  website: z.string().url().nullable().optional(),
});

export const UserSchema = z.object({
  id: z.string(),
  profile: ProfileSchema.optional(),
});

oneOf, anyOf, and discriminator review

Simple unions are useful, but complex oneOf/anyOf schemas can hide overlap between branches. When a spec uses discriminators, add one fixture per branch and verify the generated Zod schema accepts only the intended payloads.

• Prefer discriminated unions when the OpenAPI document exposes a stable type field.
• Avoid replacing hard cases with `z.any()` unless the risk is documented.
• Keep generated diagnostics in PR review so schema gaps are visible.

Production checklist

Treat generated validators as a strong starting point. Add domain refinements, unsupported custom formats, API-version ownership notes, and fixture coverage before relying on the output in CI.

• Add valid and invalid response fixtures.
• Check local `$ref` output for shared component schemas.
• Document the OpenAPI version that owns the contract.
• Compare FrameworkKit with openapi-zod-client, Orval, and Kubb when the team needs a generated client.

OpenAPI to Zod validation map

Use FrameworkKit to generate the starter code, then review the output before shipping it in production.

OpenAPI to Zod resources

FAQ

Related comparisons

Related tools