JsonApiRequestValidator creates ResourceResponse object with array instead of JsonApiDocumentTopLevelNormalizerValue

#2948666: Remove JSON API's use of $context['cacheable_metadata'] had the side-effect/benefit of ensuring that ResourceResponses always contain a data value that normalizes to a JsonApiDocumentTopLevelValue object.

It does that with:

// Having just normalized the data, we can associate its cacheability with
// the response object.
assert($jsonapi_doc_object instanceof JsonApiDocumentTopLevelNormalizerValue);

This makes sense. JSON API always returns a JSON API document.

#2933062: [>=8.5.4] Spec Compliance: Return 400 for unrecognized/unsupported query parameters added validation of JSON API query parameters. Correctly, it attempts to respond with an errors JSON API document with a relevant hyperlink to the JSON API spec.

Unfortunately, it does this by returning a ResourceResponse whose $data value is a complete JSON API document in array form.

Why doesn't it return a JsonApiDocumentTopLevel object? That's what it's for right? You'd think! But...

Wah, wahh, it can't because that class can't handle JSON API error documents. It's even on the class comment:

 * @todo Add the missing required members: 'error' and 'meta' or document why not.
 * @todo Add support for the missing optional members: 'jsonapi', 'links' and 'included' or document why not.
 */
class JsonApiDocumentTopLevel {

So, what to do? Could we throw an exception? We could, but we don't actually have a generic exception class that's customizable. IOW, if we threw an BadRequestException, we couldn't add that helpful hyperlink to the JSON API spec.

One way to solve this would be to create that exception class.

OTOH, we could make it possible to create a JsonApiDocumentTopLevel object with errors from scratch and add that directly to the ResourceResponse object that the request validator returns.

I propose we do this second object. We'll need to add a value object to src/Normalizer/Value named ErrorObject to mirror the JSON API terminology. That object should implement CacheableDependencyInterface. From there, we would make it possible to construct a JsonApiDocumentTopLevel object with either an iterator of entities (EntityCollection) or an iterator of errors.... and never the twain shall meet.

I ofc assume @Wim Leers will find a three line solution instead :P so in that case, disregard!

(I really would like to get to a point where we're constructing documents out of value objects, rather than returning a mishmash of jsonapi and non-jsonapi non-value objects that normalize to a nest of value objects, this could be a small first-step in that direction).