Updates and tests for @included as an array of node objects.

[gkellogg]

For w3c/json-ld-syntax#19.

@dlongley If you could see if this formulation works better for you. At this point @included is an array of node objects, sort of like @graph. Fairly small impact on both Expansion and Flattening algorithms.

We could extend to allow id-maps, type-maps and so forth, but that doesn't provide any really new functionality.

---

Preview | Diff

[dlongley]

So my understanding of this feature is that it allows you to specify node objects wherever you'd like without needing a predicate for them. It doesn't mean that they are necessarily in the default graph; if @included appeared within a named graph branch of the JSON tree, then those node objects would also be in that named graph. Is that correct?

Essentially, this is a way to use @graph (when we use it to express an array of nodes where that graph has no single root... aka a "bush") anywhere in the document and have it apply to whatever @graph is currently being expressed.

If I understand this properly, then I think it's much simpler and easier to understand than what we were looking at before (despite there perhaps only being minor differences). I also think it's a good feature that others have been asking for in the past and it will be helpful with "found JSON". In a future version, perhaps we can also add some framing mechanism to produce it algorithmically.

I'm not sure about the name ... maybe @include follows our naming convention better, but perhaps there's an even better term, but that's just bikeshedding.

[dlongley]

Suggested change

	An <a>included block</a> is an <a>entry</a> in a <a>node object</a> where the key is `@included` or an alias
	An <a>included block</a> is an <a>entry</a> in a <a>node object</a> where the key is either `@included` or an alias of `@included`

[gkellogg]

So my understanding of this feature is that it allows you to specify node objects wherever you'd like without needing a predicate for them.

Well, in any node object, not anyplace at all.

It doesn't mean that they are necessarily in the default graph; if @included appeared within a named graph branch of the JSON tree, then those node objects would also be in that named graph. Is that correct?

Yes.

Essentially, this is a way to use @graph (when we use it to express an array of nodes where that graph has no single root... aka a "bush") anywhere in the document and have it apply to whatever @graph is currently being expressed.

If I understand this properly, then I think it's much simpler and easier to understand than what we were looking at before (despite there perhaps only being minor differences). I also think it's a good feature that others have been asking for in the past and it will be helpful with "found JSON". In a future version, perhaps we can also add some framing mechanism to produce it algorithmically.

I haven’t experimented with framing, but it shouldn’t require too much to make it work.

I'm not sure about the name ... maybe @include follows our naming convention better, but perhaps there's an even better term, but that's just bikeshedding.

I raised that concern last time, but it reuses the name from json.api, not that I think we need be bound by that. @include May be better, and of course could always be aliased as included.

Note an area I didn’t go to is if a node with @included appears in a list, what does that mean? It would either be multiple list entries at that position, or possibly an embedded list.

[dlongley]

Well, in any node object, not anyplace at all.

Right.

Note an area I didn’t go to is if a node with @included appears in a list, what does that mean? It would either be multiple list entries at that position, or possibly an embedded list.

Right ... I'm not sure. My inclination would be that it's just more information in the graph that someone happened to drop into the list; it could have been anywhere. My understanding of @included is that where it appears only applies to which graph the information is in, nothing more. Using @included in a list is not special and it does not mean that it is either multiple list entries or an embedded list.

But I admit I haven't thought deeply about it. I don't know how "json.api" uses it in a similar circumstance and if its semantics change then.

[gkellogg]

In the Flattening algorithm, if a node object with @included is the value of a property (or reversed property) the nodes in @included are also values of that property, but thinking again, this probably shouldn’t be.