Errors and links


I really like the JSON:API spec for it’s clearness regarding MAY and MUST mentions.
However the links member in an Error is not crystal clear.

An error object MAY have the following members:

  • links: a links object containing the following members:
    • about: a link that leads to further details about this particular occurrence of the problem.

Does this mean a links member MUST and MUST ONLY contain an about link?
Or MAY it contain an about link and MAY it contain any other links?



I think you interpreted the specification exactly correct. To me, the link object in the error response is intended to point to the documentation of the specific application error code in order to explain the context when combined with the source/pointer and source/parameter arguments.

Suppose you have a very complex workflow, like a mortgage application. If you have specific domain (application) validation which goes beyond simply sanitizing the user input, the error link would point to the documentation which explains error code=394294. The client or user/developer could then use these combined fields to present a correction dialogue with only the invalid segments for the user to correct, and resubmit.

If you were to expand this field to a generic container, you would lose the ability to guarantee the interoperability of the fields to create this capability. You could certainly still have it if the situation persisted, but it would greatly complicate the consumer, making errors and interpretation differences far more likely.