less clutter

Author: danjoa

guides/providing-services.md

@@ -772,55 +772,48 @@ Here's an overview table:
 -  Pessimistic locking is not supported by SQLite. H2 supports exclusive locks only.
 :::
 
-## Input Validation
 
-CAP runtimes provide generic input validation for incoming requests out of the box, based on the data types and constraints defined in CDS models. You can add custom input validation by...
+## Custom Logic
 
-- [Declarative Constraints](./services/constraints) with the following annotations:
-  - [`@assert`](./services/constraints#assert), incl. derivates:
-    - [`@assert.format`](./services/constraints#assert-format)
-    - [`@assert.range`](./services/constraints#assert-range)
-    - [`@assert.target`](./services/constraints#assert-target)
-  - [`@mandatory`](./services/constraints#mandatory)
-  - [`@readonly`](./services/constraints#readonly)
-- [Programmatic Validations](#custom-logic) in custom event handlers
+As most standard tasks and use cases are covered by [generic service providers](#generic-providers), the need to add service implementation code is greatly reduced and minified, and hence the quantity of individual boilerplate coding.
 
-> [!tip] 
-> Prefer declarative constraints over programmatic validations wherever possible, as they require no implementation coding and are automatically served by CAP runtimes in optimized ways.
+The remaining cases that need custom handlers, reduce to real custom logic, specific to your domain and application, such as:
 
-## [Constraints](services/constraints)
+- Domain-specific programmatic [Validations](#input-validation)
+- Augmenting result sets, for example to add computed fields for frontends
+- Programmatic [Authorization Enforcements](/guides/security/authorization#enforcement)
+- Triggering follow-up actions, for example calling other services or emitting outbound events in response to inbound events
+- And more... In general, all the things not (yet) covered by generic handlers
 
-Declarative constraints allow you to express conditions using CXL expressions that are validated automatically whenever data is written, greatly reducing the need for extensive custom code for input validation.
 
-::: tip Read the guide
-Find additional information about constraints in this guide:
-[→ **_Constraints_**](services/constraints)
-:::
 
-## [Status-Transition Flows](services/status-flows)
+### Declarative Custom Logic
 
-Status-transition flows ensure transitions are explicitly modeled, validated, and executed in a controlled and reliable way, thereby eliminating the need for extensive custom coding.
+CAP supports various declarative techniques to express custom logic without coding, in particular for input validation and status-transition flows.
 
-::: tip Read the guide
-Find additional information about modeling status-transition flows in this guide:<br>
-[&rarr; **_Status-Transition Flows_**](services/status-flows)
-:::
+#### Status Transition Flows
 
-## Custom Logic
+- [Status-Transition Flows](./services/status-flows.md) ensure transitions are explicitly modeled, validated, and executed in a controlled and reliable way, thereby eliminating the need for extensive custom coding.
 
 
+#### Input Validation
 
-As most standard tasks and use cases are covered by [generic service providers](#generic-providers), the need to add service implementation code is greatly reduced and minified, and hence the quantity of individual boilerplate coding.
+- [Declarative Constraints](./services/constraints) allow to annotate your models and have the respective checks still be executed and enforced by generic runtimes, with the following annotations:
 
-The remaining cases that need custom handlers, reduce to real custom logic, specific to your domain and application, such as:
+  - [`@assert`](./services/constraints#assert), incl. derivates:
+    - [`@assert.format`](./services/constraints#assert-format)
+    - [`@assert.range`](./services/constraints#assert-range)
+    - [`@assert.target`](./services/constraints#assert-target)
+  - [`@mandatory`](./services/constraints#mandatory)
+  - [`@readonly`](./services/constraints#readonly)
+
+
+> [!tip] 
+> Prefer declarative constraints over programmatic validations wherever possible, as they require no implementation coding and are automatically served by CAP runtimes in optimized ways.
 
-- Domain-specific programmatic [Validations](#input-validation)
-- Augmenting result sets, for example to add computed fields for frontends
-- Programmatic [Authorization Enforcements](/guides/security/authorization#enforcement)
-- Triggering follow-up actions, for example calling other services or emitting outbound events in response to inbound events
-- And more... In general, all the things not (yet) covered by generic handlers
 
 
+### Custom Service Providers
 
 **In Node.js**, the easiest way to add custom implementations for services is through equally named _.js_ files placed next to a service definition's _.cds_ file:
 

guides/services/constraints.md

@@ -243,7 +243,7 @@ annotate TravelService.Travels with {
 
 
 
-### `@assert .format`
+### `@assert.format`
 
 Allows you to specify a regular expression string (in ECMA 262 format in CAP Node.js and java.util.regex.Pattern format in CAP Java) that all string input must match.
 
@@ -254,7 +254,7 @@ entity Foo {
 ```
 
 
-### `@assert .range`
+### `@assert.range`
 
 Allows you to specify `[ min, max ]` ranges for elements with ordinal types — that is, numeric or date/time types. For `enum` elements, `true` can be specified to restrict all input to the defined enum values.
 
@@ -287,32 +287,9 @@ Support for open intervals and infinity is available for CAP Node.js since `@sap
 
 
 
-### `@assert .target`
+### `@assert.target`
 
-Annotate a [managed to-one association](../../cds/cdl#managed-associations) of a CDS model entity definition with the
-`@assert.target` annotation to check whether the target entity referenced by the association (the reference's target)
-exists. In other words, use this annotation to check whether a non-null foreign key input in a table has a corresponding
-primary key in the associated/referenced target table.
-
-You can check whether multiple targets exist in the same transaction. For example, in the `Books` entity, you could
-annotate one or more managed to-one associations with the `@assert.target` annotation. However, it is assumed that
-dependent values were inserted before the current transaction. For example, in a deep create scenario, when creating a
-book, checking whether an associated author exists that was created as part of the same deep create transaction isn't
-supported, in this case, you will get an error.
-
-The `@assert.target` check constraint is meant to **validate user input** and not to ensure referential integrity.
-Therefore only `CREATE`, and `UPDATE` events are supported (`DELETE` events are not supported). To ensure that every
-non-null foreign key in a table has a corresponding primary key in the associated/referenced target table
-(ensure referential integrity), the [`@assert.integrity`](../databases#database-constraints) constraint must be used instead.
-
-If the reference's target doesn't exist, an HTTP response
-(error message) is provided to HTTP client applications and logged to stdout in debug mode. The HTTP response body's
-content adheres to the standard OData specification for an error
-[response body](https://docs.oasis-open.org/odata/odata-json-format/v4.01/cs01/odata-json-format-v4.01-cs01.html#sec_ErrorResponse).
-
-#### Example
-
-Add `@assert.target` annotation to the service definition as previously mentioned:
+Annotate a [managed to-one association](../../cds/cdl#managed-associations) with `@assert.target` to check whether the target entity referenced by the association (the reference's target) exists for a given input.
 
 ```cds
 entity Books {
@@ -328,7 +305,19 @@ entity Authors {
 }
 ```
 
-**HTTP Request** — *assume that an author with the ID `"796e274a-c3de-4584-9de2-3ffd7d42d646"` doesn't exist in the database*
+You can check whether multiple targets exist in the same transaction. For example, in the `Books` entity, you could
+annotate one or more managed to-one associations with the `@assert.target` annotation. However, it is assumed that
+dependent values were inserted before the current transaction. For example, in a deep create scenario, when creating a book, checking whether an associated author exists that was created as part of the same deep create transaction isn't supported, in this case, you will get an error.
+
+The `@assert.target` check constraint is meant to **validate user input** and not to ensure referential integrity.
+Therefore only `CREATE`, and `UPDATE` events are supported (`DELETE` events are not supported). To ensure that every
+non-null foreign key in a table has a corresponding primary key in the associated/referenced target table
+(ensure referential integrity), the [`@assert.integrity`](../databases#database-constraints) constraint must be used instead.
+
+If the reference's target doesn't exist, an HTTP response
+(error message) is provided to HTTP client applications and logged to stdout in debug mode. The HTTP response body's
+content adheres to the standard OData specification for an error
+[response body](https://docs.oasis-open.org/odata/odata-json-format/v4.01/cs01/odata-json-format-v4.01-cs01.html#sec_ErrorResponse).
 
 ```http
 POST Books HTTP/1.1

menu.md

@@ -24,9 +24,9 @@
 
   ### [Core Concepts](guides/providing-services#introduction)
   ### [Service Definitions](guides/providing-services#service-definitions)
-  ### [Served out-of-the-box](guides/providing-services#generic-providers)
-  ### [Constraints](guides/services/constraints)
+  ### [Served Out-of-the-Box](guides/providing-services#generic-providers)
   ### [Status Flows](guides/services/status-flows)
+  ### [Constraints](guides/services/constraints)
   ### [Custom Logic](guides/providing-services#custom-logic)
   ### [Actions & Functions](guides/providing-services#actions-functions)
   ### [Status-Transition Flows](guides/providing-services#status-transition-flows)