Specification unclear on the key to use in JSON:API relationships

[rartino]

As we've found in trying to resolve #386, the specification is presently unclear on what key one should use for the various JSON:API relationships one include in the relationship dictionary as part of a JSON:API-formatted response.

Given that we do not say anything about it, one may be led to believe that any key is permissible. However, the output-format-agnostic description of relationships in 3.6 Relationships makes no reference to a free-form "key" or "name" tied to an OPTIMADE relationship, so this is then some data that would only appear in a JSON:API response.

From the discussion in #386 it seems we have (at least) two options:

1. Mandate that the key must be the entry type (e.g., "structures"), and thus that there is no contextual "grouping" of related entries, but rather, all related entries of the same type are grouped, and cannot be grouped with entries of a different type. This can be done by: Edit 5.3.2 Entry Listing JSON Response Schema and for the definition of the "relationships" field say that: "Relationships MUST be grouped into a single JSON API relationships object for each entry type and placed in the relationships dictionary with that entry type name as key (e.g., "structures").

2. Preserve the possibility of a free-form JSON:API relationship key that can "group" related entries (possibly of different types) under a name. This can be done by describing the feature of a 'relationship name' to 3.6 Relationships. Preferably with some hint in the implementers note about how one can encode these names in more straightforward key-value based output formats (e.g. "type name + '_' + relationship name"?). It is probably also a good idea with a clarification in 5.3.2 that the key in this dictionary field represents this "relationship name".

We probably need to sort this out before merging #386.

[ml-evs]

Although we don't currently mandate 1. in the specification, it's somewhat implicit in 6.2.7 Filtering on releationships where the only examples given are for filtering on relationships of <entry_type>, since they are the only protected non-attribute/filter language keywords in the spec. If we were to standardize on 2., there would either need to be a corresponding change to the filtering process, or restrictions on the allowed values of the relationship name. Examples:

• Current mechanism for filtering on the structure->reference relationship:
  /structures?filter=references.id HAS "ref1"
• Probably undesirable cases we would need to worry about:
  /structures?filter=chemical_formula_anonymous.id HAS "ref1", /structures?filter=_cod_spacegroup.id HAS "ref1"

I think I would prefer any sufficiently complicated relationship (i.e., of multiple types) with a description that covers the whole set (as opposed to the relationship descriptions which a per-link) to be implemented as a collection, i.e., we standardize on 1.

[rartino]

I agree - option 2 is a major revision that affects multiple parts of the proposal, and option 1 is essentially 'what we meant all along', which only needs a rather minor clarification. Nice observation that the loss of functionality in not allowing arbitrary grouping in relationships is offset by collections.

So, I guess I'll draft up the option 1 clarification as a PR unless someone else objects.