Zodv3

About

Zod is a TypeScript-first schema validation library with static type inference.

The Zod plugin for Hey API generates schemas from your OpenAPI spec, fully compatible with validators, transformers, and all core features.

Features

• Zod v3 support
• seamless integration with @hey-api/openapi-ts ecosystem
• Zod schemas for requests, responses, and reusable definitions
• minimal learning curve thanks to extending the underlying technology

Installation

In your configuration, add zod to your plugins and you’ll be ready to generate Zod artifacts. 🎉

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'zod',
      compatibilityVersion: 3,
    },
  ],
};

SDKs

To add data validators to your SDKs, set sdk.validator to true.

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'zod',
      compatibilityVersion: 3,
    },
    {
      name: '@hey-api/sdk',
      validator: true,
    },
  ],
};

Learn more about data validators in your SDKs on the SDKs page.

Output

The Zod plugin will generate the following artifacts, depending on the input specification.

Requests

A Zod schema is generated for every request layer of each endpoint.

example

zod.gen.ts

const zDeletePetHeaders = z.object({
  api_key: z.string().optional(),
});

const zDeletePetPath = z.object({
  petId: z.number(),
});

const zDeletePetQuery = z.object({
  additionalMetadata: z.string(),
});

config

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'zod',
      compatibilityVersion: 3,
      requests: true,
    },
  ],
};

You can customize the naming and casing pattern for requests schemas using the .name and .case options.

Responses

A single Zod schema is generated for all endpoint’s responses. If the endpoint describes multiple responses, the generated schema is a union of all possible response shapes.

example

zod.gen.ts

const zResponse = z.union([
  z.object({
    foo: z.string().optional(),
  }),
  z.object({
    bar: z.number().optional(),
  }),
]);

config

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'zod',
      compatibilityVersion: 3,
      responses: true,
    },
  ],
};

You can customize the naming and casing pattern for responses schemas using the .name and .case options.

Definitions

A Zod schema is generated for every reusable definition from your input.

example

zod.gen.ts

const zFoo = z.number().int();

const zBar = z.object({
  bar: z.array(z.number().int()).optional(),
});

config

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'zod',
      compatibilityVersion: 3,
      definitions: true,
    },
  ],
};

You can customize the naming and casing pattern for definitions schemas using the .name and .case options.

ISO Datetimes

By default, values without a timezone or with a timezone offset are not allowed in the z.string().datetime() method.

Timezone offsets

You can allow values with timezone offsets by setting dates.offset to true.

example

zod.gen.ts

export const zFoo = z.string().datetime({ offset: true });

config

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'zod',
      compatibilityVersion: 3,
      dates: {
        offset: true,
      },
    },
  ],
};

Local times

You can allow values without a timezone by setting dates.local to true.

example

zod.gen.ts

export const zFoo = z.string().datetime({ local: true });

config

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'zod',
      compatibilityVersion: 3,
      dates: {
        local: true,
      },
    },
  ],
};

Metadata

It’s often useful to associate a schema with some additional metadata for documentation, code generation, AI structured outputs, form validation, and other purposes. If this is your use case, you can set metadata to true to generate additional metadata about schemas.

example

zod.gen.ts

export const zFoo = z.string().describe('Additional metadata');

config

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'zod',
      compatibilityVersion: 3,
      metadata: true,
    },
  ],
};

Types

In addition to Zod schemas, you can generate schema-specific types. These can be generated for all schemas or for specific resources.

example

zod.gen.ts

export type ResponseZodType = z.infer<typeof zResponse>;

config

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'zod',
      compatibilityVersion: 3,
      types: {
        infer: false, // by default, no `z.infer` types
      },
      responses: {
        types: {
          infer: true, // `z.infer` types only for response schemas
        },
      },
    },
  ],
};

You can customize the naming and casing pattern for schema-specific types using the .name and .case options.

Resolvers

You can further customize this plugin’s behavior using resolvers.

API

You can view the complete list of options in the UserConfig interface.

Examples

You can view live examples on StackBlitz or on GitHub.