SDKs
Spec transforms
Transforms rewrite the OpenAPI spec before generation. They are the escape hatch for anything Studio has no first-class control for, and unlike a hook they apply to every language at once.
Reach for them when the spec is the problem and you can't fix the spec at its source.
Anatomy
A transform is a command, a JSONPath target, and a payload.
| Field | Meaning |
|---|---|
command | update, append, merge, remove, move, copy |
reason | Why this exists. Surfaced in warnings; write it for the next person |
args.target | JSONPath target, or an array of them |
args.value | Payload for update / append / merge |
args.from, args.to | Source and destination for move / copy |
args.keys | Specific keys to delete for remove (else the whole node) |
args.template | When true, value is a {{value}} template string |
Commands
What they're for
The common case is injecting x-stainless-* or x-octri-* extensions that have no dedicated control:
| Goal | Transform |
|---|---|
| Rename a generated model | merge x-stainless-name onto the schema |
| Rename enum values | merge onto the enum schema |
| Mark an operation deprecated | Studio has a control for this; use that instead |
| Drop an endpoint from the spec | Studio's inclusion toggle is safer; use that instead |
Deprecation, inclusion, method names, and doc comments all have first-class per-endpoint controls. They're safer than a transform because they can't silently miss.
They fail quietly
Transforms are applied to the raw spec. A target that matches nothing does nothing, and the build succeeds. Rename a schema in your spec and a transform pointing at the old name stops applying, silently, until someone notices the model name reverted.
Re-check your transforms after any significant spec change, and write reason on every one so the next person knows what it was protecting.
Order matters
Transforms run in sequence. A remove that deletes a node makes a later transform targeting it a no-op. Keep the list short and ordered from broad to narrow.
When to fix the spec instead
Transforms are a patch over a spec you don't control. If you own the spec, fix it at source: the transform is invisible to everyone reading your OpenAPI document, and it's one more thing to keep in sync.
Most of what teams reach for a transform to paper over is a habit worth fixing upstream instead. Ten habits for writing great OpenAPI specs covers the ones that matter most downstream.