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

# Validation Rules

> Declare the conditions a record must meet before it can be saved.

## Overview

A validation rule is a condition on a record. When it evaluates to false, Twenty rejects the record and shows the rule's message.

> [!NOTE]
>
> Validation rules are only enforced in workspaces where the feature is available.

Define a rule with `defineValidationRule` from `twenty-sdk/define`:

```ts filename="src/validation-rules/invoice-has-amount.ts" theme={null}
import { defineValidationRule, ruleExpression } from 'twenty-sdk/define';

import { INVOICE_UNIVERSAL_IDENTIFIER } from '../objects/invoice.object';

const { and, field, gt, isNonEmptyString } = ruleExpression;

export default defineValidationRule({
  universalIdentifier: '8d3f2c6e-1b7a-4f0e-9c52-6a1e0d4b7f31',
  objectUniversalIdentifier: INVOICE_UNIVERSAL_IDENTIFIER,
  name: 'Invoice has an amount',
  expression: and(gt(field('amount'), 0), isNonEmptyString(field('reference'))),
  message: 'An invoice needs an amount and a reference',
});
```

You can also scaffold one with the CLI:

```bash theme={null}
twenty app add validation-rule --name invoice-has-amount --object <object-uuid>
```

| Property | Required | Description |
| - | - | - |
| `universalIdentifier` | Yes | Stable identifier of the rule |
| `objectUniversalIdentifier` | Yes | The object the rule applies to. It can be an object of your app or a standard object. |
| `name` | Yes | Name shown in settings |
| `expression` | Yes | A `ruleExpression` or a string |
| `message` | Yes | Message shown when the rule fails |
| `errorFieldUniversalIdentifier` | No | Field the message is attached to. It must belong to the rule's object. |
| `description` | No | Longer description |
| `icon` | No | Icon name |

## Writing expressions

`ruleExpression` provides:

* `field('name')` reads a field, and `field('company.employees')` reads a field through a many-to-one relation.
* `now` is the current date and time.
* `and`, `or` and `not` combine conditions.
* `eq`, `notEq`, `gt`, `gte`, `lt` and `lte` compare values.
* `add`, `subtract`, `multiply` and `divide` compute values.
* `isIn(field('stage'), ['NEW', 'WON'])` checks a value against a list.
* Functions such as `isNonEmptyString` and `isDefined`.

The builder outputs a plain string, which is what [`twenty app pull`](https://docs.twenty.com/developers/extend/apps/operations/cli) writes back. You can write that string directly:

```ts theme={null}
expression: 'amount > 0 and isNonEmptyString(reference)',
```

Strings use `and`, `or`, `not`, `==`, `!=`, `<`, `<=`, `>`, `>=`, `+`, `-`, `*`, `/` and `in [...]`, not `&&` or `||`. Text goes in single or double quotes.

A rule can read fields you declare, and the [system fields](https://docs.twenty.com/developers/extend/apps/data/system-fields.md) Twenty provisions, such as `createdAt`. The CLI checks expressions against your app's own objects. On an object outside your app, it only checks the syntax and the server checks the fields at sync time.

## Fields that become unavailable

| Situation | Result |
| - | - |
| Your app removes a field its rule reads | The sync fails with an error naming the rule and the field |
| A workspace deactivates a field outside your app | The sync succeeds and the rule stays off |
| A workspace deletes a field outside your app, and your rule's expression is unchanged | The sync succeeds and the rule stays off |
| A workspace renames a field outside your app | The sync succeeds and keeps the rule under the new name, which `twenty app pull` writes back |
| A new or edited rule names a field that doesn't exist | The sync fails |
| A workspace deletes the rule's error field | The sync succeeds and the rule is no longer attached to that field |

A sync keeps an existing rule's `isActive`, so a rule a workspace admin turned off stays off. Only new rules start on.


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