# DSL reference

Every key of a Kaabist program, generated from the program JSON Schema.

A program is a JSON document validated by the [program JSON Schema](https://kaab.ist/schemas/program-1.json); every page here is generated from that schema, so a key exists in the reference exactly when it exists in the language. [Programs and versions](https://docs.kaab.ist/concepts/programs-and-versions) explains how a program runs.

## Document keys

| Key | Type | Description |
|---|---|---|
| `kaab` | `"1"` | The DSL major version the document is written in. Required, and currently always `"1"`. |
| `name` | `string` | The program's name, unique within your organisation: lowercase letters, digits and `-`, matching `^[a-z0-9][a-z0-9-]{1,62}$`. Required for stored programs and optional for an inline job. |
| `description` | `string` | A free-text description of what the program does, up to 1,000 characters. |
| `inputs` | `map of "string" \| "number" \| "boolean" \| "secret" \| "enum" or object` | The values a job supplies when it runs the program, as a map from input name to an input definition or a bare type string such as `"string"`. Names match `^[a-zA-Z_][a-zA-Z0-9_]{0,63}$` (lint `E008`) and are read in templates as `{{inputs.<name>}}`. |
| `options` | `object` | How the program runs: tier, region, proxy, session, browser settings and budgets. Options a job sends override these key by key. |
| `landmarks` | `map of condition` | Named conditions that identify pages, referenced elsewhere with `{ "landmark": "<name>" }`. The names `login_page` and `logged_in` are reserved: diagnose and session probes use them to recognise a sign-in page and a signed-in page. |
| `steps` | `steps` | The ordered list of steps the program runs, at least 1 and at most 200 counting nested steps, with control blocks nested at most 3 deep (lint `E012`). Each step carries exactly one action or control key. |
| `extract` | `extract` | A top-level extract schema. When no top-level `extract` step writes `data`, it is appended as the final step. |
| `policies` | `object` | Job-wide policies: strict validation, raw values in the result, and what to do about expired sessions, captchas and screenshots. |

## Parts

| Part | What it covers |
|---|---|
| [Inputs](https://docs.kaab.ist/reference/dsl/inputs) | What a program takes when a job starts |
| [Options](https://docs.kaab.ist/reference/dsl/options) | Region, tier, proxy, session, budgets, canary |
| [Policies](https://docs.kaab.ist/reference/dsl/policies) | What happens on validation failures, captchas, expired sessions |
| [Steps](https://docs.kaab.ist/reference/dsl/steps) | The 26 actions and the keys every step takes |
| [Conditions](https://docs.kaab.ist/reference/dsl/conditions) | Landmarks, `expect`, `if`, `when`, `wait_for` |
| [Targets](https://docs.kaab.ist/reference/dsl/targets) | How an element is located |
| [Fields](https://docs.kaab.ist/reference/dsl/fields) | Extract field options: locators, types, validation |
| [Assertions](https://docs.kaab.ist/reference/dsl/assertions) | `$asserts` across extracted fields |
| [Transforms](https://docs.kaab.ist/reference/dsl/transforms) | Text transforms applied before parsing |
| [Lint codes](https://docs.kaab.ist/reference/dsl/lint) | What `POST /programs/lint` reports |