Zod

WARNING

Zod plugin is currently in beta. The interface might change before it becomes stable. We encourage you to leave feedback on GitHub.

About

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

Features

• seamless integration with @hey-api/openapi-ts ecosystem
• Zod schemas for requests, responses, and reusable definitions

Installation

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

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    'zod', 
  ],
};

SDKs

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

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    'zod',
    {
      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 single request schema is generated for each endpoint. It may contain a request body, parameters, and headers.

config

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'zod',
      requests: true, 
    },
  ],
};

output

const zData = z.object({
  body: z
    .object({
      foo: z.string().optional(),
      bar: z.union([z.number(), z.null()]).optional(),
    })
    .optional(),
  path: z.object({
    baz: z.string(),
  }),
  query: z.never().optional(),
});

TIP

If you need to access individual fields, you can do so using the .shape API. For example, we can get the request body schema with zData.shape.body.

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.

config

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'zod',
      responses: true, 
    },
  ],
};

output

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

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.

config

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'zod',
      definitions: true, 
    },
  ],
};

output

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

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

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

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.

config

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'zod',
      metadata: true, 
    },
  ],
};

output

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

Types

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

config

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

output

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

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

Config API

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

Examples

You can view live examples on StackBlitz.

Sponsors

Help Hey API stay around for the long haul by becoming a sponsor.

Gold

• 

  Best-in-class SDKs and MCP for your API.

  stainless.com

Silver

• scalar.com

Bronze

• 
•