fix(jsonschema): don't require @id in single-item MCP output schema (#8343)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: soyuka <soyuka@users.noreply.github.com>

Author: 3 people

src/Hydra/Tests/JsonSchema/SchemaFactoryTest.php

@@ -161,6 +161,33 @@ public function testSchemaTypeBuildSchema(): void
         $this->assertEquals($resultSchema['allOf'][0]['$ref'], $forcedCollection['allOf'][0]['$ref']);
     }
 
+    // gen_id=false output schema must not require `@id` (e.g. an operation whose serializer omits the IRI).
+    public function testGenIdFalseOutputSchemaDoesNotRequireId(): void
+    {
+        $resultSchema = $this->schemaFactory->buildSchema(Dummy::class, 'jsonld', Schema::TYPE_OUTPUT, new Get(), null, ['gen_id' => false]);
+
+        $definitions = $resultSchema->getDefinitions();
+        $rootDefinitionKey = $resultSchema->getRootDefinitionKey();
+
+        $this->assertSame(['$ref' => '#/definitions/HydraItemBaseSchemaWithoutId'], $definitions[$rootDefinitionKey]['allOf'][0]);
+        $this->assertArrayHasKey('HydraItemBaseSchemaWithoutId', $definitions);
+        $this->assertSame(['@type'], $definitions['HydraItemBaseSchemaWithoutId']['required']);
+        $this->assertArrayNotHasKey('HydraItemBaseSchema', $definitions);
+    }
+
+    // Default (gen_id left to its true default): the output schema keeps `@id` required.
+    public function testOutputSchemaRequiresIdByDefault(): void
+    {
+        $resultSchema = $this->schemaFactory->buildSchema(Dummy::class, 'jsonld', Schema::TYPE_OUTPUT, new Get());
+
+        $definitions = $resultSchema->getDefinitions();
+        $rootDefinitionKey = $resultSchema->getRootDefinitionKey();
+
+        $this->assertSame(['$ref' => '#/definitions/HydraItemBaseSchema'], $definitions[$rootDefinitionKey]['allOf'][0]);
+        $this->assertSame(['@id', '@type'], $definitions['HydraItemBaseSchema']['required']);
+        $this->assertArrayNotHasKey('HydraItemBaseSchemaWithoutId', $definitions);
+    }
+
     public function testSchemaTypeBuildSchemaWithoutPrefix(): void
     {
         $resultSchema = $this->schemaFactory->buildSchema(Dummy::class, 'jsonld', Schema::TYPE_OUTPUT, new GetCollection(), null, [ContextBuilder::HYDRA_CONTEXT_HAS_PREFIX => false]);

src/Mcp/JsonSchema/SchemaFactory.php

@@ -15,6 +15,9 @@
 
 use ApiPlatform\JsonSchema\Schema;
 use ApiPlatform\JsonSchema\SchemaFactoryInterface;
+use ApiPlatform\Metadata\CollectionOperationInterface;
+use ApiPlatform\Metadata\McpResource;
+use ApiPlatform\Metadata\McpTool;
 use ApiPlatform\Metadata\Operation;
 
 /**
@@ -32,6 +35,16 @@ public function __construct(
 
     public function buildSchema(string $className, string $format = 'json', string $type = Schema::TYPE_OUTPUT, ?Operation $operation = null, ?Schema $schema = null, ?array $serializerContext = null, bool $forceCollection = false): Schema
     {
+        // A single-item MCP operation has no routed item URI (Mcp\Routing\IriConverter returns null),
+        // so the serializer omits `@id`: mirror that here so the advertised output schema doesn't require it.
+        if (Schema::TYPE_OUTPUT === $type
+            && ($operation instanceof McpTool || $operation instanceof McpResource)
+            && !$operation instanceof CollectionOperationInterface
+        ) {
+            $serializerContext ??= [];
+            $serializerContext['gen_id'] = false;
+        }
+
         $schema = $this->decorated->buildSchema($className, $format, $type, $operation, $schema, $serializerContext, $forceCollection);
 
         $definitions = [];

src/Mcp/Tests/JsonSchema/SchemaFactoryTest.php

@@ -16,6 +16,9 @@
 use ApiPlatform\JsonSchema\Schema;
 use ApiPlatform\JsonSchema\SchemaFactoryInterface;
 use ApiPlatform\Mcp\JsonSchema\SchemaFactory;
+use ApiPlatform\Metadata\McpResource;
+use ApiPlatform\Metadata\McpTool;
+use ApiPlatform\Metadata\McpToolCollection;
 use PHPUnit\Framework\TestCase;
 
 class SchemaFactoryTest extends TestCase
@@ -422,4 +425,68 @@ public function testRefInsideAnyOfIsResolved(): void
         $this->assertSame(['type' => 'null'], $related['anyOf'][1]);
         $this->assertArrayNotHasKey('type', $related);
     }
+
+    /**
+     * A single-item MCP operation has no routed item URI (Mcp\Routing\IriConverter returns null),
+     * so the output schema must advertise `gen_id` as false to drop the required `@id`.
+     */
+    public function testSingleItemMcpOperationForcesGenIdFalse(): void
+    {
+        foreach ([new McpTool(class: \stdClass::class), new McpResource(uri: 'app://dummy', class: \stdClass::class)] as $operation) {
+            $captured = null;
+            $inner = $this->createMock(SchemaFactoryInterface::class);
+            $inner->method('buildSchema')->willReturnCallback(function (...$args) use (&$captured) {
+                $captured = $args[5] ?? null;
+
+                return $this->emptyObjectSchema();
+            });
+
+            $factory = new SchemaFactory($inner);
+            $factory->buildSchema('App\\Dummy', 'jsonld', Schema::TYPE_OUTPUT, $operation);
+
+            $this->assertFalse($captured['gen_id'] ?? null, $operation::class.' must force gen_id to false');
+        }
+    }
+
+    public function testMcpToolCollectionDoesNotForceGenIdFalse(): void
+    {
+        $captured = 'untouched';
+        $inner = $this->createMock(SchemaFactoryInterface::class);
+        $inner->method('buildSchema')->willReturnCallback(function (...$args) use (&$captured) {
+            $captured = $args[5] ?? null;
+
+            return $this->emptyObjectSchema();
+        });
+
+        $factory = new SchemaFactory($inner);
+        $factory->buildSchema('App\\Dummy', 'jsonld', Schema::TYPE_OUTPUT, new McpToolCollection(class: \stdClass::class));
+
+        $this->assertNull($captured);
+    }
+
+    public function testInputSchemaDoesNotForceGenIdFalse(): void
+    {
+        $captured = 'untouched';
+        $inner = $this->createMock(SchemaFactoryInterface::class);
+        $inner->method('buildSchema')->willReturnCallback(function (...$args) use (&$captured) {
+            $captured = $args[5] ?? null;
+
+            return $this->emptyObjectSchema();
+        });
+
+        $factory = new SchemaFactory($inner);
+        $factory->buildSchema('App\\Dummy', 'json', Schema::TYPE_INPUT, new McpTool(class: \stdClass::class));
+
+        $this->assertNull($captured);
+    }
+
+    private function emptyObjectSchema(): Schema
+    {
+        $schema = new Schema(Schema::VERSION_JSON_SCHEMA);
+        unset($schema['$schema']);
+        $schema->getDefinitions()['Dummy'] = new \ArrayObject(['type' => 'object']);
+        $schema['$ref'] = '#/definitions/Dummy';
+
+        return $schema;
+    }
 }