# JSON schema

The specification's machine-readable form is a set of JSON Schemas, draft 2020-12. They are published at the URLs in their `$id`, on this site, and are copied unchanged from the open source engine repository.

| Schema              | URL                                                                                                | Describes                                    |
| ------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| Manifest spec 1     | [`/schemas/v1/workbench.schema.json`](/schemas/v1/workbench.schema.json)                           | A spec 1 `workbench.yml`.                    |
| Manifest spec 0     | [`/schemas/v0/workbench.schema.json`](/schemas/v0/workbench.schema.json)                           | A frozen spec 0 `workbench.yml`.             |
| Event               | [`/schemas/events/v0/workbench-event.schema.json`](/schemas/events/v0/workbench-event.schema.json) | One normalized run event, `protocol: 0`.     |
| Outbox declaration  | [`/schemas/outcomes/v1/outbox.schema.json`](/schemas/outcomes/v1/outbox.schema.json)               | The optional `outcome.json` an agent writes. |
| Outcome             | [`/schemas/outcomes/v1/outcome.schema.json`](/schemas/outcomes/v1/outcome.schema.json)             | The immutable outcome manifest.              |
| Application receipt | [`/schemas/outcomes/v1/application.schema.json`](/schemas/outcomes/v1/application.schema.json)     | The mutable application state of an outcome. |

Each `$id` is `https://workbenches.dev/schemas/...` followed by the path above.

## Validate a manifest

`wb validate` parses a package and checks its local files against the schema for its `spec`:

```sh
wb validate .#core
wb validate owner/repository
```

A YAML manifest can also be checked with any draft 2020-12 validator after converting it to JSON. The schema alone does not check everything an engine checks: that `instructions`, `skills`, and `runner_config` exist inside the package, that paths stay inside the repository, and that the runner, runtimes, and model routes are supported.

## Spec 1 at a glance

The spec 1 schema allows no properties beyond those it names. Its required properties are `spec`, `version`, `name`, `runner`, `model`, `instructions`, and `runtimes`.

| Definition     | Shape                                                                                                                                                               |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`        | `id` (required, `lab/model`), `routes` (non-empty list of `{provider, model?}`).                                                                                    |
| `runtimes`     | At least one of `local` (object or null), `docker` (`image` required, `docker` optional), `e2b` (`image` required), `daytona` (`class` required, `image` optional). |
| `image`        | A non-empty string, or `{build, context?}`.                                                                                                                         |
| `requirements` | `os`, `arch`, `cpu`, `memory_gb`, `disk_gb`, `gpu`, all optional.                                                                                                   |
| `environment`  | `{required?: boolean}`, default `true`.                                                                                                                             |
| `workspace`    | `{required?: boolean, access?: "read-only" or "read-write"}`, defaults `true` and `read-only`.                                                                      |
| `docker`       | `{engine: {mode: "host"}}`.                                                                                                                                         |
| `mcp`          | `name` and `url` required, `transport` (`http`), `headers`.                                                                                                         |

Every field is described on [Spec 1 manifest](/docs/standard/manifest).

## Versioning

A released schema never changes meaning. A new manifest field needs a new spec number and a new schema beside the old one. The event protocol and outcomes schemas are versioned independently of the manifest: the event schema lives under `events/v0` for `protocol: 0`, and the outcome schemas under `outcomes/v1` for outcome `version: 1`.