Clarify the meaning of multiple node definitions with the same @id

[gkellogg]

From Peter Patel-Schneider:

• no discussion on multiple node definitions with the same id

[gkellogg]

True, this becomes apparent when examining the Flatten API method [2] though.

However, I do think that making this explicit in the syntax document is a good idea.

PROPOSAL: Define the interpretation of multiple node definitions having the same identifier in Advanced Concepts.

[lanthaler]

Isn't that already expressed in the definition of a "node definition":

node definition: A JSON object used to represent a node and one or more properties of that node. A JSON object is a node definition if it does not contain the keys @value, @list or @set and it has one or more keys other than @id. _A node definition may be spread among different parts of a document or even between different documents._

[cygri]

That sentence makes no sense. If a node definition is a JSON object, then how can it be spread throughout the document or even across documents? A JSON object is a JSON object. You can't spread a JSON object out to different parts of a JSON document.

I think this should say that multiple node definitions can contribute properties to the same node.

I wouldn't try getting into the business of explaining cross-document things. That opens a giant can of worms that you're probably not prepared to tackle. Saying what happens within a single document seems sufficient.

[tidoust]

I hadn't seen this issue but note that, as part of my grammar re-write exercise insert a Conformance section (issue #166), I updated the definition of node definition for the same reason @cygri mentions:

A node definition represents one or more properties of a node in the JSON-LD graph produced by JSON-LD processors during expansion. The properties of a node in the JSON-LD graph may be spread among different node definitions within a document or even between different documents.

http://tidoust.github.com/json-ld.org/spec/latest/json-ld-syntax/index.html#grammar-node-definition

I would also stay silent on cross-document definitions actually.

[lanthaler]

It just came to my mind that probably should remove the term “node reference” from the spec as such a thing doesn’t really exist. That object is the node. In that line of thinking also the term node definition doesn’t make much sense as it implies that there’s only one definition which probably triggered this issue in the first place.

I just checked the two specs and we don’t really need the distinction. So I would like to propose the following:

PROPOSAL: Remove the terms “node definition” and “node reference” and just talk about “nodes” instead.

Multiple JSON objects then might represent the same node and add properties to it.

Does this make sense?

[gkellogg]

We really need to distinguish between node definitions and node references. Node reference is used within the API for example in Value Compaction and Framing. I'm not sure we can eliminate the distinction.

[lanthaler]

I thought that as well but that’s not the case. In API spec e.g., there is a merely 7 mentions of those terms and most of the time both are used together. The only place where the difference actually matters is in value compaction but it would be simple enough to inline the definition there.

[gkellogg]

If you can do this without loosing the places where it seems to currently be important to distinguish them, then I'm +1.

[tidoust]

I disagree with removing "node definition" and "node reference". "Node definition" and "node reference" are grammar constructs, whereas "node" is a data model term. Statements in the grammar describe syntax, and should only use grammar construct terms.

As part of my updates to the grammar, I took great care to only reference data model constructs in the definitions of the grammar construct terms, to explain how these constructs map to the underlying JSON-LD data model, but not to use any of the JSON-LD data model terms in the normative statements associated with the grammar constructs themselves.

In the following example,

[
 {
   "@id": "http://example.org/1",
   "http://example.org/title": "Hello world"
 },
 {
   "@id": "http://example.org/1",
   "http://example.org/description": "Welcoming message to the world"
 }
]

... you need a term to describe the two JSON objects, event though they map to one node in the JSON-LD data model. That's what node definition is for. You may come up with another term if you don't like "node definition" but we need something to describe that grammar construct.

I care less about the distinction between node definition and node reference. The latter is a subset of the former, only there because the doc explains how to refer to a node (a node, not a node definition) from other parts of the document.

[cygri]

PROPOSAL 1: Remove the term node reference as it is not needed; one term (currently node definition) is sufficient.

PROPOSAL 2: Rename node definition to node object because 1. it doesn't actually “define” a node, and 2. to make more explicit that it is a kind of JSON object

[tidoust]

PROPOSALS 1 and 2 look good to me.

[lanthaler]

PROPOSAL 1: +1
PROPOSAL 2: +1

Great idea Richard, that makes it very clear and unambiguous.

[gkellogg]

+1 to both

[niklasl]

+1 to both.

[lanthaler]

RESOLVED: Remove the term node reference as it is not needed; one term (currently node definition) is sufficient.
RESOLVED: Rename node definition to node object because 1. it doesn't actually “define” a node, and 2. to make more explicit that it is a kind of JSON object

[lanthaler]

@cygri, did you have any specific definition of node object in mind? I thought of something like this:

node object: A JSON object used to represent a node and one or more properties of that node. A JSON object is a node object if it does not contain the keys @value, @list, or @set. Multiple node objects can contribute properties to the same node.

The only exception that still has to be added to the definition above is that a top-level object containing nothing else than a @graph property and an optional @context property is not a node object:

{
  "@context": { ... },
  "@graph": [
     ...
  ]
}

[gkellogg]

Probably needs to be zero or more properties of that node if it is to replace node reference.

[lanthaler]

Good spot Gregg!

[cygri]

+1 to @lanthaler's proposal with @gkellogg's amendment.

Another exception though seems to be that a JSON object is not a node object if it is the value of a @context key.

Can multiple node objects contribute @type values to a node? I guess they can?

[cygri]

The best way of defining the kind of JSON object that is a node object is probably by exclusion: “A JSON object is a node object if it is neither a context object nor a value object nor a top-level graph object nor…”

This may require explicitly defining some more object types, which is probably a good thing for clarity.

[lanthaler]

OK thanks, I’ll see what I‘ll come up with.

Yes, multiple node objects can contribute type values to a node.

[msporny]

@cygri I implemented both resolutions, but decided to not follow your advice in comment #169 (comment)

I tried declaring new object types and it was more verbose than just doing it the way we had it before. Let me know what you think about the new text and I can tweak it if needed.