# Input

## target

Path or URL to your OpenAPI specification.

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

```ts
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.

```ts
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:

```ts
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`

```ts
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.

```ts
import { defineTransformer } from 'orval';

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

Async example:

```ts
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](https://github.com/orval-labs/orval/blob/master/samples/basic/api/transformer/add-version.js).

## filters

Filter which endpoints to generate.

**Default:** `{}`

### mode

**Type:** `'include' | 'exclude'`
**Default:** `'include'`

```ts
import { defineConfig } from 'orval';

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

### tags

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

Filter by OpenAPI tags:

```ts
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`](#includeunreferencedschemas) — it works in both `include` and `exclude` mode.

### schemas

**Type:** `(String | RegExp)[]`

Filter by schema names explicitly:

```ts
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.

```ts
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.

```ts
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:

```ts
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'`.

```ts
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:

```ts
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.

```ts
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:

```ts
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.

> **Warning:**
> **Security:** External `$ref` values come from the spec being processed, which may
> be untrusted. Allowing all external refs (`['*']`) means orval will read arbitrary
> local files and fetch arbitrary URLs referenced by the spec. Prefer listing
> specific documents you trust.

`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`

> **Warning:**
> **Use at your own risk.** Code generation from an invalid OpenAPI spec is not
> guaranteed to work and may break in minor updates. Bug reports with validation
> disabled will not be accepted.

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`](#transformer) — which runs before validation — when
the spec can be repaired in-place.

```ts
import { defineConfig } from 'orval';

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