(Mostly) Editorial issues Part I

[iherman]

• [x] I think adding the same choice of example syntaxes as in the syntax document would be good (for the framing results).
• [x] 2.3.1. It is a bit unclear why one has to use the value of "@last" and "@never" rather than using boolean values. Those two terms do not look very intuitive for me...
• [x] 2.3.2, first paragraph: for the purpose of readability I would switch the last two sentences.
• [x] Last sentence of 2.3.2: "fram" -> "frame"
• [x] An example for the omit default flag should be added to to 2.3.3.

[gkellogg]

• I think adding the same choice of example syntaxes as in the syntax document would be good (for the framing results).

I didn't think it always made sense; you have an example with a source document, an example with the frame, and an example with the result, which are all related internally so they can be verified. We could provide both an expanded and compacted version of the source document, but as the entire point of the document is how to create the syntactic framed result, showing expanded, TriG, and tabular versions of this is not germane to the use cases being described. The only reason to do this is so that examples look the same in syntax and framing docs (and API), but it won't be useful in helping people to understand the point of framing.

[iherman]

Maybe you are right. Personally, I still 'see' things better in Turtle, but that may only be me.

[gkellogg]

• 2.3.1. It is a bit unclear why one has to use the value of "@last" and "@never" rather than using boolean values. Those two terms do not look very intuitive for me...

At one time, @embed was simply boolean valued, but as more was taken on, the value space evolved to include @always, @last (synonym for true), and @never (synonym for false). Arguably, the boolean values should be deprecated/removed, if anything. These are described in 4.1.

• @always, as it says, always embeds values, even if it leads to duplication,
• @last ensure that a value is embedded, but does not do duplication, and
• @never ensures that values are never embedded, although they may be included in a different part of the JSON tree as expanded.

[iherman]

Ouch. I got caught on one thing: I did not go into the details yet for the terminology, where @always is mentioned. However, in the informal description of framing, i.e., section 2, @always is not even mentioned, let alone there is no example.

I agree that if it is a three-way option then boolean is not appropriate.

[dlongley]

There also is a fourth option implemented in jsonld.js: @link (which does in-memory links for embeds). I can't remember why we dropped support for this in the spec; I searched around and didn't see anything.

[gkellogg]

We dropped it, as the result of @link can’t be expressed in JSON. There was a discussion for another spec that might do this to represent in-memory results or some other format that could represent graphs with cycles.

[dlongley]

@gkellogg, Ok, thanks.

[azaroth42]

:+1: to deprecating the booleans (though we shouldn't remove them)

[gkellogg]

For the omit default flag, I raised issue #41.

[gkellogg]

@azaroth42 the booleans look odd next to keywords, and as this has never been published, I don't think our spec needs to mention them, but my implementation (and I expect @dlongley's) will support them indefinitely.

[gkellogg]

@dlongley I added an @omitDefault example which works, but doesn't really illustrate why you might want to use it. (I don't really understand myself). Perhaps you can improve it?

[gkellogg]

Closed via #42.