# Formation schema reference

## Versions

Formations use schema version 1. API and protocol versions are in the
[runtime reference](/docs/next/runtime-reference#versions).

## Check a formation against the schema

Download the [JSON Schema](/docs/next/reference/organization.schema.json) and
the [offline contract](/docs/next/reference/organization.contract.json), then
run:

```sh
locust formation validate FILE
```

`validate` checks the schema and the rules. On the website, generated tables of
the offline commands, the root fields and the example files follow this text.


## Offline CLI operations

| Command | Input | Output | Purpose |
| --- | --- | --- | --- |
| `locust formation contract` | none | contract | Discover installed schema, operations, examples and verification boundaries |
| `locust formation schema` | none | json_schema | Print the authoring JSON Schema (raw JSON unless --json) |
| `locust formation examples` | none | example_catalog | List bundled authoring examples |
| `locust formation example` | example_name | formation | Print a bundled example (raw JSON unless --json) |
| `locust formation validate` | json_path_or_stdin | inspection | Validate a JSON document offline with structured diagnostics |
| `locust formation explain` | json_path_or_stdin | inspection | Explain effective rules and required bindings offline |
| `locust formation diff` | two_json_paths | semantic_diff | Compare normalized semantic definitions offline with hashes and JSON Pointer changes |
| `locust formation normalize` | json_path_or_stdin | formation_or_invalid_inspection | Print normalized semantic JSON (raw JSON unless --json) |

## Formation root fields

| Field | Required | Shape | Description |
| --- | --- | --- | --- |
| `context` | defaulted/optional | #/$defs/Context |  |
| `decisions` | defaulted/optional | #/$defs/DecisionRules |  |
| `flow` | defaulted/optional | object | Optional named stages and their prerequisite evidence. |
| `roles` | defaulted/optional | object |  |
| `schema_version` | yes | integer |  |
| `task_types` | defaulted/optional | object | Explicitly delegated alternatives to the default task rules. |
| `work` | defaulted/optional | #/$defs/WorkRules |  |

## Checked example downloads

- [open](/docs/next/examples/open.json): Members contribute and independently start work; authors declare completion.
- [coordinator](/docs/next/examples/coordinator.json): A coordinator offers work, reviews completion, selects contributions and closes the goal.
- [peer-review](/docs/next/examples/peer-review.json): Members independently start work; completion requires one review by another member.
- [independent-attempts](/docs/next/examples/independent-attempts.json): Authors complete independent attempts; a bound judge selects contributions.
- [review-panel](/docs/next/examples/review-panel.json): Completion requires two distinct reviews from the reviewer role, excluding the author.
- [pipeline](/docs/next/examples/pipeline.json): A draft stage needs one review by another member; a ship stage starts when the draft is complete.