---
title: "Parser"
description: "Configure @hey-api/openapi-ts."
url: "https://heyapi.dev/docs/openapi/typescript/configuration/parser"
---

We parse your input before making it available to plugins. Configuring the parser is optional, but it provides an ideal opportunity to modify or validate your input as needed.

## Patch

[Section titled “Patch”](#patch)

Sometimes you need to modify raw input before it’s processed further. A common use case is fixing an invalid specification or adding a missing field. For this reason, custom patches are applied before any parsing takes place.

You can add custom patches with `patch`.

openapi-ts.config.ts

```js
export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  parser: {
    patch: {
      schemas: {
        Foo: (schema) => {
          // convert date-time format to timestamp
          delete schema.properties.updatedAt.format;
          schema.properties.updatedAt.type = 'number';
        },
        Bar: (schema) => {
          // add missing property
          schema.properties.meta = {
            additionalProperties: true,
            type: 'object',
          };
          schema.required = ['meta'];
        },
        Baz: (schema) => {
          // remove property
          delete schema.properties.internalField;
        },
      },
    },
  },
};
```

## Validate

[Section titled “Validate”](#validate)

Caution

The validator feature is very limited. You can help improve it by submitting more [use cases](https://github.com/hey-api/openapi-ts/issues/1970#issuecomment-2933189789).

If you don’t control or trust your input, you might want to validate it. Any detected errors in your input will exit `@hey-api/openapi-ts` and no plugins will be executed.

To validate your input, set `validate_EXPERIMENTAL` to `true`.

openapi-ts.config.ts

```js
export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  parser: {
    validate_EXPERIMENTAL: true,
  },
};
```

## Filters

[Section titled “Filters”](#filters)

Filters allow you to trim your input before it’s processed further, so your output contains only relevant resources.

### Operations

[Section titled “Operations”](#operations)

Set `include` to match operations to be included or `exclude` to match operations to be excluded. Both exact keys and regular expressions are supported. When both rules match the same operation, `exclude` takes precedence over `include`.

* include

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      filters: {
        operations: {
          include: ['GET /api/v1/foo', '/^[A-Z]+ /api/v1//'],
        },
      },
    },
  };
  ```

* exclude

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      filters: {
        operations: {
          exclude: ['GET /api/v1/foo', '/^[A-Z]+ /api/v1//'],
        },
      },
    },
  };
  ```

### Tags

[Section titled “Tags”](#tags)

Set `include` to match tags to be included or `exclude` to match tags to be excluded. When both rules match the same tag, `exclude` takes precedence over `include`.

* include

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      filters: {
        tags: {
          include: ['v2'],
        },
      },
    },
  };
  ```

* exclude

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      filters: {
        tags: {
          exclude: ['v1'],
        },
      },
    },
  };
  ```

### Deprecated

[Section titled “Deprecated”](#deprecated)

You can filter out deprecated resources by setting `deprecated` to `false`.

openapi-ts.config.ts

```js
export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  parser: {
    filters: {
      deprecated: false,
    },
  },
};
```

### Schemas

[Section titled “Schemas”](#schemas)

Set `include` to match schemas to be included or `exclude` to match schemas to be excluded. Both exact keys and regular expressions are supported. When both rules match the same schema, `exclude` takes precedence over `include`.

* include

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      filters: {
        schemas: {
          include: ['Foo', '/^Bar/'],
        },
      },
    },
  };
  ```

* exclude

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      filters: {
        schemas: {
          exclude: ['Foo', '/^Bar/'],
        },
      },
    },
  };
  ```

### Parameters

[Section titled “Parameters”](#parameters)

Set `include` to match parameters to be included or `exclude` to match parameters to be excluded. Both exact keys and regular expressions are supported. When both rules match the same parameter, `exclude` takes precedence over `include`.

* include

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      filters: {
        parameters: {
          include: ['QueryParameter', '/^MyQueryParameter/'],
        },
      },
    },
  };
  ```

* exclude

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      filters: {
        parameters: {
          exclude: ['QueryParameter', '/^MyQueryParameter/'],
        },
      },
    },
  };
  ```

### Request Bodies

[Section titled “Request Bodies”](#request-bodies)

Set `include` to match request bodies to be included or `exclude` to match request bodies to be excluded. Both exact keys and regular expressions are supported. When both rules match the same request body, `exclude` takes precedence over `include`.

* include

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      filters: {
        requestBodies: {
          include: ['Payload', '/^SpecialPayload/'],
        },
      },
    },
  };
  ```

* exclude

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      filters: {
        requestBodies: {
          exclude: ['Payload', '/^SpecialPayload/'],
        },
      },
    },
  };
  ```

### Responses

[Section titled “Responses”](#responses)

Set `include` to match responses to be included or `exclude` to match responses to be excluded. Both exact keys and regular expressions are supported. When both rules match the same response, `exclude` takes precedence over `include`.

* include

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      filters: {
        responses: {
          include: ['Foo', '/^Bar/'],
        },
      },
    },
  };
  ```

* exclude

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      filters: {
        responses: {
          exclude: ['Foo', '/^Bar/'],
        },
      },
    },
  };
  ```

### Orphaned resources

[Section titled “Orphaned resources”](#orphaned-resources)

If you only want to exclude orphaned resources, set `orphans` to `false`. This is the default value when combined with any other filters. If this isn’t the desired behavior, you may want to set `orphans` to `true` to always preserve unused resources.

openapi-ts.config.ts

```js
export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  parser: {
    filters: {
      orphans: false,
    },
  },
};
```

### Order

[Section titled “Order”](#order)

For performance reasons, we don’t preserve the original order when filtering out resources. If maintaining the original order is important to you, set `preserveOrder` to `true`.

openapi-ts.config.ts

```js
export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  parser: {
    filters: {
      preserveOrder: true,
    },
  },
};
```

## Transforms

[Section titled “Transforms”](#transforms)

You can think of transforms as deterministic [patches](#patch). They provide an easy way to apply the most commonly used input transformations.

### Enums

[Section titled “Enums”](#enums)

Your input might contain two types of enums:

* enums defined as reusable components (root enums)
* non-reusable enums nested within other schemas (inline enums)

You may want all enums to be reusable. This is because only root enums are typically exported by plugins. Inline enums will never be directly importable since they’re nested inside other schemas.

* root

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      transforms: {
        enums: 'root',
      },
    },
  };
  ```

* inline

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      transforms: {
        enums: 'inline',
      },
    },
  };
  ```

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

### Properties required by default

[Section titled “Properties required by default”](#properties-required-by-default)

By default, any object schema with a missing `required` keyword is interpreted as “no properties are required.” This is the correct behavior according to the OpenAPI standard. However, some specifications interpret a missing `required` keyword as “all properties should be required.”

This option allows you to change the default behavior so that properties are required by default unless explicitly marked as optional.

* default

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      transforms: {
        propertiesRequiredByDefault: false,
      },
    },
  };
  ```

* required

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      transforms: {
        propertiesRequiredByDefault: true,
      },
    },
  };
  ```

### Read-write

[Section titled “Read-write”](#read-write)

Your schemas might contain read-only or write-only fields. Using such schemas directly could mean asking the user to provide a read-only field in requests, or expecting a write-only field in responses. We separate schemas for requests and responses if direct usage would result in such scenarios.

* default

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      transforms: {
        readWrite: {
          requests: '{{name}}Writable',
          responses: '{{name}}',
        },
      },
    },
  };
  ```

* disabled

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      transforms: {
        readWrite: false,
      },
    },
  };
  ```

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

### Schema Name

[Section titled “Schema Name”](#schema-name)

Sometimes your schema names are auto-generated or follow a naming convention that produces verbose or awkward type names. You can rename schema component keys throughout the specification, automatically updating all `$ref` pointers. For example, stripping version markers from schema names, removing vendor prefixes, converting naming conventions, or shortening deeply qualified names.

* function

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      transforms: {
        schemaName: (name) => {
          // Strip version markers: ServiceRoot_v1_20_0_ServiceRoot → ServiceRoot
          let clean = name.replace(
            /([A-Za-z\d]+)_v\d+_\d+_\d+_([A-Za-z\d]*)/g,
            (_, p1, p2) => (p2.startsWith(p1) ? p2 : p1 + p2),
          );
          // Deduplicate prefixes: Foo_Foo → Foo
          const m = clean.match(/^([A-Za-z\d]+)_\1([A-Za-z\d]*)$/);
          if (m) clean = m[1] + m[2];
          return clean;
        },
      },
    },
  };
  ```

* template

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      transforms: {
        schemaName: 'Api{{name}}',
      },
    },
  };
  ```

Name Collisions

If a transformed schema name conflicts with an existing schema, the rename is skipped for that schema to prevent overwrites. The original name is preserved.

## Pagination

[Section titled “Pagination”](#pagination)

Paginated operations are detected by having a pagination keyword in its parameters or request body. By default, we consider the following to be pagination keywords: `after`, `before`, `cursor`, `offset`, `page`, and `start`.

You can provide custom pagination keywords using `pagination.keywords`.

* extend

  openapi-ts.config.ts

  ```js
  import { defaultPaginationKeywords } from '@hey-api/openapi-ts';


  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      pagination: {
        keywords: [
          ...defaultPaginationKeywords,
          'extra',
          'pagination',
          'keywords',
        ],
      },
    },
  };
  ```

* override

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      pagination: {
        keywords: [
          'custom',
          'pagination',
          'keywords',
        ],
      },
    },
  };
  ```

## Hooks

[Section titled “Hooks”](#hooks)

Hooks affect runtime behavior but aren’t tied to any single plugin. They can be configured globally via `hooks` or per plugin through the `~hooks` property.

* parser

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      hooks: {}, // configure global hooks
    },
  };
  ```

* plugin

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    plugins: [
      {
        name: '@tanstack/react-query',
        '~hooks': {}, // configure plugin hooks
      },
    ],
  };
  ```

We always use the first hook that returns a value. If a hook returns no value, we fall back to less specific hooks until one does.

### Operations

Each operation has a list of classifiers that can include `query`, `mutation`, both, or none. Plugins may use these values to decide whether to generate specific output. For example, you usually don’t want to generate [TanStack Query options](https://heyapi.dev/openapi-ts/plugins/tanstack-query#queries) for PATCH operations.

#### Query operations

By default, GET operations are classified as `query` operations.

#### Mutation operations

By default, DELETE, PATCH, POST, and PUT operations are classified as `mutation` operations.

#### Example: POST search query

[Section titled “Example: POST search query”](#example-post-search-query)

Imagine your API has a POST `/search` endpoint that accepts a large payload. By default, it’s classified as a `mutation`, but in practice it behaves like a `query`, and your [state management](https://heyapi.dev/openapi-ts/state-management) plugin should generate query hooks.

You can achieve this by classifying the operation as `query` in a matcher.

* isQuery

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      hooks: {
        operations: {
          isQuery: (op) => {
            if (op.method === 'post' && op.path === '/search') {
              return true;
            }
          },
        },
      },
    },
  };
  ```

* getKind

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    parser: {
      hooks: {
        operations: {
          getKind: (op) => {
            if (op.method === 'post' && op.path === '/search') {
              return ['query'];
            }
          },
        },
      },
    },
  };
  ```

### Symbols

Each symbol can have a placement function deciding its output location.

#### Example: Alphabetic sort

[Section titled “Example: Alphabetic sort”](#example-alphabetic-sort)

While we work on a better example, let’s imagine a world where it’s desirable to place every symbol in a file named after its initial letter. For example, a function named `Foo` should end up in the file `f.ts`.

You can achieve this by using the symbol’s name.

openapi-ts.config.ts

```js
export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  parser: {
    hooks: {
      symbols: {
        getFilePath: (symbol) => {
          if (symbol.name) {
            return symbol.name[0]?.toLowerCase();
          }
        },
      },
    },
  },
};
```

Most plugins expose configuration options that allow you to rename many of the generated symbols. If you need even more control, use the `getName()` hook.

#### Example: Enum naming

[Section titled “Example: Enum naming”](#example-enum-naming)

By default, generated enums use the same name for both the type and the runtime value.

* example

  index.gen.ts

  ```ts
  export const Flags = {
    ALPHA: 'alpha',
    BETA: 'beta',
  } as const;


  export type Flags = (typeof Flags)[keyof typeof Flags];
  ```

* config

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    plugins: [
      {
        enums: 'javascript',
        name: '@hey-api/typescript',
      },
    ],
  };
  ```

While this code works perfectly fine due to TypeScript’s declaration merging, let’s say we want to use a different name for the type. We can accomplish this with the `getName()` hook.

* example

  index.gen.ts

  ```ts
  export const Flags = {
    ALPHA: 'alpha',
    BETA: 'beta',
  } as const;


  export type FlagsType = (typeof Flags)[keyof typeof Flags];
  ```

* config

  openapi-ts.config.ts

  ```js
  export default {
    input: 'hey-api/backend', // sign up at app.heyapi.dev
    output: 'src/client',
    plugins: [
      {
        enums: 'javascript',
        name: '@hey-api/typescript',
        '~hooks': {
          symbols: {
            getName({ meta, name, schema }) {
              if (schema?.type === 'enum' && meta.category === 'type') {
                return `${name}Type`;
              }
            },
          },
        },
      },
    ],
  };
  ```

## Examples

You can view live examples on [StackBlitz](https://stackblitz.com/orgs/github/hey-api/collections/openapi-ts-examples) or on [GitHub](https://github.com/hey-api/openapi-ts/tree/main/examples).