> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worksong.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Required columns and rules

> Make a column required, required only when another column says so, or limited to a range.

A board can hold its columns to **rules**. A rule stops a change that would leave a cell empty or out of range.

## The rules

| Rule | Meaning |
| - | - |
| Required | The cell can never be empty. Blank text and an empty Multi-select count as empty. |
| Required when | The cell cannot be empty while all the conditions hold. A condition is another column of the same board and the values that make it true, for example Stage is Won. You can set up to 5 conditions. |
| Range | A Number or Date column stays between a minimum and a maximum (both included). |

Formula, Lookup, AI, Created at and Updated at columns cannot be required, because Work fills them in.

## Set a rule

You need Manage on the board. Open **Column options** and choose **Rules**. The app offers always required, required when a Status or Multi-select column holds chosen labels, and a range. After you save, Work tells you how many rows already break the rule, for example "3 rows break this rule". The count also shows in the column's row.

A rule added to a board does not make old rows uneditable. Work checks a rule only when a change touches the guarded column, or a column in its condition. Saving the same value again is not held to it. A new item is checked against every rule.

## When a change is refused

The rule applies to every way of writing: the app, the API, Agents over MCP, automations, moves, copies and duplicates, imports and public forms. What you see depends on where the change came from:

* **In the app,** the sentence appears under the cell and your choice stays. When the rule is about another column, a **Set \<column>** button opens that column's editor. It saves the missing value and your change together.
* **Over the API,** you get a `422` with `code: "validation_rule_violated"` and a list of violations.
* **An automation** that sets a value is refused, and the item stays as it was.
* **A move, copy or duplicate** is judged by the destination board's rules, as a new item. If one item breaks a rule, the whole selection is refused.
* **An import into an existing board** is refused as a whole and names the row.
* **A public form** answers with a plain error. The person submitting never sees the board's rules.

A change to several cells, such as a paste or a fill, is judged as a whole on the item as it will be, so "Stage = Won" and "Contract = C-1" can be saved together.

If a rule depends on a column you cannot see, the refusal is one general sentence and does not name that column.

## API and Agents

* `PUT /v1/columns/{id}/rules` replaces a column's rules. An empty body clears them. Agents use `boardy_set_column_rules`, or pass `rules` to `boardy_create_column` and `boardy_update_column`.
* `GET /v1/boards/{boardId}/columns/rule-violations` (Read) lists, per column with rules, how many live items break it and a sample of 20 item ids. It reads up to 20,000 items; on a longer board the counts are "at least".

```json theme={null}
{ "required": true }
{ "requiredWhen": [{ "columnId": "<Stage column id>", "in": ["Won"] }] }
{ "min": "0", "max": "100" }
```

A bad definition returns `400` with `code: "invalid_column_rules"`. For example, a range on a Text column, a label that does not exist, or a column that depends on itself.

## Not yet

* The form builder does not warn you when a public form leaves out a required column. Every submission is then refused.
* The rules editor in the app offers conditions on Status and Multi-select columns. The API and MCP also accept Text, Number, Date and Person.

<sub>Source: `worksong-ai/worksong:services/work/docs/column-rules.md@956ab3b`. Docs version: Worksong 2.0 with Work 1.2.</sub>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.