[Proposal] Link object always have the same data structure


I am currently trying to create my own implementation of JSON API library. I notice the spec says that the link value can be a string or an object.

All the links have the same structure: { href: '', meta: { ... } } or { href: '' }


  • Consistency in APIs, easy for consumers
  • The Link object should have the same output
  • Easy to test/implement
  • Non conditional statements for data manipulation (string vs object)


  "self": { "href":  "url/to/resource" }
  "self": { "href":  "url/to/resource", meta: { counts: 10 } }


I love your passion for convention over configuration.

That said, in the the last 3 points, if you do not have any data to place into the meta object, you’d be left with a) an empty object b) the requirement to put meta: null or c) leave out the meta object

Also, the meta object may contain more than one key, which also violates your proposal

Thus, it seems these points

- The Link object should have the same output
- Easy to test/implement
- Non conditional statements for data manipulation (string vs object)

are, for better or worse, un-avoidable, or am I missing some of your argument?

Can you explain more - if so, thanks!


My preference is C, because I don’t want to send some bites :smiley: but with the same output issue probably is better A

What do you mean? I don’t understand.


Well technically the self link (in the spec) doesn’t have a meta object, the related link does. But the general definition of the meta object(which is very open and has no specifics depending on ‘where’ in a json api response its used) says:

Where specified, a meta member can be used to include non-standard meta-information. The value of each meta member MUST be an object (a "meta object").

Any members MAY be specified within meta objects.

Which means its pretty much a free for all key -> object - so good question in general I’d say, just not sure if there is a way out of that


@eriktrom this is something I dont understand btw

Note: Additional members may be specified for links objects and link objects in the future. It is also possible that the allowed values of additional members will be expanded (e.g. a collection link may support an array of values, whereas a self link does not).

So self link is just a string, related have meta with count??!?!?!?!? I am lost.

I just see this as { href: '...', meta: { whatever you want } } Do I missing something?


Yeah this part is confusing I agree. That line (i believe) is saying ‘we might add to what you can put in the links object’. For example they might make to-many relationships be an array of links similar to how the data key is an array when those relationships are embedded in the ‘included’ key of the same payload. This would prevent a trip over the wire just to get the related resource object (which is what the self link inside a relationship object, like comments or author, points too) (just a guess, but i guess that’s the point, its there to note ‘this may be extended in the future, but we don’t know how yet’)

One rule of thumb that may help in general is If you dont think about the links being external (via urls) but instead write the code to handle embedded related resources first. I think it’ll be easier to reason about. At least that helped me. Once that makes sense, then you can limit the size of the initial payload at the cost of making more than one request to fetch the related resources.

Someone should have a better answer than me tomorrow I’d say, but that’s my guess.

FWIW - i just re-read the spec, so worthwhile question indeed.


yeah and for the meta: { …whatever you want } is correct :slight_smile: dont use it, unless you see a use case of course :slight_smile: (pagination might be one)


You’re correct, @ubi.

Of course, allowing the string form makes responses more concise, at the expense that consumers have to support both forms. Whether that’s a good tradeoff is debatable, but at this point, the ship has sailed. That is: if we allowed clients not to support the string form now, that would break their support for APIs that are already using the string form, and JSON API has committed to not making such breaking changes. So this is a non-starter for now, I’m afraid.


It’s fine.

About the point of changing the spec, that’s a common in software development, nobody should expect that something will be the same the entire time.

I just want to alleviate the pain to everyone, developers and consumers.