Re: Framing and @graph

Thanks for your quick response, as always, Markus!

On Wed, Jul 31, 2013 at 2:41 PM, Markus Lanthaler
<markus.lanthaler@gmx.net>wrote:

> > In Open Annotation, currently, we do not push for the use of @graph in
> > the serialization, and in fact don't even mention it [1].  However
> > framing seems to always insert the @graph keyword when it wasn't
> > present before [2].  This means that either every client needs to know
> > that it should look inside @graph or at the top level for the
> > annotation, or we could simply specify that @graph must be present for
> > consistency.
>
> Right, framing always returns an object with an @graph at the top-level to
> ensure that results always have a deterministic shape.
>

Yes, understood.  So if we want to specify the serialization of an
Annotation in JSON-LD, we therefore should include @graph in the expected
shape of the output JSON, right?

Thus our basic annotation becomes:

{
    "@context": "http://www.w3.org/ns/oa-context-20130208.json",
    "@graph": [{
      "@type": "oa:Annotation",
      "hasBody": "http://www.example.org/body1",
      "hasTarget": "http://www.example.org/target1"
    }]
}




> > The issue that I (at least) have with this is that the JSON-LD docs
> > bury @graph in a "Named Graph" section rather than being up front and
> > saying that you need to worry about it all the time, even if you don't
> > have a named graph.
>
> I don't see this as a problem. You are reading a JSON-LD document so you
> have to expect every keyword unless you have some out-of-band contract with
> the publisher which allows you to rely on a specific structure.
>

My concern here is the different (and thus likely not interoperable)
implementations that developers with different back-end stacks will come to.
A JSON based developer will end up with an object without @graph, because
in the documentation it's described more as an edge case for named graphs.
As he doesn't have a named graph, he should feel pretty confident in
leaving it out from the serialization, and not processing it in a client.

Then a developer with an RDF stack, on the other hand, will always get a
blank node named @graph out from her tools. She also doesn't think she has
a named graph, but will code her clients to expect it.  Now these two
implementations won't work together, and I think it's hard given the
current documentation, to explain why the JSON developer needs to always
look for @graph.

> Or am I missing an option that allows @graph to be omitted?
>
> You could compact the framed result. That would eliminate the @graph if
> there's a single item in that array.


Ahha, indeed that's what I was missing

  compact( frame( flat, frame), context)

produces the desired output :)


> > Equally,
> > not naming blank nodes would also be another nice output option,
> > rather than generating explicit bnode names?  Or ... am I missing the
> > point of framing entirely? :)
>
> That's a side effect of how the algorithm works. Internally the whole
> document is flattened and indexed by @id and thus every node needs to have
> an identifier.
> Please keep in mind that framing (unfortunately) isn't part of JSON-LD 1.0.
> So things may change a lot in the future.
>

Yes, however even a de facto standard that gets widely implemented and used
is extremely beneficial to the community in terms of ease of adoption :)

Thanks again!

Rob