JsonSchema assertion will always fail for API Resources that have an output class defined

[llupa]

API Platform version(s) affected: 2.5.8 and up

Description

The SchemaFactory for Hydra properties is hardcoded to add @context as a string type. This works fine when the Resource class matches the output object. The ItemNormalizer will set @context as an IRI/URI in this case.

In case of a Resource class using an output class (see example below) the ItemNormalizer will ignore the object and the ObjectNormalizer takes over and will hard-code set the @context as an array. This happens via getAnonymousResourceContext used in ContextBuilder.

How to reproduce

1. Create a resource with output option:

Domain\Licence\Entity\LicenceCommentary:
    description: Licence commentary
    attributes:
        output: Domain\Licence\Model\LicenceCommentaryOutput
        input: Domain\Licence\Model\LicenceCommentaryInput

2. use the JsonSchema assertions provided by API Platform:

self::assertMatchesResourceItemJsonSchema(LicenceCommentary::class);

✘ Create [405 ms]
   │
   │ Failed asserting that Array &0 (
   │     '@context' => Array &1 (
   │         '@vocab' => 'http://example.com/docs.jsonld#'
   │         'hydra' => 'http://www.w3.org/ns/hydra/core#'
   │         'uuid' => 'LicenceCommentaryOutput/uuid'
   │         'type' => 'LicenceCommentaryOutput/type'
   │         'text' => 'LicenceCommentaryOutput/text'
   │     )
   │     '@type' => 'LicenceCommentary'
   │     '@id' => '/licences/57e4525d-3bc7-44ea-a5d9-8039f8f431fa/commentaries/92fd7512-70ff-423c-9136-96529a27b21e'
   │     'uuid' => '92fd7512-70ff-423c-9136-96529a27b21e'
   │     'type' => 'create type'
   │     'text' => 'create text'
   │ ) matches the provided JSON Schema.
   │ @context: Object value found, but a string is required
   │ 
   │ /builds/audi/vms-api/vendor/api-platform/core/src/Bridge/Symfony/Bundle/Test/ApiTestAssertionsTrait.php:109
   │ /builds/audi/vms-api/vendor/api-platform/core/src/Bridge/Symfony/Bundle/Test/ApiTestAssertionsTrait.php:123
   │ /builds/audi/vms-api/tests/Functional/Licence/LicenceCommentaryResourceTest.php:37
   │ 

Possible Solution

I have already tried a solution locally, it seems if the Hydra JsonSchema, SchemaFactory becomes smarter by using the ResourceClassInfoTrait it can resolve wether @context will be an object or string via isResourceClass(string $class) in the trait. The assertions pass afterwards.

I can open a PR if this is enough.

[alanpoulain]

I think we don't need to go this far. You can just change the @context type to be either a string or an array(if possible with the required and optional properties).

[llupa]

@alanpoulain Thanks for the fast reply. The schema factory has only these arguments available:

string $className, 
string $format = 'jsonld', 
string $type = Schema::TYPE_OUTPUT, 
?string $operationType = null, 
?string $operationName = null, 
?Schema $schema = null, 
?array $serializerContext = null, 
bool $forceCollection = false

None of those can tell me if the class is an optional output or the actual api resource class, this doesn't go well with the normalization, the object normalizer sees the output class as a non resource class and will always create the array data for the hydra @context.

I saw that you have worked in this part and maybe I am missing something?

[alanpoulain]

The type key is a valid JSON Schema type.
You can then use oneOf to say that it can be either a string or an array.

[llupa]

Excellent idea, I will try it out and if all seems fine, submit a PR. Thank you!