---
title: Stainless workspace schema | Stainless
description: Complete reference for the Stainless workspace file
---

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](https://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.