Top-level document with `errors` and `links`

1

Hi all, I’d just like to clarify the meaning of a top-level document with both an errors property and a links property.

The spec clearly states that a top-level document without a data property will not have an included property either:

If a document does not contain a top-level data key, the included member MUST NOT be present either.

However, no such condition exists for links. And the spec defines the links field as such:

So, I ask: what does it mean to have links that are “related to the primary data” when no such primary data is included in the document?

My guess: this description of the links field is not entirely accurate, as the self link (for example) is sensible to include in a document that does not contain any primary data.

2

I agree, in some ways, the specification is not quite clear.

Two things come into my mind when I think about this.
First, error objects have their own links object where error-related links go (about / type).

Second, you could see the “errors” array as the primary data of a document since “errors” and “data” must not coexist in the same document (my thoughts - no official statement). So, the top-level links object could still contain relevant links, such as a “self” link which is basically the URI that caused the error.

3

Could catch. I created top-level links object is related to the document in some cases by jelhan · Pull Request #1753 · json-api/json-api · GitHub to improve the wording and avoid this confusion.

2 Likes
4

You are right Jelhan.