@assert

guides/providing-services.md

@@ -939,6 +939,86 @@ Cross-service checks are not supported. It is expected that the associated entit
 The `@assert.target` check constraint relies on database locks to ensure accurate results in concurrent scenarios. However, locking is a database-specific feature, and some databases don't permit to lock certain kinds of objects. On SAP HANA, for example, views with joins or unions can't be locked. Do not use `@assert.target` on such artifacts/entities.
 :::
 
+### `@assert` <Beta/>
+
+Annotate an element with `@assert` to define an expression for more complex validations that need to be fulfilled before data gets persisted. If the validation should fail, the expression must return the error message to be sent to the client, or `null` if the validation passed.
+
+The returned error can be either a static message or a message key to support i18n. If a message key is used, the message is looked up in the message bundle of the service.
+[Learn more about localized messages](./i18n){.learn-more}
+
+The following example ensures that the `quantity` of the ordered book is validated against the actual `stock`. If there is not enough available in the stock, a static error message is returned.
+
+```cds
+entity Books : cuid {
+    title   : String;
+    stock   : Integer;
+}
+
+entity Orders : cuid {
+   Items    : Composition of many OrderItems
+                   on Items.parent = $self;
+}
+
+entity OrderItems : cuid {
+    parent    : Association to Orders;  
+    book      : Association to Books;
+    @assert: (case
+      when book.stock <= amount then 'Stock exceeded'
+    end)
+    quantity  : Integer;
+    amount    : Decimal(9, 2);
+}
+```
+
+Alternatively, the same condition can be simplified by using the ternary operator:
+
+```cds
+entity OrderItems : cuid {
+
+    @assert: ((book.stock <= amount) ? 'Stock exceeded' : null)
+    quantity  : Integer;
+}
+```
+
+By using multiple `when` sections, multiple conditions can be included in a single annotation. Each condition returns its own error message to precisely describe the error.
+
+```cds
+entity OrderItems : cuid {
+
+    @assert: (case
+      when book.stock = 0 then 'Stock is zero'
+      when book.stock <= amount then 'Stock exceeded'
+    end)
+    quantity  : Integer;
+}
+```
+
+With the help of the function `error(message, parameters, targets)`, it is possible to specify parameters as well as explicit target elements for the message. Each parameter can be represented by an expression.
+In its simplest form, this is the actual value of an entity field. The evaluating runtime will take care of replacing the placeholders in the message with the provided parameters.
+
+In the following example, it is expected that the error message with key `error.author.date` is defined to have two parameters which are filled with the concrete values of the elements `dateOfBirth` and `dateOfDeath`. The third parameter ensures that both fields are set as targets and thus marked erroneous.
+
+```cds
+entity Authors : cuid, managed {
+
+  @assert: (case 
+    when dateOfBirth > dateOfDeath then error('error.author.date', (dateOfBirth, dateOfDeath), (dateOfBirth, dateOfDeath)) 
+  end)
+  dateOfBirth  : Date;
+  dateOfDeath  : Date;
+}
+```
+
+Refer to [Expressions as Annotation Values](../cds/cdl.md#expressions-as-annotation-values) for detailed rules on expression syntax.
+
+::: info Expression Evaluation
+Expressions are evaluated *after* the request has been applied to the underlying datastore. The affected entities are the entities being part of the request and identified by their primary keys. The evaluating runtime constructs and executes statements with the annotation-provided expressions and the respective primary key values for the given entities. Depending on the structure and cardinality of the request data it can be one or more statements being executed.
+:::
+
+::: warning Limitations
+- Validations will only be enforced in `CREATE` and `UPDATE` statements that contain all key fields (including deep insert and deep update)
+- Only elements with simple types (like, `String`, `Integer`, `Boolean`) can be annotated with `@assert`. Elements typed with structured or arrayed types are not supported
+:::
 
 <div id="assertconstraints" />