Skip to content

The open alternative to Salesforce, designed for AI.

3.8 KB
Raw Blame
---
title: Validation Rules
description: Declare the conditions a record must meet before it can be saved.
---

import { PageBanner } from "/snippets/page-banner.mdx"

## 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.
</Note>

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

```ts filename="src/validation-rules/invoice-has-amount.ts"
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
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`](/developers/extend/apps/operations/cli) writes back. You can write that string directly:

```ts
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](/developers/extend/apps/data/system-fields) 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.

<PageBanner illustration="dev-contribute" />