Zod vs JSON Schema

Zod vs JSON Schema comparison table

Code example: same User schema

import { z } from "zod";

export const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  role: z.enum(["admin", "editor", "viewer"]),
  profile: z
    .object({
      website: z.string().url().nullable(),
    })
    .optional(),
});

export type User = z.infer<typeof UserSchema>;

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email", "role"],
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "email": { "type": "string", "format": "email" },
    "role": {
      "type": "string",
      "enum": ["admin", "editor", "viewer"]
    },
    "profile": {
      "type": "object",
      "properties": {
        "website": { "type": ["string", "null"], "format": "uri" }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Looking to convert Zod to JSON Schema?

Use the FrameworkKit converter when your intent is conversion rather than comparison. This page explains the tradeoffs between Zod and JSON Schema; the converter is the canonical workflow for turning supported Zod schemas into portable schema output.

When to use Zod

Use Zod when validation lives close to TypeScript code and developers need a schema that feels like normal application code.

• Validate API responses before data reaches UI or business logic.
• Validate form payloads on the client, server, or both.
• Infer TypeScript types directly from runtime schemas with `z.infer`.
• Model app-specific rules that are easier to express as TypeScript validation code.

When to use JSON Schema

Use JSON Schema when the schema is a contract that must be consumed outside one TypeScript codebase.

• Publish validation rules for services written in multiple languages.
• Compile validators with AJV or another JSON Schema validator.
• Feed API documentation, gateways, SDK generation, or schema registries.
• Keep the contract independent from app-specific TypeScript logic.

Can you use both?

Yes. Many teams keep Zod as the TypeScript source of truth for app validation, then publish supported schemas as JSON Schema for OpenAPI, AJV, or external consumers. The important rule is to choose one source of truth and review conversions where executable Zod behavior cannot be represented as plain schema data.

Zod to JSON Schema workflow

When Zod already exists in the codebase, convert it to JSON Schema for documentation, contract publishing, gateway validation, or AJV. Use Draft 2020-12 for modern JSON Schema, Draft 7 for older validators, and OpenAPI 3.0 output when your API spec expects that shape.

JSON Schema to Zod workflow

When JSON Schema or OpenAPI is the source of truth, generate Zod validators for TypeScript consumers. This is useful when a frontend or Node service needs runtime validation but the contract is owned by an API spec.

OpenAPI, AJV, TypeScript, and runtime validation

AJV validates JSON Schema at runtime. OpenAPI uses schema objects for API contracts. TypeScript checks code at compile time but disappears at runtime. Zod sits in the runtime validation layer for TypeScript apps, while JSON Schema sits in the portable contract layer. The best choice depends on which layer owns the truth.

Decision path

Start with JSON to Zod Converter when you need a browser-first workflow with copy-ready TypeScript output. Choose JSON Schema when its tradeoffs match your team better.

FAQ

Related tools