[runeks]

> Have you looked into JSON-ld? Sure it is an extension of json but it has a formal specification which solves all the problems you have with your json examples, specifically the out-of-band issue you have with your json and how to link to other things.

Which problems does it solve, exactly?

When I read the JSON-ld examples I see fields containing @-prefixed links to other JSON documents, but why not just include that JSON in the original document, instead of linking to it?

[chriswarbo]

> When I read the JSON-ld examples I see fields containing @-prefixed links to other JSON documents, but why not just include that JSON in the original document, instead of linking to it?

A few reasons:

- It avoids bloating the response, especially if the referenced data contains other references, and so on.

- It allows cycles, e.g. person A's "spouse" can reference person B, and person B's "spouse" can reference person A.

- We can reference things which we don't know, or haven't bothered to calculate, or aren't permitted to access, or which don't even exist yet. All we need is their URL.

- References aren't simply locations (URLs, which we can GET), they're also identifiers (URIs). URIs let us reference a particular thing, whereas an embedded value might be ambiguous. For example, the value `{"firstName": "Tom", "surname": "Cruise"}` might be talking about the famous actor, or some other person called Tom Cruise. In contrast, a reference like "https://dbpedia.org/page/Tom_Cruise" only refers to the actor.

- URIs are quick and easy to compare, whereas JSON values are computationally harder to compare (especially if we're inlining a whole bunch of related values), and ambiguous; e.g. in the Tom Cruise example above, is that JSON object the same (semantically) as one which also contains `"birthDate": "1962-07-03"`?

[berkes]

> why not just include that JSON in the original document, instead of linking to it?

For me, the reason I'm linking and not including is bandwidth (and load of (de-)serialization). The age-old "pointer vs value" optimization.

When you go overboard, the "state" part of the payload becomes a large part of whats being sent. I've worked with APIs where over 80% of the data was this "cruft" and only 20% was the actual data. It happens esp when you compose your API of many small objects - which in itself has tradeoffs but is often a good practice.