Describe included blocks.

[gkellogg]

For #19.

---

Preview | Diff

[azaroth42]

LGTM! :)

[azaroth42]

(Sorry, misclick)

[iherman]

Can we simplify the example to contain only what is really necessary to understand the feature? From the point of view of this feature aliasing @type, @id, or indeed @included, but also the usage of @base seems to be totally irrelevant. The same for the usage of type for the included objects.

This would help the user concentrating on what is really essential in this case...

(Otherwise it looks o.k. to me...)

[gkellogg]

The example came from Rob’s original use case, but I can simplify it easily enough.

[iherman]

Actually... the comment of @dlongley in https://github.com/w3c/json-ld-syntax/issues/128#issuecomment-516936845 made me realize that, at least for me, the most important aspect of this feature is not what is in the proposed text. Indeed, what @included can replace is the misleading top level @graph when what one wants to expess is a “bush”, ie, several top level objects with their (recursive) properties. This is used all over the place in Turtle data, and for which the only solution in JSON-LD 1.0 is to use a top-level @graph property whoise value is... not a graph in the dataset sense (certainly not the same way as when a TriG data is encoded in JSON-LD).

If my understanding is indeed correct, I would think that such an example should be “the” core example for this feature, and the cross references in @azaroth42’s example is just a welcome consequence...

Or, at least, this fact should be emphasized in the text imho.

[gkellogg]

@iherman Please suggest some text and an example to help flesh this out in the spec. I'll be happy to integrate it into the text.

[dlongley]

@iherman,

Indeed, what @included can replace is the misleading top level @graph when what one wants to expess is a “bush”, ie, several top level objects with their (recursive) properties.

Yes, this is also my understanding -- I left a comment to similar effect over on the API PR:

https://github.com/w3c/json-ld-api/pull/128#pullrequestreview-269051034

[iherman]

@gkellogg

@iherman Please suggest some text and an example to help flesh this out in the spec. I'll be happy to integrate it into the text.

Hopefully, the PR over this PR works: https://github.com/w3c/json-ld-syntax/pull/209

[iherman]

This issue was discussed in a meeting.

• RESOLVED: focus <code>@included</code> text and example on original inclusion use case; mention value of it as an <code>@graph</code> replacement for bushes–and reference primer for further reading
• RESOLVED: close issue #19 with merger of <code>@included</code> related PRs
  View the transcript

  4.1. Indexing with @included
  Ivan Herman: -> https://github.com/w3c/json-ld-syntax/pull/208 issue PR
  Ivan Herman: -> https://github.com/w3c/json-ld-syntax/issues/19 issue itself
  Benjamin Young: We made good progress on this last week.
  Gregg Kellogg: It is @included now.16:13:56 <bigbluehat> https://jsonapi.org/
  … @included comes from the JSON.API spec, and we are adopting this.
  … Right now it’s just a container for collecting node objects that don’t have a direct rel with the node in which they are contained.
  … There’s been some exchange on the issue highlighting a bush-like use for included.
  … In JSON-LD 1.0 the top-level graph is used to collect nodes is a corner case. Everywhere else where graphs are used are seen as named graph.
  … Included doesn’t carry that baggage.
  … So @included can be used in favor of @graph in these places.
  … In 1.0, you can’t have a graph name being a property of another node. With @included you can.
  … We can’t use @graph to define a default graph.
  … Except when it is the only property in a top-level object.
  Benjamin Young: How does the actual inclusion take place?
  Gregg Kellogg: The shape is similar to JSON.API. The value is seen as an array of node objects. If you have a node that is a value of a prop….
  … Needed in jsonapi for node references that are not included in the main document as references, but should be included aside.
  … Included blocks can be nested, and will be flattened out when done.
  … You won’t compact back to included blocks after flattening.
  … You can use included in a frame and have it match on diff subjects.
  … The name @included is out of sync with other keywords.
  … Dave suggested @include
  … Just like jsonapi
  Ivan Herman: It’s becoming bikeshedding
  … I would go further than what you did. Ex 1.1.1 and 1.1.2 (bushes) should be removed.
  … We should convince people to not use those forms anymore.
  Gregg Kellogg: https://pr-preview.s3.amazonaws.com/w3c/json-ld-syntax/pull/208.html#example-111-using-graph-to-explicitly-express-the-default-graph
  Gregg Kellogg: By removing these we won’t lose anything. We would have to remove everything after the note.
  Gregg Kellogg: https://pr-preview.s3.amazonaws.com/w3c/json-ld-syntax/pull/208.html#example-103-simple-data-with-several-top-level-nodes
  Gregg Kellogg: Also, we may want to reverse example 103 and 104. To clarify writing bushes.
  Ivan Herman: Referring to @graph is misleading, as it has not been explained yet there.
  Gregg Kellogg: We may want to change an example in the @graph section then.
  … We can also just leave that out and use it in the best practices document.
  Ivan Herman: Yes
  Benjamin Young: Flattened representation will still contain @graph, so readers will have to know what it does.
  … This plumbing shift is significant.
  … This is going to cause issues for the json people that are operating on the flattened form.
  Gregg Kellogg: If you flatten with a context, it would introduce a graph to contain it. This would change the shape dramatically.
  … Same with framing. In 1.1 we don’t use an @graph at the top level if not needed.
  … We could change the algo to use included instead.
  … But we may not want to do that.
  … So do we want to replace the main usage of @graph to @included?
  … Included allows embedded nodes to go to one place. Like in jsonapi, they don’t want to include referenced things inline, but only a reference to an included block.
  Benjamin Young: Useful for reducing payload size. And only including referenced things once.
  … These are just IRI references?
  Gregg Kellogg: There is no magic going on.
  Ivan Herman: In JSON-LD it used to be hard to do these indexed references.
  … The bush features can now be expressed in two different ways.
  … These things happen.
  … It’s a matter of taste which one you prefer.
  … I personally always hated graph for representing bushes.
  … I like this new included representation for bushes.
  … I don’t want to hide the fact that bushes can be described with included instead of the graph ‘hack’.
  Gregg Kellogg: We can say that included can also be used without other props in node object for describing node objects without semantic relationship.
  Ivan Herman: I’m fine with that.
  Benjamin Young: https://pr-preview.s3.amazonaws.com/w3c/json-ld-syntax/pull/208.html#included-blocks-to-be-flattened
  Benjamin Young: If @included were @graph, this would make a named graph?
  Gregg Kellogg: I think this would make one or two named graphs.
  Benjamin Young: With included it won’t make named graphs.
  Gregg Kellogg: Yes, just objects.
  Benjamin Young: I see the value, but not keen on the new keyword.
  … I think we need to explain these next to each other, with their nuances.
  … The initial reason for this feature was not meant to displace graph.
  … It was meant to bring in other referenced objects in the document.
  Gregg Kellogg: What jsonld always had was the ability to reference node
  … by defining @id or @vocab you can define that thing.
  … our mission is to use json in the wild where this is a pattern of usage
  Benjamin Young: You said exactly what I was typing.
  … it would be good to use an example from jsonapi
  Gregg Kellogg: jsonapi examples are quite long, with a lot of nesting
  … we have a test case from jsonapi
  … may be too long for here. But may be good for best practices document.
  … It would overly complicated the spec to include here.
  Benjamin Young: This solves the jsonapi case by aliasing included to @included.
  Gregg Kellogg: Yes, you can have multiple properties that have multiple aliases.
  … included can be a nested object
  Ivan Herman: Can we talk about things that go to the primer?
  Gregg Kellogg: What to do with example?
  Ivan Herman: Switch the order of problem of Rob. In the primer we will have to spend more words on the fact that there are different things that can be used to do the same thing.
  … We must have a primer.
  … The current doc is already huge.
  Benjamin Young: We need distinction in the main spec explaining diff between included and graph
  Ivan Herman: To be honest, at this level there is no real diff between the examples.
  … this is a side-effect with included.
  … we should not fiddle around with that
  Benjamin Young: The graph foundation exists in flattened output, and this won’t go away.
  … this needs clarification
  Gregg Kellogg: The use of included on its own is a by-product of the feature.
  … it does not need its own description in the spec
  … There are use cases where that can be useful
  … That better lies in a non-normative text.
  Benjamin Young: The bush usage would go to the primer
  … focus of the text would go back to inter-document referencing.
  Ivan Herman: We are falling back to other extreme that I don’t agree with
  … we are hiding a feature of included
  … In the inclusion part we should mention the alternative representation of bushes.
  … because current graph-based bushes are a hack
  … It has been around for a while, but we still should mention it.
  Benjamin Young: This is an accidental feature since recently.
  … it is essential to flattened output. I don’t see it as a hack.
  … For non-turtle/trig users.
  Ivan Herman: For semweb folks you don’t care it is a hack.
  … we get into taste issues
  … I don’t want to hide it.
  Proposed resolution: focus @included text and example on original inclusion use case; mention value of it as an @graph replacement for bushes–and reference primer for further reading (Benjamin Young)
  Ivan Herman: +0.5
  Gregg Kellogg: +1
  Benjamin Young: +1
  Tim Cole: +1
  Ruben Taelman: +1
  Ivan Herman: If we have a primer, a reference can be put into it in CR
  Resolution #2: focus @included text and example on original inclusion use case; mention value of it as an @graph replacement for bushes–and reference primer for further reading
  Ivan Herman: include or included?
  Benjamin Young: People may expect a URI to be included. But this is wrong.
  Ruben Taelman: what was the keyword in JSON API?
  Gregg Kellogg: included
  Ruben Taelman: in that case, it might be helpful to be consistent with that
  Tim Cole: +1 for @included
  Proposed resolution: close issue #19 with merger of @included related PRs (Benjamin Young)
  Tim Cole: +1
  Ivan Herman: +1
  Ruben Taelman: +1
  Benjamin Young: +1
  Gregg Kellogg: +1
  Resolution #3: close issue #19 with merger of @included related PRs
  4