Use ResourceObjectData with cardinality 1 for individual responses

1. +++ b/src/Controller/EntityResource.php
   @@ -918,6 +922,7 @@ class EntityResource {
   +    assert($data instanceof Data || $data instanceof FieldItemListInterface);
   

   The second case would disappear once Relationship exists, i.e. once #3036285: Add a \JsonApiResource\Relationship object to carry relationship data, metadata and a link collection. is done?

2. +++ b/src/Controller/EntityResource.php
   @@ -1024,6 +1030,7 @@ class EntityResource {
      public function getIncludes(Request $request, $data) {
   +    assert($data instanceof ResourceObject || $data instanceof ResourceObjectData);
   

   Why can this be both?

3. +++ b/src/IncludeResolver.php
   @@ -64,9 +64,8 @@ class IncludeResolver {
      public function resolve($data, $include_parameter) {
   -    assert($data instanceof ResourceIdentifierInterface || $data instanceof ResourceObjectData);
   ...
   +    assert($data instanceof ResourceObject || $data instanceof ResourceObjectData);
   

   Same question here.

4. +++ b/src/JsonApiResource/LinkCollection.php
   @@ -24,7 +24,7 @@ final class LinkCollection implements \IteratorAggregate {
   -   * @var \Drupal\jsonapi\JsonApiResource\JsonApiDocumentTopLevel
   +   * @var \Drupal\jsonapi\JsonApiResource\JsonApiDocumentTopLevel|\Drupal\jsonapi\JsonApiResource\ResourceObject
   

   👍Fixes small oversight in #3015438: Wrap entity objects in a ResourceObject which carries a ResourceType.

I find this issue a bit too light on the explanation and justification side. So I'm RTBC'ing this with my understanding of the rationale, if it's wrong, please un-RTBC. Ideally we'd also get @effulgentsia to +1, since he was involved with related/preceding issues.

+++ b/src/Controller/FileUpload.php
@@ -184,7 +185,8 @@ class FileUpload {
-    return new ResourceResponse(new JsonApiDocumentTopLevel(new ResourceObject($file_resource_type, $file), new NullData(), $links), 201, []);
+    $resource_object = new ResourceObject($file_resource_type, $file);
+    return new ResourceResponse(new JsonApiDocumentTopLevel(new ResourceObjectData([$resource_object], 1), new NullData(), $links), 201, []);

+++ b/src/Normalizer/DataNormalizer.php
@@ -0,0 +1,34 @@
+class DataNormalizer extends NormalizerBase {

This normalizer is now necessary because there is now one extra level of indirection in the data structure, right?

That extra level of indirection buys us the benefit of dealing with "data" generically: be it includes, resource objects or relationships.

This paves the path to let contrib modules in the future provide access to non-entity data in JSON:API-compliant responses (see #3032787: [META] Start creating the public PHP API of the JSON:API module).

I first started this by opening #3032679: Clean-up: rename EntityCollection to Data to rename EntityCollection to something that is not tightly coupled to entities, and that itself was triggered by #3015438: Wrap entity objects in a ResourceObject which carries a ResourceType, which was the first essential step.

Assuming this is correct, RTBC.

Ahhh, that settles my one concern! Will commit when green :) (And it obviously should be, but I'll still wait, because typos are easily introduced.)