Specification is unclear on where description of relationships should go

[rartino]

In typing up an example for the discussion #211, it became clear to me that we have a weakness in the specification in regards to the use of a description field for a human-readable description of the nature of a relationship.

The specification says:

• relationships: a dictionary containing references to other entries according to the description in section Relationships encoded as JSON API Relationships. The OPTIONAL human-readable description of the relationship MAY be provided in the description field inside the meta dictionary.

This makes it sound as one is supposed to use the meta dictionary belonging to the relationship object described in JSON API as "a meta object that contains non-standard meta-information about the relationship." I.e.:

    "relationships": {
      "calculations": {
        "data": [
          { "type": "calculations", "id": "4711" },
          { "type": "calculations", "id": "4712"}
        ],
        "meta": {
            "description": "The relaxation calculation generating this structure."
         }
      }
    }

However, as can be seen in this example, this only leaves room for a single description for all the linked entries of the same type! So I cannot indicate different descriptions for the two calculations entries.

So, perhaps it is reasonable then to use the meta field inside what JSON API calls the resource identifier object, i.e.:

    "relationships": {
      "calculations": {
        "data": [
          { "type": "calculations", "id": "4711", 
            "meta": {
               "description": "The relaxation calculation generating this structure."
            }},
          { "type": "calculations", "id": "4712",
            "meta": {
               "description": "Calculation of elastic constants of this structure."
            }},
          }
        ],
      }
    }

Although, to me, this does seem to somewhat misuse that meta field, since this isn't meta-data about the referenced object, it is meta-data pertaining to the relationship to it.

To make matters worse, our specification actually has an example that uses this description field like this:

"relationships": {
      "references": {
        "data": [
          { "type": "references", "id": "Dijkstra1968" },
          {
            "type": "references",
            "id": "1234",
            "meta": {
              "description": "This article has been retracted"
            }
          }
        ]
      }
    }

However, note how the description field in this example isn't used as a "human readable description of the nature of a relationship" as we say; here it is used as a clarification of the nature of that resource identifier object, which is more in line with the spirit of the JSON API spec.

This seems a bit of a mess. Any advice for what changes we should do to rectify this are welcome. I'm leaning towards clarifying that we standardizing on "misusing" the resource identifier object meta field and update the example accordingly.

[merkys]

However, as can be seen in this example, this only leaves room for a single description for all the linked entries of the same type! So I cannot indicate different descriptions for the two calculations entries.

So, perhaps it is reasonable then to use the meta field inside what JSON API calls the resource identifier object, i.e.:

I agree that meta of resource identifier object is a more natural place to describe the relations, and this should be stressed in the OPTiMaDe specification.

Although, to me, this does seem to somewhat misuse that meta field, since this isn't meta-data about the referenced object, it is meta-data pertaining to the relationship to it.

I understand the concern, but I can't think of a more suitable place to describe the relationships.

However, note how the description field in this example isn't used as a "human readable description of the nature of a relationship" as we say; here it is used as a clarification of the nature of that resource identifier object, which is more in line with the spirit of the JSON API spec.

Indeed, the comment This article has been retracted describes the referenced object, not the relationship. I agree that we should fix this example to show the intent to use meta of resource identifier object to describe relationships.

This seems a bit of a mess. Any advice for what changes we should do to rectify this are welcome. I'm leaning towards clarifying that we standardizing on "misusing" the resource identifier object meta field and update the example accordingly.

Agree.

[CasperWA]

According to the JSON API spec "a resource identifier object MAY also include a meta member, whose value is a meta object that contains non-standard meta-information".

To me, the question indeed seems to come down to @rartino's thought that "[a]lthough, to me, this does seem to somewhat misuse that meta field, since this isn't meta-data about the referenced object, it is meta-data pertaining to the relationship to it."

To this I would say we should be careful. Either we go directly against the JSON API and add our own field/member to a resource object identifier, or we put it under meta and acknowledge that it is in the gray-area between data and metadata? Personally, I prefer the second option, as it is more inline with the JSON API spec.