JSON-LD introduction via data model

[lanthaler]

This issue was raised by @cygri as part of #47:

Finally, but that's again another rant for another day: Once the data model is really clear, I think that JSON-LD should really be introduced by listing all the ways how its data model differs from the JSON data model. So, all the things it adds above vanilla JSON. Arbitrary graphs instead of trees. Hyperlinks within and across documents. I18n and arbitrary data types. Expansion of keys into globally unique IRIs. I think this is really important. If you cannot explain to a JSON developer why they should care about these additions over plain JSON, then you get the RDF/XML problem where people try to produce the stuff with XML goggles on without understanding at all what's going on

[msporny]

I had a fairly lengthy discussion with @cygri on this and we came up with an idea of what could be done to resolve this issue. The notes below are very rough and are mainly meant as a reminder to me on how to re-organize the introduction to the JSON-LD spec. In general, the introduction should be re-written to do the following things, in this order:

1. Basic Introduction to what JSON-LD is about.
2. Basic introduction to the JSON model and what JSON-LD enables over the regular JSON model. Try to use JSON model terminology as much as possible at this stage.
3. An introduction to the JSON-LD data model (this is currently the Linked Data section, but it may be renamed to avoid conflict in the RDF WG)

This approach is geared toward people that know JSON and is meant to be a gentle migration into JSON-LD. Hopefully, this will make the introduction flow a bit more nicely.

[lanthaler]

RESOLVED: Rewrite the introductory portions of the JSON-LD document to explain JSON-LD in JSON terms first, then describe the advantages of JSON-LD, then rework the Linked Data section as the JSON-LD data model section.

[lanthaler]

I closed issue #158 as it is a duplicate of this issue:

@cygri does not believe that we should normatively define Linked Data. The concern is that the moment we formally define Linked Data, that it allows people to say that format X is Linked Data and format Y is not. The definition of Linked Data was never meant to be used in that way, but rather it was meant to promote the idea of publishing de-reference-able structured data. Linked Data may look very different in 15 years than it does today (just like the Web looks very different today than it did 15 years ago).

The alternative would be to change the word "Linked Data" to the "JSON-LD Data Model". This would avoid the issue above. However, we also want to make sure that we do have some agreed-upon text by the RDF WG and the JSON-LD CG that constitutes the minimum requirements of Linked Data. This text should go into the JSON-LD specification, but in a more informal way than what we have today.

[msporny]

This issue was addressed in commit 4628fe8. Closing the issue. @cygri please let us know if you agree with the changes. If you disagree, please state what changes you'd like to see (be specific) and re-open the issue.

[cygri]

+1 to the new Section 3.1; this address my comment.

I'd say that the two six-item lists in 3.1 are quite redundant, and the second list is probably sufficient to get the point across. That's just an editorial comment.

[cygri]

Thinking more about it, I believe that the section “3.1 Benefits of JSON-LD” should be moved to Section 2 and made non-normative. It provides rationale, and not basic concepts.

[lanthaler]

I agree with Richard on this. The two (three) lists could should combined and probably the whole section should be moved into section 1 (I think that would work better than moving it to section 2).