add info to api docs

Author: katacek

apify-api/openapi/components/schemas/datasets/CreateDatasetResponseError.yaml renamed to apify-api/openapi/components/schemas/datasets/PutItemResponseError.yaml

@@ -1,4 +1,4 @@
-title: Createdatasetresponseerror
+title: PutItemResponseError
 required:
   - error
 type: object

apify-api/openapi/components/schemas/datasets/errorDataset.yaml

@@ -1,12 +1,53 @@
-title: error
-required:
-  - type
-  - message
 type: object
 properties:
-  type:
-    type: string
-    example: schema-validation-error
-  message:
-    type: string
-    example: 'Schema validation failed'
+  error:
+    type: object
+    properties:
+      type:
+        type: string
+        description: The type of the error.
+        example: "schema-validation-error"
+      message:
+        type: string
+        description: A human-readable message describing the error.
+        example: "Schema validation failed"
+      data:
+        type: object
+        properties:
+          invalidItems:
+            type: array
+            description: A list of invalid items in the received array of items.
+            items:
+              type: object
+              properties:
+                itemPosition:
+                  type: number
+                  description: The position of the invalid item in the array.
+                  example: 2
+                validationErrors:
+                  type: array
+                  description: A complete list of AJV validation error objects for the invalid item.
+                  items:
+                    type: object
+                    properties:
+                      instancePath:
+                        type: string
+                        description: The path to the instance being validated.
+                      schemaPath:
+                        type: string
+                        description: The path to the schema that failed the validation.
+                      keyword:
+                        type: string
+                        description: The validation keyword that caused the error.
+                      message:
+                        type: string
+                        description: A message describing the validation error.
+                      params:
+                        type: object
+                        description: Additional parameters specific to the validation error.
+        required:
+          - invalidItems
+    required:
+      - type
+      - message
+      - data

apify-api/openapi/paths/datasets/datasets.yaml

@@ -106,6 +106,7 @@ post:
     Keep in mind that data stored under unnamed dataset follows [data retention period](https://docs.apify.com/platform/storage#data-retention).
     It creates a dataset with the given name if the parameter name is used.
     If a dataset with the given name already exists then returns its object.
+
   operationId: datasets_post
   parameters:
     - name: name
@@ -143,25 +144,6 @@ post:
               actId: null
               actRunId: null
               fields: []
-    '400':
-      description: ''
-      headers: {}
-      content:
-        application/json:
-          schema:
-            allOf:
-              - $ref: >-
-                  ../../components/schemas/datasets/Createdatasetresponseerror.yaml
-              - example:
-                  error:
-                    type: schema-validation-error
-                    message: >-
-                      Schema validation failed
-          example:
-            error:
-              type: schema-validation-error
-              message: >-
-                Schema validation failed
   deprecated: false
   x-legacy-doc-urls:
     - https://docs.apify.com/api/v2#/reference/datasets/dataset-collection/create-dataset

apify-api/openapi/paths/datasets/datasets@{datasetId}@items.yaml

@@ -478,6 +478,10 @@ post:
     The POST payload is a JSON object or a JSON array of objects to save into the dataset.
 
 
+    If the data you attempt to store in the dataset is invalid (meaning any of the items received by the API fails the validation), the whole request is discarded and the API will return a response with status code 400.
+    For more information about dataset schema validation, see [Dataset schema](https://docs.apify.com/platform/actors/development/actor-definition/dataset-schema/validation).
+
+
     **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.
   operationId: dataset_items_post
   parameters:
@@ -523,6 +527,35 @@ post:
             type: object
             example: {}
           example: {}
+    '400':
+      description: ''
+      headers: {}
+      content:
+        application/json:
+            schema:
+                allOf:
+                - $ref: >-
+                    ../../components/schemas/datasets/PutItemResponseError.yaml
+                - example:
+                    error:
+                        type: schema-validation-error
+                        message: >-
+                            Schema validation failed
+            example:
+                error:
+                type: schema-validation-error
+                message: >-
+                    Schema validation failed
+                data:
+                    invalidItems:
+                        - itemPosition: 2
+                        - validationErrors:
+                            instancePath: /1/stringField
+                            schemaPath: /items/properties/stringField/type
+                            keyword: type
+                            params:
+                                type: string
+                            message: 'must be string'
   deprecated: false
   x-legacy-doc-urls:
     - https://docs.apify.com/api/v2#/reference/datasets/item-collection/put-items