feat: add API documentation for dataset validation (#1079)

Hey all, this is a proposal of how the dataset validation could be
handled in API.

We have decided, that no matter how many items in a request you send, if
at least one is not valid the whole request fails with `400 Bad
request`.

My proposal is to return our normal API error, but add "data" property
to the error object returned from API and in the data return
"invalidItems" which will list all validation errors for all invalid
items by index in the items array.

So for example if you send a request with 1000 items and 2 of them do
not have a required field. The response will look like this:

```json
{
  "error": {
    "type": "schema-validation-error",
    "message": "Schema validation failed",
    "data": {
        "invalidItems": {
          "4": ["name is required"],
          "124": ["name is required"],
         },
     }
  }
}
```

---------

Co-authored-by: Jaroslav Hejlek <[email protected]>

Author: gippy

sources/platform/api_v2/api_v2_reference.apib

@@ -3081,6 +3081,9 @@ The POST payload is a JSON object or a JSON array of objects to save into the da
 **IMPORTANT:** The limit of request payload size for the dataset is 5 MB. If the array exceeds the size,
 you'll need to split it into a number of smaller arrays.
 
+If the dataset has fields schema defined, the push request can potentialy fail with `400 Bad Request` if any item does not match the schema.
+In such case, nothing will be inserted into the dataset and the response will contain an error message with a list of invalid items and their validation errors.
+
 + Parameters
 
     + token:   `soSkq9ekdmfOslopH` (string, required) - API authentication token.
@@ -3099,9 +3102,6 @@ you'll need to split it into a number of smaller arrays.
               },
               {
                 "foo": "hotel"
-              },
-              {
-                "foo": "restaurant"
               }
             ]
 
@@ -3113,6 +3113,39 @@ you'll need to split it into a number of smaller arrays.
 
     + Attributes(object)
 
++ Response 400 (application/json)
+
+    + Headers
+
+            Location: https://api.apify.com/v2/datasets/WkzbQMuFYuamGv3YF/items
+
+    + Body
+
+            {
+                error: {
+                    type: 'schema-validation-error',
+                    message: 'Schema validation failed',
+                    data: {
+                        invalidItems: [
+                            {
+                                itemPosition: 0,
+                                validationErrors: [
+                                    {
+                                        instancePath: 'foo',
+                                        schemaPath: 'foo',
+                                        keyword: 'type',
+                                        params: {
+                                            type: 'string'
+                                        },
+                                        message: 'must be string'
+                                    }
+                                ]
+                            }
+                        ]
+                    }
+                }
+            }
+
 # Group Request queues
 
 This section describes API endpoints to manage request queues.