Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open
  • Is something wrong?
#8,698 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
58/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
openapi, php
Domain
api

Research direction

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.

Written by the indexing model from the issue text.

Description

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.

Dominant language
PHP
Stars
2.6k
Forks
989
Avg merge
2d 1h
Merged PRs (30d)
104

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from api-platform/core

All issues in api-platform/core

Similar issues

More PHP issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.