Pydantic v2

About

Pydantic is the most widely used data validation library for Python. Fast and extensible, Pydantic plays nicely with your linters/IDE/brain.

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

Features

• Pydantic v2 support
• seamless integration with @hey-api/openapi-python ecosystem
• Pydantic models for requests, responses, and reusable definitions
• minimal learning curve thanks to extending the underlying technology

Installation

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

openapi-python.config.ts

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

SDKs

Pydantic can validate or transform data directly in your SDK. Set validator or transformer to true on the SDK plugin to enable it.

validator

openapi-python.config.ts

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

transformer

openapi-python.config.ts

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

The SDK page covers validators and transformers in more detail.

Output

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

Requests

A Pydantic model is generated for every request layer of each endpoint.

example

pydantic.gen.ts

const vDeletePetHeaders = v.object({
  api_key: v.optional(v.string()),
});

const vDeletePetPath = v.object({
  petId: v.number(),
});

const vDeletePetQuery = v.object({
  additionalMetadata: v.string(),
});

config

openapi-python.config.ts

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

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

Responses

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

example

pydantic.gen.ts

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

config

openapi-python.config.ts

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

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

Definitions

A Pydantic model is generated for every reusable definition from your input.

example

pydantic.gen.ts

const vFoo = v.pipe(v.number(), v.integer());

const vBar = v.object({
  bar: v.optional(v.array(v.pipe(v.number(), v.integer()))),
});

config

openapi-python.config.ts

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

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. You can set metadata to true to attach descriptions to schemas when available.

example

pydantic.gen.ts

export const vFoo = v.pipe(
  v.string(),
  v.metadata({
    description: 'Additional metadata',
  }),
);

config

openapi-python.config.ts

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

For more control over metadata, you can provide your own function. It receives the source schema, the target node object, and the $ builder for populating metadata.

example

pydantic.gen.ts

export const vFoo = v.pipe(
  v.string(),
  v.metadata({
    hasTitle: false,
    createdAt: 1735732800000,
  }),
);

config

openapi-python.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'pydantic',
      metadata({ $, node, schema }) {
        node.prop('hasTitle', $.literal(Boolean(schema.title)));
        node.prop('createdAt', $.literal(Date.now()));
      },
    },
  ],
};

Resolvers

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

API

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