OpenAPI Extensions

Scalar SDK Generator reads a small set of OpenAPI vendor extensions when it derives an SDK configuration and compiles an SDK. They let an API description carry SDK-specific intent without requiring a separate configuration file.

When extensions are read depends on where they sit. Document-root and operation extensions are read when the generator derives a configuration from the document; once you supply a configuration, its resources, settings, and pagination are authoritative and those extensions are not re-read. Schema, parameter, and enum extensions apply on every build.

Use these extensions only where the guide says they are supported. Values from an OpenAPI document are treated as untrusted input: malformed values are ignored or reported through Diagnostics, rather than becoming generated code.

Extensions that mirror a configuration block use the same field names and value shapes as Configuration. A standalone Scalar SDK configuration remains the better home for settings shared across multiple documents or targets.

Scalar extensions

Document root

x-scalar-sdk-client-settings:
  defaultTimeout: 30000
  defaultRetries:
    maxRetries: 2
  defaultHeaders:
    X-Client: acme-sdk

x-scalar-sdk-settings:
  unwrapResponseFields: [data]
  ordering: crud

x-scalar-pagination:
  - name: cursor
    type: cursor
    request:
      cursor:
        type: cursor
        param: cursor
        location: query
    response:
      items:
        type: items
        location: body
        path: [data]
      next:
        type: cursor
        location: body
        path: [next_cursor]

Operations

These are read when a configuration is derived from the document. With a configuration of your own, an operation it places is generated even if it carries x-scalar-ignore.

paths:
  /users:
    get:
      operationId: listUsers
      x-scalar-method: users.list
      x-scalar-pagination: cursor
      x-scalar-unwrap: data
      responses:
        '200': { description: OK }

Parameters

Schemas and properties

x-scalar-override-schema takes a Schema Object as its value. This is useful when the published description must retain a broader wire shape while the SDK intentionally exposes a safer or more specific type.

Omitting a property or parameter

x-scalar-ignore is read on operations and component schemas only. To leave a single property or parameter out of the generated SDK, list it by wire name in your SDK configuration:

• A property of a component schema: add a top-level models entry for that schema with skipProperties.
• A parameter: add it to skipParams on the method that takes it. A path parameter is part of the URL and is never dropped.

{
  "models": {
    "User": {
      "type": "model",
      "openapiUri": "#/components/schemas/User",
      "skipProperties": ["legacy_id"]
    }
  },
  "resources": {
    "users": {
      "methods": {
        "list": { "kind": "http", "endpoint": "get /users", "skipParams": ["debug"] }
      }
    }
  }
}

A document imported from another generator can carry that generator's omit markers instead, and they are honored too: see the x-fern-ignore and x-stainless-skip rows under Imported vendor extensions.

Enums

The following arrays are aligned with the enum's enum values by index. Values that cannot be aligned are ignored.

Generated OpenAPI additions

These extensions are written to an augmented OpenAPI document by the generator. They may also be preserved when already present in a source document.

The code-sample pipeline also recognizes x-codeSamples, x-code-samples, and x-custom-examples on operations. Select the output key with openapi.codeSamples in the SDK configuration.

Imported vendor extensions

The generator also reads these extensions written for other SDK generators. They are useful when importing an existing Fern, Speakeasy, or Stainless project; new documents should generally use the native Scalar extension or configuration field named in the table.

When a build has no SDK configuration and the document carries x-fern-* extensions on its root, a server, or an operation, the document is imported as a Fern project: the starter configuration is derived as it would be for any document, with the Fern extensions mapped on top, and no pagination is inferred from the document's shape (see Pagination). Once a configuration exists, it decides.

Fern

Speakeasy

Stainless

Extensions outside the SDK vocabulary

x-scalar-navigation, x-scalar-order, x-scalar-is-dirty, x-scalar-original-document-hash, x-scalar-original-source-url, and x-scalar-registry-meta are Scalar workspace metadata. The loader strips them before generation; do not use them to control an SDK.

With openapi.tags: "resources", the augmented OpenAPI document labels each derived tag with x-displayName and removes x-tagGroups; neither affects generated SDK methods or models.

Next steps

• Configuration — the config blocks mirrored by root-level extensions
• Pagination — the scheme shape x-scalar-pagination carries, and the helpers it generates
• Diagnostics — messages for invalid, ignored, or incomplete input
• AsyncAPI — SDK generation from AsyncAPI documents