Zod Schema Generation

Overview

This guide explains how to use the Zod schema generation feature in PEDAL, including supported features, usage examples, and troubleshooting tips.

---

Usage

CLI

To generate Zod schemas from an OpenAPI or AST file:

node scripts/generate-zod.js --input path/to/openapi.yaml --output path/to/zod-schemas.ts

• --input: Path to your OpenAPI YAML/JSON or AST file

• --output: Path to write the generated Zod schemas

API

You can also use the generator programmatically:

import { generateZodSchema } from 'src/pipeline/stages/zod-generator';
import openApiDoc from './openapi.json';

const { schemas } = generateZodSchema({ oas: openApiDoc });
console.log(schemas.User.parse({ ... }));

---

Supported Features

• Type Mapping: string, number, integer, boolean, array, object, enum, union (oneOf/anyOf), intersection (allOf)

• Format Support: uuid, email, uri, date, date-time

• Validation Rules: minLength, maxLength, pattern, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, minItems, maxItems, uniqueItems, minProperties, maxProperties

• References: $ref resolution for local schemas

• Edge Cases: Handles empty schemas, optional-only objects, invalid patterns

---

Limitations

• Circular References: Not fully supported; will throw or skip

• Polymorphism: Discriminators and advanced polymorphic constructs are not supported

• External $ref: Only local references are supported

• Custom Zod Refinements: Only standard OpenAPI validation rules are mapped

---

Example

OpenAPI Input:

User:
  type: object
  properties:
    id:
      type: string
      format: uuid
    email:
      type: string
      format: email
    age:
      type: integer
      minimum: 0
  required: [id, email]

Generated Zod Schema:

export const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  age: z.number().int().gte(0).optional()
});
export type User = z.infer<typeof UserSchema>;

---

FAQ

Q: How do I add custom validation? A: Extend the generated schema with .refine() in your own code.

Q: What if my OpenAPI uses unsupported features? A: The generator will skip or throw for unsupported constructs. See limitations above.

Q: How do I run tests? A: See src/pipeline/stages/__tests__/README.md for test instructions.

Q: How do I contribute? A: See CONTRIBUTING.md for guidelines.

---

Schema Patterns & Best Practices

Common Schema Patterns

Basic Types

Simple:
  type: object
  properties:
    name: { type: string }
    age: { type: integer }
    isActive: { type: boolean }

z.object({
  name: z.string(),
  age: z.number().int(),
  isActive: z.boolean()
})

Validation Rules

Validated:
  type: object
  properties:
    username: { type: string, minLength: 3, maxLength: 20, pattern: '^[a-zA-Z0-9_]+$' }
    score: { type: number, minimum: 0, maximum: 100, multipleOf: 0.5 }

z.object({
  username: z.string().min(3).max(20).regex(/^[a-zA-Z0-9_]+$/),
  score: z.number().gte(0).lte(100).refine(v => v % 0.5 === 0)
})

Required vs. Optional

User:
  type: object
  properties:
    id: { type: string }
    email: { type: string }
    age: { type: integer }
  required: [id, email]

z.object({
  id: z.string(),
  email: z.string(),
  age: z.number().int().optional()
})

Enums, Unions, Intersections

Status:
  enum: [active, inactive, pending]
Response:
  oneOf:
    - type: string
    - type: number
Manager:
  allOf:
    - $ref: '#/components/schemas/Person'
    - $ref: '#/components/schemas/Employee'

z.enum(['active', 'inactive', 'pending'])
z.union([z.string(), z.number()])
z.intersection(PersonSchema, EmployeeSchema)

Not/Inverse Validation

NonEmptyString:
  type: string
  not:
    type: string
    maxLength: 0

z.string().refine(val => val.length > 0, { message: 'Must not be empty' })

Advanced & Real-World Patterns

Nested Objects & Arrays

Order:
  type: object
  properties:
    items:
      type: array
      items:
        type: object
        properties:
          sku: { type: string }
          qty: { type: integer, minimum: 1 }
      minItems: 1

z.object({
  items: z.array(z.object({
    sku: z.string(),
    qty: z.number().int().gte(1)
  })).min(1)
})

Cross-Referenced Schemas

UserProfile:
  type: object
  properties:
    user: { $ref: '#/components/schemas/User' }
    preferences:
      type: object
      properties:
        theme: { type: string, enum: [light, dark] }
        notifications: { type: boolean }

Format-Specific Strings

Email:
  type: string
  format: email

z.string().email()

Best Practices

• Prefer explicit required/optional fields for clarity.

• Use OpenAPI validation keywords to maximize Zod's static validation.

• For custom logic, extend generated schemas with .refine() in your codebase.

• Avoid circular references and unsupported polymorphism.

• Keep schemas modular and reusable.

Usage Examples

• See the test suite for real-world and edge-case examples.

• Use generated Zod schemas for API validation, form validation, and data transformation.