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
| 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 | Short title, shown in the Rules settings. |
description | yes | text | One sentence: what the rule reports. |
category | yes | string | static, local-consistency, global-consistency or project. See Categories. |
scope | yes | string | What the checks run against: sequence, track, clip, effect or marker. See Scopes. |
severity | yes | string | info, warning or error. |
options | no | object | Configurable values, by name. See Option. |
checks | yes | array | At least one 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. |
data | no | object | Data attached to every diagnostic of the rule. |
Check
| Property | Required | Type | Meaning |
|---|---|---|---|
condition | yes | condition | When to report. |
message | yes | message | What to say. |
data | no | object | Data 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.
Condition
One of:
| Shape | Holds when |
|---|---|
{ "field", "operator", "value"? } | The comparison is true. See 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.
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.
Label
| Property | Required | Meaning |
|---|---|---|
field | yes | The field whose value picks the wording. |
values | yes | A message per value, keyed by the value as text ("true" for a boolean). |
Used as {labels.<name>} in messages. Guide: Labels.
Data entry
A field path ("clip.scale"), or a constant { "literal": value }. Guide: Data.
Texts
name and description are a string (English), or an object keyed by locale where en_US is required.
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.
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.