How to fix "server variable default is required" in OpenAPI

Every OpenAPI Server Variable Object must define a default. An enum can restrict the allowed substitutions, but it does not select the value used when a tool expands the server URL.

Broken YAML

The {region} variable has allowed values but no default:

openapi: 3.1.0
info:
  title: Regional API
  version: 1.0.0
servers:
  - url: https://{region}.api.example.test
    variables:
      region:
        enum: [us, eu]
paths: {}

Why it fails

The Server Variable Object requires default. Tools substitute this value when they need one concrete server URL. An enum is optional and only limits the available values.

Redocly reports The field default must be present on this level at #/servers/0/variables/region. Choose a usable value. When an enum exists, use one of its entries as the default.

Corrected YAML

Set us as the initial substitution:

openapi: 3.1.0
info:
  title: Regional API
  version: 1.0.0
servers:
  - url: https://{region}.api.example.test
    variables:
      region:
        default: us
        enum: [us, eu]
paths: {}

The variable name must also match the expression in the URL. A default does not repair a mismatch such as {region} in the URL and location under variables.

OpenAPI 3.0 vs 3.1

OpenAPI 3.0 and OpenAPI 3.1 both require a string default for every Server Variable Object. OpenAPI 3.0 recommends a non-empty enum and recommends that the default be one of its values (SHOULD). OpenAPI 3.1 requires both when an enum is present (MUST). Use a non-empty enum and a listed default to work with both versions.

Server variable substitution is different from JSON Schema validation. Do not use a schema-level default or oneOf inside the Server Variable Object.

Specification sections: OpenAPI 3.0.4 and OpenAPI 3.1.1.

Validate the fix

Save the complete document as openapi.yaml, then run:

pnpm --package=@redocly/cli@2.53.3 dlx redocly lint openapi.yaml --extends=minimal

The corrected server removes the structural missing-default error. Redocly can also report a separate warning for placeholder domains such as example.com; that policy warning is not the server-variable error.