Spec extensions

Spec extensions put SDK settings in your OpenAPI document, so they live with your API and go through your normal code review. Use SDK Studio if you'd rather keep your spec clean: the two reach the same place.

Extensions that start x-octri- have a matching x-stainless- name, so a spec written for Stainless mostly works as it is. If a node has both, x-octri- wins.

Naming

x-octri-methodtextoperation

Sets the generated method name. Your operationId stays as it is.

x-octri-modeltextschema

Sets the generated model name.

x-octri-namingnames per languageoperation or schema

Sets a name for one language, with method_name, model_name or method_argument.

x-octri-paramtext or trueoperation

Sends the request body as one argument, rather than spreading its fields. Name the argument, or use true for body.

For example, a different method name in Go and argument name in Python:

paths:
  /users:
    get:
      operationId: listUsers
      x-octri-naming:
        go:
          method_name: ListAll
        python:
          method_argument: api_timeout

Grouping and order

x-octri-sdk-tagslistoperation or schema

On an operation, sets its namespace, overriding tags. Use a path to nest: ["Billing/Invoices"]. On a schema, sets the folder the model is generated in.

x-octri-sdk-ordernumberoperation

Sets its position in the generated SDK.

Deprecation

x-octri-deprecation-messagetextoperation or schema

Marks it deprecated, and adds your message to the doc comment.

x-octri-enum-deprecationslistenum schema

Marks individual enum values as deprecated. The list lines up with the schema's enum: a message or true deprecates the value in that position, and false leaves it alone, such as ["Use pro", false]. Go, Java, Kotlin, PHP, Rust, Ruby, Dart and Swift mark the member. TypeScript and Python enums are literal types, with no member to mark.

x-octri-deprecation-message: Use POST /v2/users instead.

See versioning.

Including and excluding

x-octri-skiptrue or list of languagesoperation

Leaves it out of the SDK, in every language or only the ones listed.

x-octri-model-skiptrue or list of languagesschema

Inlines the model rather than generating a named one.

x-octri-model-onlylist of languagesschema

Generates the named model only for the languages listed.

x-octri-skip: [php, ruby]

Types

x-octri-anytrueschema

Treats the value as open JSON: any in TypeScript and Go, serde_json::Value in Rust.

x-octri-empty-objecttrueschema

Treats it as an open map.

x-octri-override-schemaschemaschema

Replaces the schema with the one you give.

x-octri-consttrueschema

Accepted so a spec written for Stainless still parses, but it doesn't change the generated code yet.

x-octri-soft-requiredtrueparameter or property

Shows as required in the method signature, without being enforced by validation at runtime.

Pagination

x-pagination states how an operation pages, and x-pagination: false turns detection off. See setting it in your spec.

You can also mark the individual fields with x-octri-pagination-property.

Reliability

x-sdk-retry:
  maxAttempts: 2
  retryOn: [503]
x-sdk-timeout: 120000

Both go on an operation and override your project's settings for that method. Only the TypeScript SDK reads them so far: for every language, set the override on the endpoint in SDK Studio. See retries and timeouts.

Idempotency

Declare an idempotency header on the operation to tell the client your server deduplicates. It isn't an extension, just a normal header parameter. See making writes retry safely.

Applying extensions without editing your spec

If you can't change the spec, for example because it's generated by another team's framework, inject extensions with a spec transform:

{
  "command": "merge",
  "reason": "Model name reads better than the schema key",
  "args": {
    "target": "$.components.schemas.UserResponseDTO",
    "value": { "x-octri-model": "User" }
  }
}

Studio or spec?

Choose	When
SDK Studio	Non-engineers make the changes, or you want to preview the result first
Spec extensions	The spec is in version control and you want the settings reviewed with it
Transforms	You don't control the spec

Your spec needs no extensions at all to generate a good SDK. Start with Spec Audit, and add these only for what it can't express.