OpenAPIExtensions

Global parameters

View as Markdown

A global parameter is a value set once — at the SDK client level or the CLI config level — and injected into every relevant request, instead of being passed on every call. Per-call values always win over the global value.

Global parameters differ from global headers: a global header is always a header, while a global parameter can target a header, query parameter, path parameter, or a field in the request body.

Declare global parameters

Use the x-fern-global-parameters extension at the root of your spec. Each entry declares one parameter:

openapi.yml
1x-fern-global-parameters:
2  - name: currency
3    in: body
4    target: config.currency
5    env: ACME_CURRENCY
6    default: USD
7    optional: true
8    apply: auto
9    docs: The currency code used for pricing.
10  - name: region
11    in: path
12    target: regionId
13    env: ACME_REGION
14    default: us
15    apply: explicit

Fields

name
stringRequired

The canonical identifier for the parameter. It’s the base for the generated flag or constructor argument, and the key operations use to opt in.

in
stringDefaults to body

Where the value is injected on the wire: body, query, header, or path.

target
string

The wire-level injection target. For body, a dotted path into the request body (for example, config.currency). For query, header, and path, the parameter or header name. Defaults to name.

type
stringDefaults to string

The value type: string, integer, double, or boolean.

env
string

An environment variable the value falls back to when the caller doesn’t provide one.

default
any

A client-side default used when neither the caller nor the environment variable supplies a value. x-fern-default takes precedence over default.

optional
booleanDefaults to false

Whether the parameter can be omitted. A required parameter with no value, default, or environment variable produces an error.

apply
stringDefaults to explicit

How the parameter applies to operations. explicit applies only to operations that opt in; auto applies to every operation whose request contains the target.

parameter-name
string

An SDK/CLI-facing alias. When set, this name is used for the generated flag or constructor argument instead of name.

Apply to specific operations

When a parameter uses apply: explicit (the default), it applies only to operations that opt in with the per-operation x-fern-global-parameter extension. List the parameter names to include. The value accepts a single string or a list:

openapi.yml
1paths:
2  /v1/products/{regionId}/search:
3    post:
4      x-fern-global-parameter:
5        - region
6        - currency
7      operationId: searchProducts
8      # ...
9  /v1/products/{regionId}/{productId}:
10    get:
11      x-fern-global-parameter: region
12      operationId: getProduct
13      # ...

Each name must match a parameter declared in x-fern-global-parameters. A parameter with apply: auto is injected into every operation whose request contains its target, with no opt-in required.

Resolution order

At runtime, the value is resolved from the first available source, in order:

  1. The per-call value (a per-operation parameter or an explicit request field) — this always wins.
  2. The CLI flag or constructor argument.
  3. The environment variable (env).
  4. The client-side default (x-fern-default, then default).

For a body parameter with a nested target, a value the caller already supplies at that path is never overwritten.

Generated CLI behavior

The CLI generator registers each global parameter as a top-level flag (with its env fallback and default) and injects the resolved value at the declared location for every applicable command.