Transform API Descriptions
Generate public, private, staging, and production variants from one API description with scalar document transform. Filter internal operations, change server URLs, and edit documentation metadata without changing the source file.
Transform accepts local files and URLs containing JSON or YAML OpenAPI 2.0, OpenAPI 3.0–3.2, or AsyncAPI 2.x/3.x descriptions. It preserves the OpenAPI or AsyncAPI version. Choose JSON or YAML serialization with the output filename.
Quick start
Create a transformation configuration, then pass it alongside your source and an explicit output path:
scalar document transform api.yaml --config public-production.yaml --output public-api.yaml
Both --config and --output are required. Configuration is a JSON or YAML file containing ordered steps; it is not executable code. See Getting Started to install the Scalar CLI.
Generate public production and private staging variants
This example starts with one API description containing a public endpoint, an internal endpoint, and internal metadata. The public production output removes internal content. The private staging output keeps it and uses a staging server.
Source: api.yaml
Mark an operation with x-internal: true to make it eligible for filtering. You can also mark an entire path or channel as internal.
openapi: 3.1.0
info:
title: Pet Platform API
version: 1.0.0
x-internal-notes: Contact the platform team for admin access.
servers:
- url: http://localhost:3000
paths:
/pets:
get:
operationId: listPets
responses:
'200':
description: A list of pets
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Pet'
/admin/status:
get:
operationId: getAdminStatus
x-internal: true
responses:
'200':
description: Internal service status
content:
application/json:
schema:
$ref: '#/components/schemas/AdminStatus'
components:
schemas:
Pet:
type: object
properties:
id:
type: string
name:
type: string
AdminStatus:
type: object
properties:
queueDepth:
type: integer
Public production configuration: public-production.yaml
Remove internal operations and explicitly delete the internal notes. Then replace the root server list and title. removeUnusedComponents: true removes the AdminStatus schema once no remaining operation references it.
version: 1
steps:
- type: remove-internal-operations
- type: remove
pointer: /info/x-internal-notes
- type: set
pointer: /servers
value:
- url: https://api.example.com
- type: set
pointer: /info/title
value: Public Pet API
removeUnusedComponents: true
Private staging configuration: private-staging.yaml
Omit remove-internal-operations to keep both endpoints. This configuration also keeps the internal notes and changes the root server list and title.
version: 1
steps:
- type: set
pointer: /servers
value:
- url: https://staging-api.example.com
- type: set
pointer: /info/title
value: Internal Pet API - Staging
removeUnusedComponents: true
Generate both outputs
Run both commands from the directory containing the source and configuration files:
scalar document transform api.yaml \
--config public-production.yaml \
--output public-api.yaml
scalar document transform api.yaml \
--config private-staging.yaml \
--output private-api.yaml
Public production output: public-api.yaml
The output contains only /pets and its Pet schema. The admin operation, AdminStatus schema, and internal notes are removed.
openapi: 3.1.0
info:
title: Public Pet API
version: 1.0.0
servers:
- url: https://api.example.com
paths:
/pets:
get:
operationId: listPets
responses:
"200":
description: A list of pets
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Pet"
components:
schemas:
Pet:
type: object
properties:
id:
type: string
name:
type: string
Private staging output: private-api.yaml
The output keeps both endpoints, both schemas, and the internal notes. The server points to staging. The original api.yaml remains unchanged after both commands.
openapi: 3.1.0
info:
title: Internal Pet API - Staging
version: 1.0.0
x-internal-notes: Contact the platform team for admin access.
servers:
- url: https://staging-api.example.com
paths:
/pets:
get:
operationId: listPets
responses:
"200":
description: A list of pets
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Pet"
/admin/status:
get:
operationId: getAdminStatus
x-internal: true
responses:
"200":
description: Internal service status
content:
application/json:
schema:
$ref: "#/components/schemas/AdminStatus"
components:
schemas:
Pet:
type: object
properties:
id:
type: string
name:
type: string
AdminStatus:
type: object
properties:
queueDepth:
type: integer
Transformation configuration
version must be 1. steps is an array applied in the order listed. removeUnusedComponents defaults to false.
| Step | Behavior |
|---|---|
remove-internal-operations |
Remove operations marked x-internal: true, including operations under internal paths or channels. |
set |
Add or replace the value at pointer with value. |
remove |
Delete the existing value at pointer. |
Remove internal operations
For OpenAPI 3.x, filtering covers paths, webhooks, callbacks, and reusable components/pathItems, including when component pruning is disabled. For OpenAPI 2.0, it covers paths. For AsyncAPI 2.x, it covers channel publish and subscribe operations; for AsyncAPI 3.x, it covers operations and internal channels. Matching no internal operations is a successful no-op.
Filtering internal operations does not remove every form of confidential content. Explicitly remove private metadata, descriptions, and examples, as the example does for /info/x-internal-notes.
Edit values with JSON Pointers
A pointer identifies an exact location. Escape / inside a key as ~1, and ~ as ~0. For example, the server list of the /pets path is /paths/~1pets/servers.
set replaces an entire value; it does not merge objects or append to arrays. The parent must already exist, and array indices must already exist. remove must match an existing target. Replacing the document root and using prototype-related pointer segments are rejected.
Remove unused components
Set removeUnusedComponents: true to prune reusable content after all steps run. Pruning follows references, security scheme requirements, and discriminator mappings, and preserves reachable cycles. AsyncAPI 3.x channels are retained through their operations.
With the default false, unused schemas and other reusable content remain in the output. Internal operations in OpenAPI components/pathItems are still filtered.
Configure servers for other formats
The example replaces the root OpenAPI 3.x /servers array. Other document formats use different fields:
| Format | Configuration |
|---|---|
| OpenAPI 2.0 | Use set steps for /host, /basePath, and /schemes, such as staging.example.com, /v1, and [https]. |
| AsyncAPI 2.x | Set /servers to a map, such as {staging: {url: staging.example.com, protocol: amqp}}. |
| AsyncAPI 3.x | Set /servers to a map, such as {staging: {host: staging.example.com, protocol: amqp}}. |
Replacing the root server configuration leaves path-, operation-, and channel-level overrides in place. Edit those explicitly if they also need to change. AsyncAPI 2.x channel server-name lists must name entries in the replacement map; AsyncAPI 3.x channel server references must still resolve.
Output and failure behavior
Use an output filename ending in .json, .yaml, or .yml. Parent directories must already exist. Input, configuration, and referenced source files cannot be overwritten, including through symbolic links or hard links. Distinct existing output files must be writable.
Use --output - to print the transformed document to stdout in the source's JSON or YAML serialization. Diagnostics go to stderr, so stdout stays parseable:
scalar document transform api.yaml --config public-production.yaml --output -
The command loads and checks source references, bundles external references, applies ordered steps to a copy, optionally prunes components, validates references and the resulting description, then serializes and writes the output.
Invalid configurations, missing pointer targets, unresolved references, or invalid final descriptions fail with a nonzero exit status before replacing the destination. Source references must resolve even if a later step would remove the content that references them. There is no incomplete-output mode.
Regular output files are replaced atomically, preserving ownership and permissions. If ownership transfer is denied for a shared writable file, it is updated in place to preserve ownership; that fallback is not atomic. Source formatting and YAML comments are not preserved.
For reproducible outputs, keep the source, configuration, referenced content, and CLI version fixed. Pin remote content when using URLs. This configuration is specific to the transform command; it is not an OpenAPI Overlay or a plugin API.
What did you think of this content?