Update requirements for top-level "included"

[CasperWA]

From the consortium meeting on 26.11.2019 we have decided the following:

If a related resource is of type references it SHOULD be included under the top-level included field.
For any other related resource types it MAY be included under the top-level included field.

There is as of yet no consensus on limitation on how many resource objects may be returned under included.

There is also no consensus on whether we want to use the include query parameter.

[CasperWA]

Tagging main contributors to the discussion if there are any additions: @fawzi, @rartino, @ml-evs, @sauliusg, @merkys

[merkys]

There is issue #183 opened to discuss the support of JSON API's include query parameter.

[merkys]

My opinion:

• I'm OK with references having a special role. As discussed in the Web meeting, a user most likely will want to get them anyway.

• Concerning the limitation on included, JSON API seems to forbid limits on inclued.

• Concerning the include and included I have the following proposal: let's omit the included if include is not present, and include only those entry types that are explicitly requested by include. This would reduce the load of the most usual queries, but still allow inclusion upon requests. And this proposal seems to agree with JSON API specification.

What do you think?

[CasperWA]

@merkys, so to sum up, from the POV of the OPTiMaDe spec, what I understand by your points (just to ensure we're on the same page):

The top-level included field MUST/SHOULD be omitted unless the include parameter has been specified with a valid value.

And then either:

• The default value for include, if it is not supplied explicitly, is include=references; or
• The first rule should be foregone if any primary data return a relationships of the type references. Relationship data of type references MUST/SHOULD always be passed under the top-level included field, if present.

[merkys]

@CasperWA, now I see the conflicting statements I've made :)

So when include is provided, we should follow the JSON API and show only what is requested.

And there are two alternative ways to deal with the implicit case, i.e., when include is not provided:

1. Omit included altogether;
2. Act as if include=references was supplied.

I have a feeling (can't prove it, though) that 2. might be against JSON API spec., as presence of included most probably makes a response a compound document, and then all referenced objects MUST be in included. But I may be wrong. Then option 2. would be OK.

[CasperWA]

So when include is provided, we should follow the JSON API and show only what is requested.
(...)
I have a feeling (can't prove it, though) that 2. might be against JSON API spec., as presence of included most probably makes a response a compound document, and then all referenced objects MUST be in included. But I may be wrong. Then option 2. would be OK.

Considering these two things, it seems to me that when include is provided, only relationships of the type included in the value for include should be returned under included (convoluted sentence, sorry).
I.e., if we have include=references (option 2.) being the default, then no matter what kind of relationship-types there are in the primary data, only those of type references should be returned under included, which is compliant with the JSON API defintion of the include parameter. Right? :)

[merkys]

Considering these two things, it seems to me that when include is provided, only relationships of the type included in the value for include should be returned under included (convoluted sentence, sorry).

My interpretation is (and would sound) the same :)

I.e., if we have include=references (option 2.) being the default, then no matter what kind of relationship-types there are in the primary data, only those of type references should be returned under included, which is compliant with the JSON API defintion of the include parameter. Right? :)

I meant option 2. being the default when include is not provided: the API lists references in included if include is not given.

[CasperWA]

Great! I think we can try putting this into the spec. now 👍