Added the example for bushes

[iherman]

(I hope this PR for a PR works:-)

I have made a change on the section of @included to emphasize the simple bush feature, but also maintaining the original example. I am sure the text needs harmonization as for the style.

I was also not sure about the paragraph on the JSON API; I have never used that thing, so I cannot comment on it. I am actually not sure it is worth keeping it here; it is not necessarily relevant imho. (or should be put as a note if we really want to keep to it).

---

Preview | Diff

[iherman]

Thanks @dlongley !

[azaroth42]

Is this true? This seems like the use case for {"@context": {}, "@graph": [ ... ]} ?

[azaroth42]

e.g.: http://tinyurl.com/y54yasoh

[iherman]

Well, yes, the solution so far to the problem is to use @graph. But it turns out that @included can play exactly the same role, except that using that keyword (instead of @graph) is cleaner. The problem with using @graph for something like that is that it looks like we are talking about a dataset when, in fact, we are not!

B.t.w., and that is relevant, the example is almost exactly the same is a few chapter below (example 111 in the PR) where datasets/named graphs are described. But there is difference between named graphs (or data sets) and a single graph which can then be handled via @included.

B.t.w., and I forgot to do that: if we agree with this PR, then the text around 111 should be redone. Of course, 111 remains valid due to backward compatibility reasons but I would propose that the @included should be promoted instead.

[gkellogg]

Looks good, I fixed the examples and added a note to Example 111.

[BigBlueHat]

I don't think this was the intended use of @included...and I find using it for bushes confusing--it's yet another way to do them rather than a meaningful replacement for the others.

Bushes can be written (as I understand them):

[{"@context": "...local context...", "@id": "...subject..."}, {}]

or

{
  "@context": "...shared context...",
  "@graph": [{"@id": "...subject..."}, {}]
}

And datasets can be written as...

{
  "@context": "...shared context...",
  "@id": "...name of graph...",
  "@graph": [{"@id": "...subject..."}, {}]
}

I've never found that confusing...but maybe I'm missing something?

[BigBlueHat]

Put differently, if the following two examples are identical, we don't need the new one.

New @included-based "bush."

{
  "@context": {
    "Person": "http://xmlns.com/foaf/0.1/Person",
    "name": "http://xmlns.com/foaf/0.1/name",
    "knows": {"@id": "http://xmlns.com/foaf/0.1/knows", "@type": "@id"}
  },
  "@included": [{
    "@id": "http://manu.sporny.org/about#manu",
    "@type": "Person",
    "name": "Manu Sporny",
    "knows": "https://greggkellogg.net/foaf#me"
  }, {
    "@id": "https://greggkellogg.net/foaf#me",
    "@type": "Person",
    "name": "Gregg Kellogg",
    "knows": "http://manu.sporny.org/about#manu"
  }]
}

vs. existing @graph-based bush...

{
  "@context": {
    "Person": "http://xmlns.com/foaf/0.1/Person",
    "name": "http://xmlns.com/foaf/0.1/name",
    "knows": {"@id": "http://xmlns.com/foaf/0.1/knows", "@type": "@id"}
  },
  "@graph": [{
    "@id": "http://manu.sporny.org/about#manu",
    "@type": "Person",
    "name": "Manu Sporny",
    "knows": "https://greggkellogg.net/foaf#me"
  }, {
    "@id": "https://greggkellogg.net/foaf#me",
    "@type": "Person",
    "name": "Gregg Kellogg",
    "knows": "http://manu.sporny.org/about#manu"
  }]
}

@gkellogg do these generate the same graph/bush output?

[iherman]

I think they are the same indeed, and if we have @included then indeed we have two ways of expressing the same.

As for using @graph: I do find it confusing. These two things are not the same, semantically (in Turtle and TriG, respectively):

a:b c:d "something" .

_:sdf { a:b c:d "something". }

Using @graph for a bush, for me, would naturally map to the latter but, the way we use it, it maps in the former. That is confusing in my view.

[iherman]

I know the second example above is not really valid, though... A better one is to say

 a:b c:d "something".
<http://a.b.c.> {}

The point is: let us not mix up datasets and simple graphs...

[gkellogg]

One difference is that @graph takes on a different meaning when other properties are present, which @included doesn't. This means you can have an @included block where the members are graph objects, each denoting a different named graph.

[BigBlueHat]

a:b c:d "something" .

becomes

{
  "@graph": [{"@id": "a:b", "c:d": "something"}]
}

And the dataset one...

<http://a.b.c.> { a:b c:d "something". }

becomes...

{
  "@id": "http://a.b.c.",
  "@graph": [{"@id": "a:b", "c:d": "something"}]
}

I really don't see the confusion. A dataset is an @graph with an identifier.