One of my primary motivations when I started this (a few years ago now) was a straight forward representation of graphs of data (including bits of data without dedicated URLs), rather than trees of data.
Consider the case of a blog. Each blog post has many comments. Each post has an author, and each comment has an author. Some of those entities may have dedicated URLs, and others may not. Additionally, the authors are highly repetitive; you want to refer to them by identifier, not by embedding them.
Because a tree of data can be represented easily as a graph, but not vice versa, JSON API provides a straight-forward way to provide a list of records that are linked to each other. The goal is simple, straight-forward processing regardless of the shape of the graph.
On graphs, I was really hoping to see provisions in the spec to support the property graph model, specifically for properties on relationships. We are building APIs that access data in a graph DB, and all the data in the graph has had an obvious representation in the JSON API model except for attributes on edges.
As an example, let's say that my graph DB has People nodes and a MARRIED_TO relationship between two people to indicate they are married. A MARRIED_TO edge could have a "married_on" property containing the date of the marriage.
Where would the "married_on" attribute be represented in JSON API? I could stuff it in the "meta" member of the link object, but that feels loose and hacky. Maybe it could live in the "linkage object" along with the "type" and "id" members. But the linkage object appears to currently be a closed set of only those two members.
Is this requirement to present a full property graph model not as common as I would imagine? I'm a bit behind on my sync with the current state of the spec. This is the first time I've tried to elaborate this need.
At first I was confused by this comment because anything built with links is a graph. Now that I've caught your meaning, and seen the complicated "included" structure, I wonder if it wouldn't have been better to just add an "_id" property to HAL. HAL's designers, however, would probably just say that "author" should be its own resource, and be linked or embedded as required. That is, if it's too heavy to embed, then link it.
Consider the case of a blog. Each blog post has many comments. Each post has an author, and each comment has an author. Some of those entities may have dedicated URLs, and others may not. Additionally, the authors are highly repetitive; you want to refer to them by identifier, not by embedding them.
Because a tree of data can be represented easily as a graph, but not vice versa, JSON API provides a straight-forward way to provide a list of records that are linked to each other. The goal is simple, straight-forward processing regardless of the shape of the graph.