From 838947ce398ae09f1722984ea81ed2fc82da2f5c Mon Sep 17 00:00:00 2001
From: Will-thom <116388885+Will-thom@users.noreply.github.com>
Date: Wed, 20 May 2026 12:54:41 -0300
Subject: [PATCH] Fix JSON:API collection included schema

---
 src/JsonApi/JsonSchema/SchemaFactory.php | 18 ++++++++++++------
 tests/Functional/OpenApiTest.php         | 18 ++++++++++++++++++
 2 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/src/JsonApi/JsonSchema/SchemaFactory.php b/src/JsonApi/JsonSchema/SchemaFactory.php
index 8e5b0667c5..c4448ee842 100644
--- a/src/JsonApi/JsonSchema/SchemaFactory.php
+++ b/src/JsonApi/JsonSchema/SchemaFactory.php
@@ -259,15 +259,21 @@ public function buildSchema(string $className, string $format = 'jsonapi', strin
         $properties = $this->buildDefinitionPropertiesSchema($key, $className, $format, $type, $operation, $schema, []);
         $properties['data']['properties']['attributes']['$ref'] = $prefix.$key;
 
+        $collectionProperties = [
+            'data' => [
+                'type' => 'array',
+                'items' => $properties['data'],
+            ],
+        ];
+
+        if (isset($properties['included'])) {
+            $collectionProperties['included'] = $properties['included'];
+        }
+
         $schema['description'] = "$definitionName collection.";
         $schema['allOf'] = [
             ['$ref' => $prefix.(false === $operation->getPaginationEnabled() ? self::COLLECTION_BASE_SCHEMA_NAME_NO_PAGINATION : self::COLLECTION_BASE_SCHEMA_NAME)],
-            ['type' => 'object', 'properties' => [
-                'data' => [
-                    'type' => 'array',
-                    'items' => $properties['data'],
-                ],
-            ]],
+            ['type' => 'object', 'properties' => $collectionProperties],
         ];
 
         return $schema;
diff --git a/tests/Functional/OpenApiTest.php b/tests/Functional/OpenApiTest.php
index 1bfbe5f749..546861f1a7 100644
--- a/tests/Functional/OpenApiTest.php
+++ b/tests/Functional/OpenApiTest.php
@@ -261,6 +261,24 @@ public function testHasSchemasForMultipleFormats(): void
         ], 'description' => 'A resource used for OpenAPI tests.'], $res['components']['schemas']['Crud.jsonld']);
     }
 
+    public function testJsonApiCollectionSchemaDocumentsIncludedResources(): void
+    {
+        $response = self::createClient()->request('GET', '/docs', [
+            'headers' => ['Accept' => 'application/vnd.openapi+json'],
+        ]);
+
+        $this->assertResponseIsSuccessful();
+        $json = $response->toArray();
+        $schema = $json['paths']['/dummies']['get']['responses']['200']['content']['application/vnd.api+json']['schema'];
+        $properties = $schema['allOf'][1]['properties'];
+
+        $this->assertArrayHasKey('included', $properties);
+        $this->assertSame('array', $properties['included']['type']);
+        $this->assertTrue($properties['included']['readOnly']);
+        $this->assertArrayHasKey('anyOf', $properties['included']['items']);
+        $this->assertNotEmpty($properties['included']['items']['anyOf']);
+    }
+
     public function testRetrieveTheOpenApiDocumentation(): void
     {
         $response = self::createClient()->request('GET', '/docs', ['headers' => ['accept' => 'application/vnd.openapi+json']]);