Add payload constraint option (api-platform#263)

* Add payload constraint option

For api-platform/core#1364

* Add ability to define payload fields

* Minor Markdown and wording fixes

* Update TOC

Author: pierre-H

core/validation.md

@@ -159,6 +159,33 @@ class Book
 }
 ```
 
+## Error Levels and Payload Serialization
+
+As stated in the [Symfony documentation](https://symfony.com/doc/current/validation/severity.html), you can use the payload field to define error levels.
+You can retrieve the payload field by setting the `serialize_payload_fields` option to `true` in the API Platform config:
+
+```yaml
+# app/config/config.yml
+
+api_platform:
+    validator:
+        serialize_payload_fields: true
+```
+
+Then, the serializer will return all payload values in the error response.
+
+If you want to serialize only some payload fields, define them in the config like this:
+
+```yaml
+# app/config/config.yml
+
+api_platform:
+    validator:
+        serialize_payload_fields: [ severity, anotherPayloadField ]
+```
+
+In this example, only `severity` and `anotherPayloadField` will be serialized.
+
 Previous chapter: [Serialization Groups and Relations](serialization-groups-and-relations.md)
 
 Next chapter: [Pagination](pagination.md)

index.md

@@ -50,6 +50,7 @@
 8.  [Validation](core/validation.md)
     1.  [Using Validation Groups](core/validation.md#using-validation-groups)
     2.  [Dynamic Validation Groups](core/validation.md#dynamic-validation-groups)
+    3.  [Error Levels and Payload Serialization](core/validation.md#error-levels-and-payload-serialization)
 9.  [Pagination](core/pagination.md)
     1.  [Disabling the Pagination](core/pagination.md#disabling-the-pagination)
     2.  [Changing the Number of Items per Page](core/pagination.md#changing-the-number-of-items-per-page)