[Reference] document the `2.5` validation options

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes
| Applies to    | 2.5+
| Fixed tickets | part of #4094
We should later on add a reference to the cookbook article about the new validation API that is still to be written (see #4094).