Bunch of editorial issues, part I

[iherman]

In preparing for the F2F I am re-reading the syntax document. I have spotted a bunch of issues that I consider editorial. Instead of filing a whole lot of mini issues, I have collected them here; I guess that these are really of interest for @gkellogg and @pchampin.

This is the first batch; I have to go to do something else now. I will try to get to the end of the document tomorrow, using my airport waiting time and so...

• Section Set of Documents: I guess the reference to JSON-LD should go to the /TR URL (like for the API and framing) and not to the editor's draft...

• The terms embedded and scoped contexts should be added to the list of terms in 1.4.

• I 1.4, it says "A list object is a dictionary that has a @list key.". Shouldn't it say "... that has @list as a unique key."? I guess the same for set.

• in 1.6: "Within a directed graph, nodes with may be unnamed,...": 'with' is probably superfluous.

• section 2: the first and third paragraphs are repetitive. I would think the first one is automatically generated by respec...

• section 2, namespace table: the only occurrence of the cred namespace is in its full expanded (URI) form, and not as a prefix. Should be removed from the table. The same holds for geojson and prov.

• In both example 3 & 4 the comments overflow, ie, one has to scroll horizontally. Not very pleasant...

• In 3.2: also in view of the separate discussion in IRI-s vs. URL-s #25 it may be a good idea to emphasize that IRI-s may also include non-URL-s, and that is absolutely fine as far as JSON-LD goes. A separate example using, for example, a uuid or doi IRI, or somethings similar, maybe helpful at that point...

• in 3.5: in the last two nodes the @type is not systematically marked with a <code>...

• in 3.5: it is difficult to understand what this quote:

  The ability coerce a value using a term definition is distinct from setting one or more types on a node object, as the former does not result in new data being added to the graph, while the later manages node types through adding additional relationships to the graph.

  means at this point. I wonder whether it is not better placed in the section that describes type coercion...

• Section 4.1 example 18 is the first example where the top level of the JSON-LD fragment is an array and not an object. I think this deserves a somewhat more detailed explanation, because (this is the same graph with two different objects, ie, this is a bush and not tree, etc). This also emphasizes why the fact that "contexts may be used any time a dictionary is defined." makes real sense even on the top level.

• Also, in the same section: isn't what is described the in example 19 what we refer to as 'embedded context'? It may be worth naming this, it helped us in the discussions, it may help others...

• For some reasons, the link to the playground from example 24 yields a bunch of strange errors...

• No tabs to the various version ins example 25

• I am not sure I understand the two paragraphs after example 30 in section 4.1.4. Is the first paragraph, ie,

  In JSON-LD 1.0, terms may be chosen as compact IRI prefixes when compacting only if a simple term definition is used where the value ends with a URI gen-delim character (e.g, /, # and others, see [RFC3986]). The previous specification allows any term to be chosen as a compact IRI prefix, which led to a poor experience.

  The second sentence seems to contradict the first. And I looked into 1.0 and did not find such a restriction, although I may have missed it. Isn't it possible that the first sentence (which is repeated in the paragraph that follows) is what we introduce in 1.1? On the other hand, the paragraph after the note seems to repeat the same information as the one before the note.

• After example 32: "the term is a keyword are be ignored." the word 'be' is superfluous.

• I failed to understand, I must admit, the description after example 32. Also: as a casual reader, at this point, I do not know what 'compaction algorithm; and @container with a value @set means, so the whole paragraph, and the following example, is a mystery. Maybe this whole part should be moved to the compaction algorithm where it gets some sense...

• In the note "Aliased keywords MUST NOT be used within a context, itself.": is the comma necessary before 'itself'?

• This description (after example 40):

  When expanding, each value of @type is considered (ordering them lexographically) where that value is also a term in the active context having its own embedded context. If so, that embedded context is applied to the active context. When compacting, if a term is chosen to represent an IRI used as a value of @type where that term definition also has an embedded context, it is then applied to the active context to affect further compaction.

  would deserve its own example. It is very difficult to understand what it is (I failed...) Most notably, the first-time reader does not understand what 'Compacting' means, in fact. Maybe move that into the compaction section? (B.t.w., it should be 'lexicographically'...)

• (still barney...) after 46 it may be worth adding why the expansion of barney is different: the first occurrence is based on @id, hence is a relative URL, etc... Just to help the reader!

• Example 61, lists of lists... the definition does not really make it clear that "@container":"@list" is, sort of, recursive. At first read what it says that the immediate children are lists, but that does not necessary means (from the text) that the array:

          [-10.0, -10.0],
          [10.0, -10.0],
          [10.0, 10.0],
          [-10.0, -10.0]
  

  is itself a list. It only says that if I have several of these groups, those constitute a list. (is this an editorial comment, actually?)

• for the first time reader, the usage of @graph to denote a bush does come a bit out of the blue in example 67. This explains a separate explanation (including emphasizing the difference between a tree and a bush?).

• end of 4.5.1 says:

  It is worth noting that blank node identifiers may be relabeled during processing. If a developer finds that they refer to the blank node more than once, they should consider naming the node using a dereferenceable IRI so that it can also be referenced from other documents.

  Was this fact also true in JSON-LD 1.0? I thought the algorithm included an explicit way of generating the blank node id-s, which made them, essentially, fixed. If so, it may be worth emphasizing that in 1.1 the user should not expect that...

• After example 71 in 4.6.1 it says:

  This allows a developer to access the German version of the post using the following code snippet: obj.post.de.

  I think this should deserve a little bit more explanation as for obj.post.de: something whereby if the JSON-LD snippet is used by a traditional JSON processor in, e.g., Javascript, then this type of access to the values is made available, or something like that. Just say "code snippet" is a bit unclear for the reader and would look for something related to the JSON-LD processor code or something similar...

• I really believe that Section 4.8 should be separated from the rest of section 4. It is a very different ballgame when one begins to fiddle around with graphs...

[pchampin]

I have a list of my own that I was planning to post as well. I'll append it here ASAP, and implement the changes -- expect for those where I'm not sure if it's purely editorial, of course.

…

[gkellogg]

In preparing for the F2F I am re-reading the syntax document. I have spotted a bunch of issues that I consider editorial. Instead of filing a whole lot of mini issues, I have collected them here; I guess that these are really of interest for @gkellogg and @pchampin.

This is the first batch; I have to go to do something else now. I will try to get to the end of the document tomorrow, using my airport waiting time and so...

• Section Set of Documents: I guess the reference to JSON-LD should go to the /TR URL (like for the API and framing) and not to the editor's draft...

This is handled at publication time automatically using the conversions described in json-ld.js. This was based on something you did for CSVW. Keeping them pointing to editorial versions for the editorial drafts makes sense to me.

• The terms embedded and scoped contexts should be added to the list of terms in 1.4.

👍

• I 1.4, it says "A list object is a dictionary that has a @list key.". Shouldn't it say "... that has @list as a unique key."? I guess the same for set.

Except that it can also contain @context and @data, although that's not real common usage.

• in 1.6: "Within a directed graph, nodes with may be unnamed,...": 'with' is probably superfluous.

👍

• section 2: the first and third paragraphs are repetitive. I would think the first one is automatically generated by respec...

👍

• section 2, namespace table: the only occurrence of the cred namespace is in its full expanded (URI) form, and not as a prefix. Should be removed from the table. The same holds for geojson and prov.

They're used in examples in Turtle and Tabular representations.

• In both example 3 & 4 the comments overflow, ie, one has to scroll horizontally. Not very pleasant...

How do you think we should handle such commenting?

• In 3.2: also in view of the separate discussion in IRI-s vs. URL-s #25 it may be a good idea to emphasize that IRI-s may also include non-URL-s, and that is absolutely fine as far as JSON-LD goes. A separate example using, for example, a uuid or doi IRI, or somethings similar, maybe helpful at that point...

👍

• in 3.5: in the last two nodes the @type is not systematically marked with a <code>...

👍

• in 3.5: it is difficult to understand what this quote:

  The ability coerce a value using a term definition is distinct from setting one or more types on a node object, as the former does not result in new data being added to the graph, while the later manages node types through adding additional relationships to the graph.

  means at this point. I wonder whether it is not better placed in the section that describes type coercion...

• Section 4.1 example 18 is the first example where the top level of the JSON-LD fragment is an array and not an object. I think this deserves a somewhat more detailed explanation, because (this is the same graph with two different objects, ie, this is a bush and not tree, etc). This also emphasizes why the fact that "contexts may be used any time a dictionary is defined." makes real sense even on the top level.

👍

• Also, in the same section: isn't what is described the in example 19 what we refer to as 'embedded context'? It may be worth naming this, it helped us in the discussions, it may help others...

👍

• For some reasons, the link to the playground from example 24 yields a bunch of strange errors...

Looks like an issue where the playground is not up to date (been some time, now 🤕 ).

• No tabs to the various version ins example 25

The tabs for this are in example 26, which says that it is the expanded version of what is shown in 25.

• I am not sure I understand the two paragraphs after example 30 in section 4.1.4. Is the first paragraph, ie,

  In JSON-LD 1.0, terms may be chosen as compact IRI prefixes when compacting only if a simple term definition is used where the value ends with a URI gen-delim character (e.g, /, # and others, see [RFC3986]). The previous specification allows any term to be chosen as a compact IRI prefix, which led to a poor experience.

  The second sentence seems to contradict the first. And I looked into 1.0 and did not find such a restriction, although I may have missed it. Isn't it possible that the first sentence (which is repeated in the paragraph that follows) is what we introduce in 1.1? On the other hand, the paragraph after the note seems to repeat the same information as the one before the note.

This is from an errata, where we changed the behavior for 1.0 processors to place some restrictions on what can be used to create a prefix fo compact IRIs.

We could simplify the second paragraph to something like:

Additionally, in JSON-LD 1.1, terms may also be used as compact IRI prefixes if their expanded term definition contains a @prefix member with the value true.

• After example 32: "the term is a keyword are be ignored." the word 'be' is superfluous.

👍

• I failed to understand, I must admit, the description after example 32. Also: as a casual reader, at this point, I do not know what 'compaction algorithm; and @container with a value @set means, so the whole paragraph, and the following example, is a mystery. Maybe this whole part should be moved to the compaction algorithm where it gets some sense...

We need something in the syntax document, as it describes legal syntax for authors to use, while the API document is targeted more at tool developers; perhaps you can suggest an alternate wording?

• In the note "Aliased keywords MUST NOT be used within a context, itself.": is the comma necessary before 'itself'?

I think so, but this gets into english grammar.

• This description (after example 40):

  When expanding, each value of @type is considered (ordering them lexographically) where that value is also a term in the active context having its own embedded context. If so, that embedded context is applied to the active context. When compacting, if a term is chosen to represent an IRI used as a value of @type where that term definition also has an embedded context, it is then applied to the active context to affect further compaction.

  would deserve its own example. It is very difficult to understand what it is (I failed...) Most notably, the first-time reader does not understand what 'Compacting' means, in fact. Maybe move that into the compaction section? (B.t.w., it should be 'lexicographically'...)

We can improve this wording and provide some examples of use. So as to not overburden the spec with examples, we might consider doing this in a separate document.

• (still barney...) after 46 it may be worth adding why the expansion of barney is different: the first occurrence is based on @id, hence is a relative URL, etc... Just to help the reader!

👍

• Example 61, lists of lists... the definition does not really make it clear that "@container":"@list" is, sort of, recursive. At first read what it says that the immediate children are lists, but that does not necessary means (from the text) that the array:

          [-10.0, -10.0],
          [10.0, -10.0],
          [10.0, 10.0],
          [-10.0, -10.0]
  

  is itself a list. It only says that if I have several of these groups, those constitute a list. (is this an editorial comment, actually?)

I'll look at it further. Suggestions for improved wording appreciated.

• for the first time reader, the usage of @graph to denote a bush does come a bit out of the blue in example 67. This explains a separate explanation (including emphasizing the difference between a tree and a bush?).

Worth a further explanation.

• end of 4.5.1 says:

  It is worth noting that blank node identifiers may be relabeled during processing. If a developer finds that they refer to the blank node more than once, they should consider naming the node using a dereferenceable IRI so that it can also be referenced from other documents.

  Was this fact also true in JSON-LD 1.0? I thought the algorithm included an explicit way of generating the blank node id-s, which made them, essentially, fixed. If so, it may be worth emphasizing that in 1.1 the user should not expect that...

In 1.0 and 1.1, flattening and framing relabel blank nodes. And, of course, in RDF generation. You can use a blank node in JSON-LD, and it is largely honored through expansion and compaction, but otherwise, it's similar to other RDF serializations.

• After example 71 in 4.6.1 it says:

  This allows a developer to access the German version of the post using the following code snippet: obj.post.de.

  I think this should deserve a little bit more explanation as for obj.post.de: something whereby if the JSON-LD snippet is used by a traditional JSON processor in, e.g., Javascript, then this type of access to the values is made available, or something like that. Just say "code snippet" is a bit unclear for the reader and would look for something related to the JSON-LD processor code or something similar...

👍

• I really believe that Section 4.8 should be separated from the rest of section 4. It is a very different ballgame when one begins to fiddle around with graphs...

It's an advanced concept, and making it a top-level section would actually give it more weight, so I'm not quite on the same page.

[gkellogg]

I am not sure I understand the two paragraphs after example 30 in section 4.1.4. Is the first paragraph, ie,
In JSON-LD 1.0, terms may be chosen as compact IRI prefixes when compacting only if a simple term definition is used where the value ends with a URI gen-delim character (e.g, /, # and others, see [RFC3986]). The previous specification allows any term to be chosen as a compact IRI prefix, which led to a poor experience.

The second sentence seems to contradict the first. And I looked into 1.0 and did not find such a restriction, although I may have missed it. Isn't it possible that the first sentence (which is repeated in the paragraph that follows) is what we introduce in 1.1? On the other hand, the paragraph after the note seems to repeat the same information as the one before the note.

This is the subject of an errata for 1.0 that affected the way terms are selected when compacting an IRI into a compact IRI; previously, any term would do, which led to numerous issues https://lists.w3.org/Archives/Public/public-rdf-comments/2018Jan/0002.html.

[gkellogg]

I failed to understand, I must admit, the description after example 32. Also: as a casual reader, at this point, I do not know what 'compaction algorithm; and @container with a value @set means, so the whole paragraph, and the following example, is a mystery. Maybe this whole part should be moved to the compaction algorithm where it gets some sense...

Perhaps if we just remove the sentence:

This is used by the Compaction algorithm to ensure that the values of @type (or an alias) are always represented in an array.

The other text is necessary, as we're describing the limitations on aliasing keywords, where @type is an exception, and this is the aliasing keywords section. This isn't about compaction directly, but about the legal ways that @type can be used in the context. Moving the but about @container: @set later on would be out of place, IMHO.

[iherman]

• Bunch of editorial issues, part I #124 (comment): I understand now, it was not clear when I read it for the first time. Didactically/visually it may be a god idea to move the subsequent Note after example 31; probably, when I read it, I did not realize that example 31 is there to help to understand it.

  However, what may have also been the problem at first reading is that the paragraph before and after that note seem to convey exactly the same information. I think removing the paragraph after the note and move the note after example 31 may do the trick.

• Bunch of editorial issues, part I #124 (comment): I understand the intention, still finding it a bit disturbing for a first-time reader... Note that this is the only place in the document where the "@type":{"@container":"@set"} idiom appears in the document and makes it hardly understandable. I would think that

  1. create a separate subsection in 4.3.2. that shows the current example 33 and explains what it means

  2. put a forward reference in 4.1.5 to that new subsection. This could be put at the end of the sentence "Other than for @type" saying something like

     When processing mode is set to json-ld-1.1, there is an exception for @type; see section x.y.z for further details.

[gkellogg]

Closed via #130.