JSON:API: input schema puts an embedded input DTO collection under `relationships`, but the denormalizer reads it from `attributes`

Start in JsonApi\JsonSchema\SchemaFactory::buildDefinitionPropertiesSchema(), where getRelationship() is called with the resource class instead of the input class. Compare how the denormalizer splits attributes from relationships for an input DTO, then reproduce with the issue's Order/OrderInput classes and run bin/console api:openapi:export. Done when lines is documented under attributes as an array of OrderLineInput for the input schema, and the output schema is unchanged.

API Platform version(s) affected

4.4.4

Description

A resource has a relation to another resource. A write operation uses an input DTO, and the DTO has a property with the same name that holds plain (non-resource) objects.

For the JSON:API format, the generated request body schema puts this property under data.relationships as resource linkage (type + id). The denormalizer does not accept that shape. It accepts the objects only under data.attributes, and that shape is not documented.

The cause looks like JsonApi\JsonSchema\SchemaFactory::buildDefinitionPropertiesSchema(). It calls getRelationship($className, ...) with the resource class, not with the input class. So the schema uses the type of the resource property (list<OrderLine>, a resource) and not the type of the input property (list<OrderLineInput>, a plain DTO).

How to reproduce

#[ApiResource(operations: [new Get(provider: [self::class, 'provide'])])]
final class OrderLine
{
    public function __construct(public int $id = 1, public string $sku = 'ABC', public int $quantity = 1) {}
    public static function provide(): self { return new self(); }
}

final class OrderLineInput
{
    public string $sku;
    public int $quantity;
}

final class OrderInput
{
    public string $reference;
    /** @var list<OrderLineInput> */
    public array $lines = [];
}

#[ApiResource(operations: [
    new Get(provider: [self::class, 'provide']),
    new Post(input: OrderInput::class, processor: [self::class, 'process']),
])]
final class Order
{
    /** @param list<OrderLine> $lines */
    public function __construct(public int $id = 1, public string $reference = 'R-1', public array $lines = []) {}

    public static function provide(): self { return new self(); }

    public static function process(OrderInput $data, Operation $operation): self
    {
        $lines = [];
        foreach ($data->lines as $i => $line) {
            $lines[] = new OrderLine($i + 1, $line->sku, $line->quantity);
        }
        return new self(1, $data->reference, $lines);
    }
}

The generated Order.OrderInput.jsonapi schema (shortened):

"attributes": { "properties": { "reference": { "type": "string" } } },
"relationships": {
  "properties": {
    "lines": { "properties": { "data": { "type": "array", "items": {
      "properties": { "type": { "type": "string" }, "id": { "type": "string", "format": "iri-reference" } },
      "required": ["type", "id"]
    } } } }
  }
}

A request that follows the schema fails. The processor gets an OrderLineInput whose properties were never set:

POST /orders
Content-Type: application/vnd.api+json

{"data":{"type":"Order","attributes":{"reference":"R-9"},"relationships":{"lines":{"data":[{"type":"OrderLine","id":"/order_lines/1"}]}}}}

Error: Typed property App\ApiResource\OrderLineInput::$sku must not be accessed before initialization

A request with the lines under attributes works and answers 201, but the schema does not document it:

POST /orders
Content-Type: application/vnd.api+json

{"data":{"type":"Order","attributes":{"reference":"R-9","lines":[{"sku":"X","quantity":2}]}}}

Expected: for an input schema, the attributes/relationships split follows the input class. lines is then documented under attributes as an array of OrderLineInput, which is the shape the denormalizer reads.

Possible Solution

Use the input class (or the output class for output schemas) in getRelationship(), not the resource class.

Additional Context

Checked on api-platform/core v4.4.4, Symfony 7.4, PHP 8.5, in an empty Symfony app. The code of JsonApi\JsonSchema\SchemaFactory on main is the same as in v4.4.4.

The app has only FrameworkBundle, TwigBundle and ApiPlatformBundle, with this config:

$c->extension('api_platform', [
    'mapping' => ['paths' => ['%kernel.project_dir%/src/ApiResource']],
    'formats' => ['jsonapi' => ['application/vnd.api+json']],
    'docs_formats' => ['jsonopenapi' => ['application/vnd.openapi+json']],
    'doctrine' => ['enabled' => false],
]);

The spec comes from bin/console api:openapi:export.