Stainless workspace schema

The Stainless workspace file declares the workspace that the CLI and Stainless Language Server operate on. Create this file by running stl init in your project directory.

{
  "project": "acme-api",
  "openapi_spec": "./openapi.json",
  "stainless_config": "./stainless.yml",
  "targets": {
    "typescript": {
      "output_path": "../sdks/acme-api-typescript"
    },
    "python": {
      "output_path": "../sdks/acme-api-python"
    }
  }
}

File location

The workspace file can be located at either:

• .stainless/workspace.json (recommended)
• stainless-workspace.json (legacy)

When you run stl commands or open files in an editor with the Stainless Language Server, the tooling searches up the directory tree to find a workspace file and uses it to determine which project to work on and where files are located.

Schema

The workspace file uses JSON format with the following fields:

Key	Description
project?	string The name of your Stainless project. This corresponds to the project name in your Stainless account at app.stainless.com.
openapi_spec?	string Relative path from the workspace file to your OpenAPI specification file. Supports both JSON and YAML formats.
stainless_config?	string Relative path from the workspace file to your Stainless configuration file.
targets?	Record<string, WorkspaceTarget> Defines where SDK output files should be written for each target language. Each key is a target name (e.g., typescript, python).

WorkspaceTarget

Key	Description
output_path	string Relative path from the workspace file to the directory where the SDK should be generated.

Workspace discovery

The Stainless CLI and Language Server discover workspaces in two ways:

Explicit workspace

When you have a workspace file (.stainless/workspace.json or stainless-workspace.json), the tooling walks up the directory tree from your current location to find it. The workspace file explicitly declares:

• Which project you are working on
• Where your OpenAPI spec is located
• Where your Stainless config is located

This is the recommended approach for most projects.

Implicit workspace

If no workspace file is found, the tooling attempts to discover a workspace implicitly by looking for:

• An openapi.yml or openapi.json file
• A *.stainless.yml file

in the same directory. This allows quick experimentation without setting up a full workspace.