How can json-api be compared to json-ld?

[thasmo]

I've just found out about json-ld and was wondering if it's goal's are similar to the ones of json-api and/or if there are fundamental differences between them?

[passy]

It's going to be covered in the FAQ: #1

[thasmo]

Ah, thanks! :)

[steveklabnik]

Yup.

[jokeyrhyme]

Just a heads up: JSON-LD IS A W3C RECOMMENDATION

[mpetyx]

I was just looking both at #1 and at FAQ and I did not see any further discussion on the comparison between JSON-LD and json-api.
Is this somewhere else that I did not look?
I can see that in json-api there is also discussion about REST Actions which is something I like, and partly similar (in the JSON-LD world) to what could be described by Hydra.
I would love to see this discussion moving, so please let me know if you are interested on this and if I could contribute somehow.

[almibe]

Maybe this needs reopened? I still don't see any mention of json-ld in the faq. If on the other hand json-api doesn't want to compare itself to any linked data or semantic web technologies in general because the goals are so different, maybe a blanket statement regarding that should be in the faq.

[jokeyrhyme]

@passy ? @steveklabnik ?

[almibe]

I'll take this as a "the goals are too different to even compare".

[ethanresnick]

Hi @almibe and @jokeyrhyme. Sorry this thread hasn't had much activity; I think people have just been busy.

Anyway, here's my personal take on this, which may not represent the views of the other editors:

• JSON LD's about saying, for each value in the response, this value is a certain kind of thing (e.g. "the string at the document's /people/0/name path is a firstName, in the schema.org meaning of the term"). Doing this type of labeling can have advantages for machine consumption of an api, for integration between different apis, and sometimes for API evolvability. But many projects don't get much practical benefit from this labeling, and implementing JSON LD has costs, too. As an API author, the cost is that I have to find (or, just as often, invent) vocabularies that adequately describe my data; as a client, I have to bring in a json-ld parsing aparatus (JSON LD parsing is non-trivial) and learn a new data model.
• JSON API is about taking commonly-supported API features, like including related resources or accepting partial resource updates, and defining a standard way that servers should expose those features. This makes it possible for API client developers to use drop-in code to interact with an API, because that API will do these common things just like every other JSON API. It also saves API authors from having to reinvent the wheel each time and, hopefully, since the JSON API conventions are pretty well thought out, it saves them from making subtle design mistakes that might hurt them later.

So, basically, JSON API says "for convenience and encouraging good design, let's standardize the best practice version of what we're doing now", whereas JSON LD says "let's use a new data model, with shared vocabularies, and new tools to get some new semantic-webby benefits".

JSON API isn't actually opposed to any of JSON LD's ideas—in fact, JSON API will support extensions that allow the two to interoperate—but I/we just think that the JSON LD worldview should be opt-in, and that developers should be able to get simple conveniences today without having to change as much of their thinking as JSON LD demands.

[jokeyrhyme]

@ethanresnick thanks, this makes sense.

[almibe]

Thanks for the response from what I know about JSON-LD I'd agree with that. I was curious how well the two could work together and the possibility of them benefiting each other sounds like it's worth experimenting with.

[ethanresnick]

I was curious how well the two could work together and the possibility of them benefiting each other sounds like it's worth experimenting with.

From the playing around that I've done, they integrate quite well. For example, it's pretty easy to properly annotate a typical JSON API response with JSON LD. Occasionally, some duplicate JSON LD @id declarations are required, as, without them, JSON LD's @context mechanism isn't quite expressive enough to annotate the JSON API structure. But this duplication has very little effect on transport size (it gets gzipped away) and no effect on the resulting JSON LD data; the JSON LD parser outputs the data graph, independent of the serialization format it came in, so you end up with very clean data.

I'd definitely encourage you to experiment further, though, and to share your findings on the JSON API forum (http://discuss.jsonapi.org). I'm curious to hear about any integration problems you run into or any cool things that you're able to do by combining the two formats.

[almibe]

Could this issue be reopened until there is an official response in the FAQ? Or are github issue responses the new FAQ ;)

[ghost]

definitely still valid today.

[geoidesic]

Sounds like we're gradually turning JSON into XML.