Bunch of editorial issues, part II

[iherman]

As before, some comments are questions that may be the result of my lack of understanding.

• I referred, in Bunch of editorial issues, part I #124, to the problem of @graph appearing out of the blue in example 67. A forward reference to what "@graph" means to example 86 may be a partial solution. (Actually, example 86 is more or less the same as 67! It may be possible to change 67 so that that it makes the usage of "@graph" unnecessary. After all, cross-references within a graph with the same root is also possible.)

• In 4.8.1. "Strictly speaking, the value of such a term is not a named graph, rather it is the graph name associated with the named graph, which exists separately within the dataset." is of course true. But I have the impression that for 99% of the readers this statements is meaningless, I wonder whether it is not more harmful than helpful to have it here:-) (No strong opinion, actually)

• Section 6 says:

  In order to use an external context with an ordinary JSON document, when retrieving an ordinary JSON document via HTTP, processors MUST retrieve any JSON-LD document referenced by a Link Header with:

  I am a little bit bothered by the formulation because, after all, it is not (only) the processor that MUST retrieve, but the server that must play game as well, ie, all this depends (also) on the correct setup server-side. This is somehow missing from the formulation, although it is clear in the example...

• Section 7: we should not cast HTML 5.2 in concrete as the reference to HTML. Afaik https://www.w3.org/TR/html/ always refers to the latest Rec and there are plans to, possibly, make explicit something like https://www.w3.org/TR/html/rec. Better use one of those. (Yep, I am not sure about specref/respec)

• 7.1 the reference to What is 'base' for an embedded json-ld? #23 should be removed; that issue is closed.

• I know I am being very picky, so we may decide to ignore this, but section 8 says:

  "Every node is an IRI, a blank node, a JSON-LD value, or a list.".

  Strictly speaking this is not according to the RDF data model, which does not have a special notion for a list. This difference is not reflected in section 10: the note in that section whereby

  "In JSON-LD lists use native JSON syntax, either contained in a list object, or described as such within a context. Consequently, developers using the JSON representation can access list elements directly rather than using the vocabulary for collections described in [RDF-SCHEMA]..

  could also be said about Turtle, which uses (...) to denote lists, i.e., hiding the list vocabulary of RDF. I am not sure how to put this in a better way, and we may ignore this because (to refer to my statement above) for 99% of the readers this is meaningless, but maybe somebody has a bright idea...

  (Incidentally, the last quote has two full stops at the end)

• Section 9 begins with "This appendix restates the syntactic...". But this is not an appendix, but a bona fide section:-)

• Section 9.1 long paragraph starting with "When used...": any reasons why we use SHOULD NOT and not MUST NOT? (Or is it a backward compatibility issue? If so we should find a formulation that says, for example, if this is a JSON-LD 1.1 document than it MUST NOT). Same remark on the paragraph that follows.

• 9.2 says:

  If the node object contains the @nest key, its value MUST be an dictionary or an array of dictionaries which MUST NOT include a value object.

  There is a bit of a discrepancy between the syntax as used and the terminology here. The only occurrence of @nest as a key is with a term value (or possibly values, I guess) and not with objects; on the other hand, as also described in 9.10, I guess the reason of using objects is because the nesting labels are associated with a specific term and are not absolute. It took me a while to realize this (if my understanding is correct), maybe it is worth emphasizing it.

• I must admit I am a little bit lost by 9.3. If I read that text, I would deduce that the content of example 85 is not a graph object, because it does include a term generatedAt. Or is the graph object the value of "@graph"? But then the text says that I could use "@graph" within the object on example 85: what does that mean?

• The very end of 9.7 says:

  Index Maps may also be used to map indexes to associated named graphs, if the term is defined with @container set to an array containing both @graph and @index, and optionally including @set. The value consists of the node objects contained within the named graph which is named using the referencing key, which can be represented as a simple graph object.

  However, the very usage of index is to define graphs with a name and my understanding is that the term "simple graph object" is for graphs that does not have an explicit name (i.e., their name is a blank node). What do I misunderstand here?

• Is this correct (in 9.11)? "If the expanded term definition contains the @nest keyword, its value MUST be either @nest, or a term which expands to @nest." This sounds circular to me; isn't the value of @nest a term, or an array of terms?

• Appendix E includes references to the closed issues HTTP parameters for specifying context or frame #8, What is 'base' for an embedded json-ld? #23, Expanding @vocab properties consistently #56, Weird wording in spec of Iri Compaction #75, Allow @type for @none in Language Maps #91; these should be removed. (I cannot check whether other issues should be listed, I am on a plane:-)

[gkellogg]

• I referred, in Bunch of editorial issues, part I #124, to the problem of @graph appearing out of the blue in example 67. A forward reference to what "@graph" means to example 86 may be a partial solution. (Actually, example 86 is more or less the same as 67! It may be possible to change 67 so that that it makes the usage of "@graph" unnecessary. After all, cross-references within a graph with the same root is also possible.)

I addressed this when describing the top-level use of arrays in the "Describing disconnected nodes with @graph" in 4.1; see if that helps.

[gkellogg]

• In 4.8.1. "Strictly speaking, the value of such a term is not a named graph, rather it is the graph name associated with the named graph, which exists separately within the dataset." is of course true. But I have the impression that for 99% of the readers this statements is meaningless, I wonder whether it is not more harmful than helpful to have it here:-) (No strong opinion, actually)

Thus the "Strictly speaking" bit, but if it's not there RDF pedants will complain! I'll leave it for now.

[gkellogg]

• I am a little bit bothered by the formulation because, after all, it is not (only) the processor that MUST retrieve, but the server that must play game as well, ie, all this depends (also) on the correct setup server-side. This is somehow missing from the formulation, although it is clear in the example...

As this is straight 1.0 text, I'm inclined to leave as is. If you can think of a better formulation, than please suggest.

[gkellogg]

Is this correct (in 9.11)? "If the expanded term definition contains the @nest keyword, its value MUST be either @nest, or a term which expands to @nest." This sounds circular to me; isn't the value of @nest a term, or an array of terms?

We went over this in the F2F, so it should be clear now. the @nest in a term definition is used for compaction to know where to serialize the property, thus the value of @nest has to be something which expands to @nest.

[iherman]

• Bunch of editorial issues, part II #127 (comment): Indeed, this is helpful (but look at Editorial issues #130 (comment)).
• Bunch of editorial issues, part II #127 (comment): what about saying something like:

  In order to use an external context with an ordinary JSON document, when retrieving an ordinary JSON document via HTTP, processors MUST attempt to retrieve any JSON-LD document referenced by a Link Header with:
  ...
  if provided by the server.

• Bunch of editorial issues, part II #127 (comment): well, I am still confused. Looking at examples Improve data model diagram with examples showing different encodings. #69 and Test PR Preview #71 (in the Editorial issues #130 PR version) the two JSON-LD examples only differ from one another by the extra "@nest":"labels" but their expanded/turtle forms are absolutely identical. Which suggests that the extra "@nest":"labels" in the definition of main_label and other_label is superfluous...

[gkellogg]

@iherman said:

• well, I am still confused. Looking at examples Improve data model diagram with examples showing different encodings. #69 and Test PR Preview #71 (in the Editorial issues #130 PR version) the two JSON-L

I'll add a bit more to this, the distinction comes in the compaction algorithm (I probably removed that phrase, because you thought a reference to the compaction algorithm was overly complex and out of place).

The point is, that because the term definitions for main_label and other_label have @nest: labels, the compaction algorithm knows to place those properties under labels, rather than place them along with the other node properties.

[gkellogg]

@iherman said:

any reasons why we use SHOULD NOT and not MUST NOT?

I can't recall specifically why SHOULD NOT and not MUST NOT for the first paragraph. In the second paragraph, it may be reasonable for other specifications to define keywords starting with @ that may never get into JSON-LD itself, so it can serve as an extension point.

[gkellogg]

@iherman said:

There is a bit of a discrepancy between the syntax as used and the terminology here. The only occurrence of @nest as a key is with a term value (or possibly values, I guess) and not with objects.

Whenever a term aliasing a keyword can be used, that keyword can be used itself; there's a statement at the top of 9. which describes this to avoid repetition. In the labels case, as it aliases to @nest, it would be legitimate (but not particularly useful) to use @nest as a key itself. But, this is a grammar section which is strict and minimal about what can be allowed where.

[gkellogg]

@iherman said:

I must admit I am a little bit lost by 9.3. If I read that text, I would deduce that the content of example 85 is not a graph object, because it does include a term generatedAt. Or is the graph object the value of "@graph"? But then the text says that I could use "@graph" within the object on example 85: what does that mean?

Yes, this is confusing, and I'll attempt to improve. A graph object only describes a named graph, if it includes other properties, it's a node object, but a node object can also describe a named graph if it includes @graph, or has a property which is a graph container. It is necessary to distinguish between the different forms, as there are times when graph objects can be used by API algorithms if they're not node objects.

[iherman]

Any reasons why we use SHOULD NOT and not MUST NOT?

I can't recall specifically why SHOULD NOT and not MUST NOT for the first paragraph. In the second paragraph, it may be reasonable for other specifications to define keywords starting with @ that may never get into JSON-LD itself, so it can serve as an extension point.

I am fine with the SHOULD NOT for the second paragraph. I guess the only reason the first paragraph may be more reasonable to be SHOULD NOT, I reckon, is that a MUST would require that an implementation checks the current list of IANA schemes at all times, which becomes a drag.

[iherman]

The point is, that because the term definitions for main_label and other_label have @nest: labels, the compaction algorithm knows to place those properties under labels, rather than place them along with the other node properties.

I presume a somewhat more explicit explanation, as well as showing possibly the result of the compaction algorithm (with due forward reference to what compaction means) would be necessary to make the result understandable.

[iherman]

For #127 (comment), I will wait until the revision comes...

B.t.w., the word "include" is repeated in the first sentence of the section...

[iherman]

For #127 (comment), I will wait until the revision comes...

Actually, I realized that you have made changes in #130. I think it is all right now, although this discrepancy between graph objects and a node object that also describes a graph is a bit confusing. But I presume it is too late to change the full terminology.

---

Incidentally: I realized that the 'diff' generation in PR does not seem to refresh itself after a new commit (the preview does)...

[gkellogg]

Closed via #130.