extend for definitions for environment variables

[wibed]

environment variables need some way to be defined right?.
ideally some default definition of the same that would outline the scope of the library.

[dfbustosus]

OpenAPI does not currently define process or deployment environment variables. An OpenAPI Description defines the externally observable HTTP interface, so values such as DATABASE_URL, PORT, or LOG_LEVEL normally belong in deployment or application-configuration documentation.

If a value selects the API base URL, use servers or a Server Variable:

servers:
  - url: https://{environment}.example.com/v1
    variables:
      environment:
        default: api
        enum: [api, staging-api]

That is URL-template substitution; it does not tell tooling to read an OS environment variable. If a value is actually sent over HTTP, describe it as a Parameter, Schema field, or Security Scheme as appropriate.

A private machine-readable convention can use a namespaced specification extension such as x-acme-environment-variables, but its schema and behavior would be custom and standard OpenAPI tools would not enforce it. Actual secret values should never be embedded in the document.

If environments expose different contracts, separate descriptions or an OpenAPI Overlay may be clearer. The right representation therefore depends on whether the variable configures the server, a generated library, deployment, or an HTTP request.

References: Server Variables, Specification Extensions, and Overlays.

[miqui]

Hi @dfbustosus - Can you articulate the problem a bit better? For now, focus on Server variables. Not sure what problem you are trying to solve.

[dfbustosus]

@miqui Certainly. I was not proposing that an OpenAPI document read operating-system environment variables directly; I was separating two concepts that the original question appears to combine.

For Server Variables, the concrete problem is only URL-template substitution. For example:

servers:
  - url: https://{region}.api.example.com
    variables:
      region:
        default: us-east
        enum: [us-east, eu-west]

OAS defines the variable's allowed/default values and how it expands in the URL. It deliberately does not define whether a non-default value comes from API_REGION, a CLI flag, a generator configuration file, or a UI selection. That binding belongs to the tool or deployment system.

The deployment-oriented problem raised by @bwdmr is different: generators currently make independent choices about runtime configuration, so generated clients or servers may use inconsistent environment-variable names and semantics. Standardizing that would first require a precise contract:

• Which artifact consumes the variable: generated client, generated server, or deployment manifest?
• What observable behavior changes when it is set?
• Is it merely a source for a Server Variable value, or arbitrary application configuration?
• How are required values, defaults, types, and secrets handled?

For the example above, a generator-specific extension could explicitly bind the Server Variable without changing its OAS meaning:

variables:
  region:
    default: us-east
    enum: [us-east, eu-west]
    x-example-env: API_REGION

That is interoperable only among tools agreeing on the extension. A standard OAS field would need normative runtime/tooling behavior, which is broader than describing the HTTP interface. If the intended scope is specifically “bind a Server Variable to an external configuration source,” that is a much narrower proposal than general environment-variable definitions and would be the clearest end-to-end use case to evaluate.

[bwdmr]

i understand your post as an attempt at finding a middleground on existing solution and interpret it as implementation detail.

personally i found environment variables separate to server variables as these can be deployment oriented.
generators have the difficulty to decide between interpretation and standard.

as the numbers of generators increase the differences between them can be an obstacle which would weigh on specification standards such as openapi is. the logical conclusion would be to lighten that burden by removing intention to specification.

while the intention might be correct to presume the environment variables within the server variables, to me it seems distinguished enough to separate those two and make it easier for generators to adapt such salience faster.

[UmeshCode1]

The distinction raised here by @bwdmr is an important one that repeatedly surfaces across SDK generators (such as OpenAPI Generator, Speakeasy, Fern, and Kiota).

To keep the core specification clean and avoid specification bloat, it helps to understand why OAS maintains this separation and how the ecosystem standardizes this:

1. The Wire Contract Boundary vs. Client Runtime

The OpenAPI Specification is intentionally scoped as a protocol wire contract—it strictly describes what passes over the wire (HTTP verbs, paths, headers, query params, request/response media types, and status codes).

Process-level environment variables (like process.env.API_KEY or std::env::var("BASE_URL")) are fundamentally execution runtime concerns, which vary wildly across target languages (e.g., Node.js vs. Rust vs. Android vs. embedded C). Embedding host OS environment bindings directly into the core OAS would blur the line between interface declaration and execution context.

2. How the Ecosystem Solves Generator Inconsistency Today

Because SDK generators need a way to know which environment variable maps to an auth header or base URL without guessing:

1. OpenAPI Overlays (Standardized):
   Using the OpenAPI Overlay Specification, teams maintain clean, runtime-agnostic API specs for public documentation, and apply an overlay for SDK build pipelines that injects generator metadata.

2. Namespaced Extensions (x-):
   Major SDK generators standardize on specification extensions for parameter and security scheme binding:

   components:
     securitySchemes:
       ApiKeyAuth:
         type: apiKey
         in: header
         name: X-API-KEY
         x-environment-variable: "ACME_API_KEY"
         description: "API Key read automatically from ACME_API_KEY environment variable if not passed to client constructor."

   Or for base URLs:

   servers:
     - url: https://api.example.com/v1
       x-environment-variable: "ACME_BASE_URL"

3. Arazzo Specification (Workflow and Runtime Inputs):
   If the goal is to define end-to-end operational workflows where inputs flow from environment context or previous step outputs, the newer Arazzo Specification explicitly models runtime inputs ($inputs.<param>) across workflows without modifying the underlying OAS description.

Keeping host environment binding within Overlays or x- generator extensions maintains OAS's integrity as a language-agnostic wire contract while giving generators the exact deterministic mapping they need.