[OpenAPI] @id, @type and @context fields are included in schemas inconsistently between Item and Collection operations

[jamesisaac]

API Platform version(s) affected: 2.5.6 and master

Description

This is an easier problem to work around than the one I reported in #3666 , but thought I'd still make a note of it anyway.

If a certain serializer group only appears in a collection operation, then @id and @type fields are missing from the generated OpenAPI schema. E.g. this:

 * @ApiResource(
 *  normalizationContext={"groups"={"Book:Default"}},
 *  collectionOperations={
 *      "get"={
 *          "normalization_context"={
 *              "groups"={
 *                  "Book:Collection"
 *              },
 *          },
 *      }
 *  }
 * )

...will lead to a consumer of the OpenAPI schema thinking there are no @id and @type fields for each item in the collection, when in fact there are.

This problem can be solved if Book:Collection were to be added to an itemOperation, because the schema is then shared. However this does introduce another slight bug... it then suggests that the collection includes @context, which it doesn't.

How to reproduce

I've created a reproduction here:

https://github.com/jamesisaac/openapi-bugs

Once running, OpenAPI docs are visible at http://localhost:8000 or http://localhost:8000/docs.json

The /books endpoint according to OpenAPI schemas has no @id or @type attribute, but in reality it does.

Possible Solution

A partial solution would be including @id and @type when the schema comes from a collection.

Although technically, that still doesn't seem perfect, as then you'd have the inconsistency that @context is different between collections and items. I suppose to get this perfect you'd need a different schema for items and collections... not sure that's exactly desirable though as it will lead to even more generated schemas and longer names.

Additional Context

• I've tried this on 2.5.6, and on master with OpenApi v3 refactor  #3407 merged, but the problem seems present on both.

[soyuka]

I've tried this on 2.5.6, and on master with #3407 merged, but the problem seems present on both.

Indeed the Schema part stayed the same. Not sure about what's recommended here, @dunglas any idea?

[dunglas]

I'm in favor of always including the @ keys in the JSON schemas describing JSON-LD documents (actually it's what I tried to do but may have missed some cases).
This keys aren't marked as required in the JSON Schema, so a JSON-LD not including these keys (when embedded for instance) will still be valid according to a schema defining them (but not marking them as mandatory).

[jamesisaac]

Hm, when you talk about these @ fields being non-required, are you talking about as input parameters or something?

From what I can see in the /docs.json response schemas, they're not marked as nullable, so I'd assume they're always required? I'm relying on @id and @type a lot in client-side code, so it would make things quite difficult if those could sometimes be missing. (Currently it seems like they are always there, it's just the OpenAPI schemas that are incorrectly missing them).

[dunglas]

@id and @type will be always there (and we should fix the schema if they aren't always described). However @context may be described but not present.

According to https://json-schema.org/understanding-json-schema/reference/object.html#required-properties, all properties are optional by default, except when explicitly marked as required.

[jamesisaac]

Got it, thanks! I wasn't seeing a required key anywhere under components.schemas (although now I see it's used in a couple of places in paths), so wasn't aware that was a feature of JSON Schema -- I'll read the reference next time 😉

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.