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',
            },
          },
        ],
      },
    },
  },
});

compress

Type: (value: string) => Promise<string> | string

Optional callback forwarded to @scalar/json-magic when external references are bundled. It may be synchronous or asynchronous. The callback receives Scalar's normalized external document identity/path, not necessarily the literal $ref, and returns the key used internally for that document. Returning stable service names makes external schema names easier to read when using externalRefs.strategy: 'always'.

import { defineConfig } from 'orval';

const externalIdentity = (value: string) => {
  if (value.includes('billing')) return 'billing';
  if (value.includes('catalog')) return 'catalog';
  return value;
};

export default defineConfig({
  petstore: {
    input: {
      target: './openapi.yaml',
      parserOptions: {
        compress: externalIdentity,
        externalRefs: {
          allow: ['*'],
          strategy: 'always',
        },
      },
    },
  },
});

With this configuration, a User schema from billing.yaml is emitted as User_billing. An asynchronous callback uses the same configuration shape:

const externalIdentity = async (value: string) =>
  value.includes('billing') ? 'billing' : value;

The callback must produce unique values for distinct external documents. Scalar will retry collisions, but a callback that cannot produce a unique value fails instead of silently merging two documents.

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: ['*'],
  },
}

strategy

Type: 'default' | 'always' Default: 'default'

Controls the names assigned to schemas imported from external documents.

• default preserves the current behavior: an external schema keeps its original name and receives a suffix only when that name collides with an existing schema.
• always appends the sanitized external document key to every external schema. For example, User from the billing document becomes User_billing.

The external document key is produced by parserOptions.compress when it is configured. Without compress, always still works, but Scalar's default generated, hash-like key is used, so names may look like User_<generated-key>. Use a stable custom compress callback such as one that maps billing.yaml to billing when human-readable names are needed.

Orval does not silently overwrite an existing final component name. A collision with a local or external component, including a collision after suffix sanitization, produces an explicit error. This deliberately prevents an ambiguous suffix from overwriting a schema as could happen in the legacy behavior.

externalRefs.allow still controls which external documents may be loaded; compress and strategy only control the names of external schemas that have already been allowed.

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,
    },
  },
});