# Rule file (/docs/reference/rule-file)

Every property of a rule file.



A rule file is a JSON object saved as `<id>.rule.json`. Unknown properties are errors, so a typo never silently disables part of a rule.

## Rule [#rule]

| Property        | Required | Type           | Meaning                                                                                                                                          |
| :-------------- | :------- | :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| `formatVersion` | yes      | `1`            | Version of the format. Always `1`.                                                                                                               |
| `id`            | yes      | string         | Stable identifier: lower-case letters and digits in words joined by hyphens (`^[a-z0-9]+(-[a-z0-9]+)*$`). Never changes once the rule is in use. |
| `name`          | yes      | [text](#texts) | Short title, shown in the Rules settings.                                                                                                        |
| `description`   | yes      | [text](#texts) | One sentence: what the rule reports.                                                                                                             |
| `category`      | yes      | string         | `static`, `local-consistency`, `global-consistency` or `project`. See [Categories](#categories).                                                 |
| `scope`         | yes      | string         | What the checks run against: `sequence`, `track`, `clip`, `effect` or `marker`. See [Scopes](/docs/reference/scopes).                            |
| `severity`      | yes      | string         | `info`, `warning` or `error`.                                                                                                                    |
| `options`       | no       | object         | Configurable values, by name. See [Option](#option).                                                                                             |
| `checks`        | yes      | array          | At least one [check](#check).                                                                                                                    |
| `matching`      | no       | string         | `first` (default): an item gets the diagnostic of the first check that holds. `all`: one diagnostic per check that holds.                        |
| `labels`        | no       | object         | Wording chosen by a field's value, by name. See [Label](#label).                                                                                 |
| `data`          | no       | object         | [Data](#data-entry) attached to every diagnostic of the rule.                                                                                    |

## Check [#check]

| Property    | Required | Type                    | Meaning                                              |
| :---------- | :------- | :---------------------- | :--------------------------------------------------- |
| `condition` | yes      | [condition](#condition) | When to report.                                      |
| `message`   | yes      | [message](#messages)    | What to say.                                         |
| `data`      | no       | object                  | [Data](#data-entry) merged over the rule's `data`.   |
| `scope`     | no       | string                  | Runs this check on another scope than the rule's.    |
| `location`  | no       | field path              | A number field, in ticks: the diagnostic's position. |

Guide: [Checks](/docs/guides/checks).

## Condition [#condition]

One of:

| Shape                               | Holds when                                                          |
| :---------------------------------- | :------------------------------------------------------------------ |
| `{ "field", "operator", "value"? }` | The comparison is true. See [Operators](/docs/reference/operators). |
| `{ "all": [condition, …] }`         | Every condition holds.                                              |
| `{ "any": [condition, …] }`         | At least one condition holds.                                       |
| `{ "not": condition }`              | The condition does not hold.                                        |

A `value` is a literal (number, string, boolean, or a list for `in` / `notIn`, a pair for `between`) or a field reference `{ "field": "options.max" }`. Guide: [Conditions](/docs/guides/conditions).

## Option [#option]

| Property      | Required | Meaning                                                          |
| :------------ | :------- | :--------------------------------------------------------------- |
| `type`        | yes      | `number`, `string`, `boolean`, `number[]`, `string[]` or `json`. |
| `default`     | yes      | A value of that type.                                            |
| `description` | no       | What the option changes.                                         |

Read as the field `options.<name>`. Guide: [Options](/docs/guides/options).

## Label [#label]

| Property | Required | Meaning                                                                                |
| :------- | :------- | :------------------------------------------------------------------------------------- |
| `field`  | yes      | The field whose value picks the wording.                                               |
| `values` | yes      | A [message](#messages) per value, keyed by the value as text (`"true"` for a boolean). |

Used as `{labels.<name>}` in messages. Guide: [Labels](/docs/guides/labels).

## Data entry [#data-entry]

A field path (`"clip.scale"`), or a constant `{ "literal": value }`. Guide: [Data](/docs/guides/data).

## Texts [#texts]

`name` and `description` are a string (English), or an object keyed by [locale](/docs/guides/messages#translations) where `en_US` is required.

## Messages [#messages]

A message is a template with `{field.path}` placeholders, as a string (English) or an object keyed by locale with `en_US` required. Each template is a string, or plural forms: `{ "count": "<number field>", "one"?, "few"?, "many"?, "other" }`. Guide: [Messages](/docs/guides/messages).

## Categories [#categories]

| Category             | The rule…                                                                                           |
| :------------------- | :-------------------------------------------------------------------------------------------------- |
| `static`             | inspects facts of one item: an offline clip, a disabled clip, a gap.                                |
| `local-consistency`  | compares a clip with nearby clips.                                                                  |
| `global-consistency` | compares a clip with a broader population of the sequence.                                          |
| `project`            | checks requirements for the whole sequence: required tracks, markers or effects, sequence settings. |

Rules are listed by category, then id.