Input

target

Path or URL to your OpenAPI specification.

Type: string | string[] | OpenApiDocument | Record<string, unknown>

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: './petstore.yaml',
    },
  },
});

You can also pass an array of targets. Orval will try each target in order and use the first one that resolves successfully (file exists on disk or URL is reachable). This is useful for fallback scenarios, such as preferring a local spec file when available while falling back to a remote URL.

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: [
        './local-petstore.yaml',
        'https://petstore.swagger.io/v2/swagger.json',
      ],
    },
  },
});

The shorthand input property supports arrays as well:

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: [
      './local-petstore.yaml',
      'https://petstore.swagger.io/v2/swagger.json',
    ],
  },
});

override

transformer

Transform the OpenAPI specification before generation.

Type: String | Function

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      override: {
        transformer: 'src/api/transformer/add-version.js',
      },
    },
  },
});

The transformer runs before spec validation (and before the internal OpenAPI 2.0 → 3.1 upgrade), so you can use it to repair malformed specs (e.g. fix non-compliant fields) without having to disable validation entirely. If your spec is OpenAPI 2.0 (Swagger), the transformer receives the 2.0 document — not the upgraded 3.1 form.

The transformer function receives an OpenApiDocument and must return an OpenApiDocument or a Promise<OpenApiDocument> — async transformers are supported, so you can fetch overrides or run any awaitable repair step inside. You may mutate the input in place or return a new object. The defineTransformer helper from orval provides type inference for both sync and async returns.

import { defineTransformer } from 'orval';

export default defineTransformer((inputSchema) => ({
  ...inputSchema,
  info: {
    ...inputSchema.info,
    title: `${inputSchema.info?.title} - Custom`,
  },
}));

Async example:

import { defineTransformer } from 'orval';

export default defineTransformer(async (inputSchema) => {
  const overrides = await fetch('https://example.com/overrides.json').then(
    (r) => r.json(),
  );
  return { ...inputSchema, ...overrides };
});

See example transformer.

filters

Filter which endpoints to generate.

Default: {}

mode

Type: 'include' | 'exclude' Default: 'include'

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      filters: {
        mode: 'exclude',
        tags: ['pets'],
      },
    },
  },
});

tags

Type: (String | RegExp)[] Default: []

Filter by OpenAPI tags:

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      filters: {
        tags: ['pets', /health/],
      },
    },
  },
});

When tags is set and schemas is not, orval automatically limits the output to only the schemas referenced (directly or transitively) by the matching operations. This prevents unrelated schemas from appearing in the generated output.

If you also specify schemas, it takes precedence and the automatic inference is skipped. To filter endpoints by tags while still outputting all schemas, set includeUnreferencedSchemas: true — it works in both include and exclude mode.

schemas

Type: (String | RegExp)[]

Filter by schema names explicitly:

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      filters: {
        schemas: ['Error', /Cat/],
      },
    },
  },
});

includeUnreferencedSchemas

Type: Boolean Default: false

When tags is set (and schemas is not), orval emits only the schemas referenced by the matching operations. Set includeUnreferencedSchemas: true to keep every #/components/schemas entry — including schemas referenced by no operation — while still filtering endpoints by tags. The other component sections (responses, parameters, requestBodies) remain pruned to what the matching operations use. This works in both include and exclude mode, and is ignored when schemas is set.

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      filters: {
        mode: 'exclude',
        tags: ['stream'],
        includeUnreferencedSchemas: true,
      },
    },
  },
});

parserOptions

Optional configuration for the OpenAPI spec parser, particularly useful for fetching specs from protected URLs.

headers

Type: Array<{ domains: string[]; headers: Record<string, string> }>

Domain-specific headers to send when fetching the OpenAPI specification from remote URLs. Headers are matched based on the domain of the URL being fetched.

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: 'https://api.example.com/openapi.json',
      parserOptions: {
        headers: [
          {
            domains: ['api.example.com'],
            headers: {
              Authorization: 'Bearer YOUR_TOKEN',
              'X-API-Key': 'your-api-key',
            },
          },
        ],
      },
    },
  },
});

Configure different headers for different domains:

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: 'https://api.example.com/openapi.json',
      parserOptions: {
        headers: [
          {
            domains: ['api.example.com', 'api.prod.example.com'],
            headers: {
              Authorization: 'Bearer PROD_TOKEN',
            },
          },
          {
            domains: ['api.dev.example.com'],
            headers: {
              Authorization: 'Bearer DEV_TOKEN',
            },
          },
        ],
      },
    },
  },
});

externalRefs

Control how external $ref targets (local files or remote URLs) are resolved.

By default, orval refuses to resolve any external $ref and prints a config snippet you can paste into your parserOptions.

allow

Type: string[] Default: []

External $ref document targets to allow. Each entry should be the document part of the $ref (without the #/... fragment). File paths are relative to the spec file.

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: './openapi.yaml',
      parserOptions: {
        externalRefs: {
          allow: [
            './schemas/pet.yaml',
            './schemas/user.yaml',
            'https://example.com/schemas/shared.json',
          ],
        },
      },
    },
  },
});

Use ['*'] to allow all external refs (previous behavior). Orval will emit a warning listing external documents referenced by the top-level spec:

parserOptions: {
  externalRefs: {
    allow: ['*'],
  },
}

unsafeDisableValidation

Disable OpenAPI spec validation during code generation.

Type: boolean Default: false

When true, orval skips both spec-level validation (@scalar/openapi-parser) and the component-key check, and proceeds with code generation regardless of spec errors. Intended as an escape hatch for specs that use non-standard extensions (e.g. FastAPI's itemSchema on text/event-stream responses) which a compliant validator would otherwise reject. Prefer override.transformer — which runs before validation — when the spec can be repaired in-place.

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: './petstore.yaml',
      unsafeDisableValidation: true,
    },
  },
});