Explanation of examples

[iherman]

The various examples are shown in other syntaxes in a somewhat inconsistent manner: most of them use the result of the expansion but some of them use a table figuring, essentially, the triples.

Also, the usage of the expansion algorithm to illustrate the example is not really helpful, mainly at first reading. Most of the examples are in sections 3 and 4, whereas the expansion algorithm is defined at the very end of section 4 (in 4.25). Also, the result of the expansion algorithm, while o.k. for machine processing, is not always intuitive: e.g., everything is put into arrays, even in cases when this is fairly unexpected for a JSON reader.

I would propose two editorial changes in this respect.

1. Move sections 4.25-4.27 into a separate top level sections. These are important for the handling of JSON-LD files, but not necessary important for the understanding of JSON-LD.
2. For every examples, there should be an equivalent of the example in the expanded form, in a table with the triples, in turtle (as close to the JSON-LD structure as possible) and, possibly, as graphs. Not all of them would appear on the screen at the same time but, rather, the reader could choose what to see with some tabs.

(A good example for such an approach is in the OWL Primer, where there is tab at the top that governs what syntax the reader would like to see.)

[gkellogg]

There are a couple of things going on:

• examples with no transformation
• examples of document expansion, which may take a document with optional context and show the expanded form or quads, in the form of a table
• examples of compaction or framing
• examples of flattening.

Typically, when a transformation is shown, it's the tabular form which is shown, quite often, the transformation is not shown inline. Where we do show the tabular form, it could make sense to allow this to be either expanded, flattened, TriG, tabular and perhaps even graphical. I'd favor a control on the example result, rather than a document-wide setting personally. Note that there is a Travis-CI setup which does some basic syntax checking, which could be enhanced to validate all transformations (although, tabular isn't quite normalized enough to do this easily, right now).

Do we want to add more transformations for other examples? That could certainly blow up the size of the document, but might be useful. Alternatively, a link to the playground that loads the source could allow this kind of interaction without blowing up the document size.

[iherman]

Explicit examples for framing or flattening are of course a separate issue.

I think that consistency is important: all examples (excep for the flattening/expansion ones, of course) must have the same series of examples, whether it makes a lot of sense or not. And relying on playground is not an option for me: I may not always be on-line (I reviewed the document, and gathered these comments, on a plane) and playground may be down...

If we can have a control over each example easily, I would also be in favour of that. And if the document is large: let us be it. We will sill be smaller than the HTML doc, and infinitely more readable:-)

[iherman]

B .t.w., on my last remark: if the document is too large as one HTML file, we can consider cutting the text into several files (within on recommendation) like HTML or SVG does it...

[BigBlueHat]

@iherman do you know of any specs that use multiple representations/displays at once--thinking something like this would be nice https://schema.org/Person#Invoice-gen-43

[gkellogg]

@iherman originally referenced the OWL Primer, but I'd like to do something more granular, say with buttons below examples, which would open each variation inline. The ShEx Spec does something similar, but the key-binding is annoying (see example in http://shex.io/shex-semantics/#shapes-schema).

[iherman]

@BigBlueHat, @gkellogg referred to the examples that would come to my mind...