SDK variables (OpenAPI) | Fern Documentation

The x-fern-sdk-variables extension allows you to define variables that are set once during SDK client initialization and automatically used in path parameters across all endpoint calls. This is useful for common parameters like tenant IDs, organization IDs, or environment identifiers that appear in many endpoint paths.

SDK variables are supported in TypeScript (v2.6.3+), Python (v4.24.0+), Java (v3.6.3+), Go (v1.66.0+), C# (v2.87.0+), Ruby (v1.31.0+), and PHP (v2.25.0+). Only string types are supported.

Configuration

Define variables at the document level using x-fern-sdk-variables, then mark path parameters as variables using x-fern-sdk-variable:

openapi.yml

x-fern-sdk-variables:
  gardenId:
    type: string
    description: The unique identifier for your garden
  zoneId:
    type: string
    description: The zone within the garden
paths:
  /gardens/{gardenId}/zones/{zoneId}/plants:
    get:
      operationId: list_plants_in_zone
      parameters:
        - name: gardenId
          in: path
          required: true
          x-fern-sdk-variable: gardenId
          schema:
            type: string
        - name: zoneId
          in: path
          required: true
          x-fern-sdk-variable: zoneId
          schema:
            type: string

SDK usage

Variables are set once on the client instead of being passed to individual method calls. Bound path parameters are removed from the generated method signatures:

const client = new PlantClient({
  gardenId: "garden_123",
  zoneId: "zone_456",
  apiKey: "your-api-key"
});
const plants = await client.listPlantsInZone();

In TypeScript, Python, and Java, a variable is required when the client is constructed. In Go, C#, Ruby, and PHP, the client accepts variables as optional settings, and calling an endpoint that uses an unset variable raises an error before the request is sent. Go and PHP also accept a variable as a per-request option (option.WithGardenID(...) in Go, the options array in PHP), which overrides the client value for that call.

Environment variable fallback

Add x-fern-env to a variable in x-fern-sdk-variables to let the SDK read the value from an environment variable when it isn’t passed to the client:

openapi.yml

x-fern-sdk-variables:
  gardenId:
    type: string
    description: The unique identifier for your garden
    x-fern-env: PLANT_GARDEN_ID
  zoneId:
    type: string
    description: The zone within the garden

A variable with x-fern-env becomes an optional client setting. A value passed to the client takes precedence over the environment variable. If neither is set, the SDK raises an error that names both the variable and the environment variable. Variables without x-fern-env, such as zoneId, keep the behavior described in SDK usage.

Language	Fallback	Error when the value is missing
TypeScript (v3.99.0+)	`process.env.PLANT_GARDEN_ID`	Thrown when the client is constructed
Java (v4.26.0+)	Builder field defaults to `System.getenv("PLANT_GARDEN_ID")`	`build()` throws `IllegalStateException`
Go (v1.66.0+)	`os.Getenv("PLANT_GARDEN_ID")` when the client is created	Bound endpoint methods return an error
C# (v2.87.0+)	`ClientOptions.GardenId` defaults to `Environment.GetEnvironmentVariable("PLANT_GARDEN_ID")`	Bound endpoint methods throw `ArgumentException`
Ruby (v1.31.0+)	`garden_id:` keyword defaults to `ENV.fetch("PLANT_GARDEN_ID", nil)`	Bound endpoint methods raise `ArgumentError`
PHP (v2.25.0+)	`getenv('PLANT_GARDEN_ID')`	Bound endpoint methods throw `InvalidArgumentException`

Python SDKs don’t support the environment variable fallback yet.

With PLANT_GARDEN_ID set in the environment, callers omit gardenId when creating the client:

// gardenId is read from PLANT_GARDEN_ID
const client = new PlantClient({
  zoneId: "zone_456",
  apiKey: "your-api-key"
});

In a Fern Definition, declare the fallback with the env key on a variable in api.yml.