Added explanation text to clarify the purpose.

src/PSR7/Validators/BodyValidator/MultipartValidator.php

@@ -291,6 +291,23 @@ private function validateServerRequestMultipart(
 
         $files = $this->normalizeFiles($message->getUploadedFiles());
 
+        // The PHP kernel separates file data (binary) from body data so it's
+        // imperative to combine the two arrays __recursively__ to have properly
+        // constructed arrays of objects (collections) prior to validating
+        // them against the schema
+        //
+        // Otherwise, the file array will overwrite the body array at the common
+        // __root__ element, which may result in an object validation error if
+        // the object also contains other properties (stored in the body array)
+        //
+        // Eg: Array of file objects with a text descriptor
+        // [
+        //   ['description' => <string>, 'file' => <binary>]
+        //   ['description' => <string>, 'file' => <binary>]
+        //   ['description' => <string>, 'file' => <binary>]
+        // ]
+        //
+        // The 'description' would be in $body and 'file' would be in $files
         $body = array_replace_recursive($body, $files);
 
         $validator = new SchemaValidator($this->detectValidationStrategy($message));