RE: Framing and @graph

On Wednesday, July 31, 2013 11:02 PM, Robert Sanderson wrote:
> Thanks for your quick response, as always, Markus!

Robert, could you please try to send plain-text mails instead of HTML
formatted ones. This would make it much easier to reply and to understand
who wrote what. Thanks.


> On Wed, Jul 31, 2013 at 2:41 PM, Markus Lanthaler wrote:
>> 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"
>    }]
> }

No, I don't think you should do that. Why would you? A consumer can't and
shouldn't rely on a specific shape anyway. In your spec you state above the
examples that "[the use of the recommended context] results in
serializations *similar* to the two examples below". That "similar" is
enough IMO to make it clear that other shapes have to be expected by
consumers. If you want to make it crystal clear, you could add a sentence
explaining that consumers must be prepared to receive the data serialized
differently (using different property names for example).

 
>>> 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.

That has nothing to do with the publisher (backend) but solely with the
consumer. If you need to support JSON-only consumers, i.e., clients that
rely on the structure and the property names to process the document, you
need to specify it. A goal of JSON-LD is to eliminate that coupling which
all too often results in very brittle systems. So the question you should
ask yourself is: "Do we need to support clients that process OpenAnnotation
documents as JSON"?

If the answer is no, you don't have to do anything. JSON-LD capable clients
will transform the document to a form suitable for them. They might frame
it. Or they might flatten it. You don't know - and don't have to.

On the other hand, if you need to support JSON-only clients as well, you
need to specify in all details how documents are structured. Then you would
define a profile and use JSON-LD's profile media type parameter to signal
that the documents conforms to that structure. Similarly, a client can
request a document in that form in conneg.

I see that as an anti-pattern and just useful for legacy systems. So I would
recommend you to not go down that route. That would be similar to
prescribing how the Turtle serialization should look like.


>>> 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 :) 

Right :-)

 
>> 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 :) 

Agreed, but the current implementations aren't 100% interoperable at the
moment and the algorithm in the spec draft is completely outdated. I just
wanted to ensure that you are aware of that and that you don't base your
spec on it. But you are right, framing is one of the most powerful concepts
of JSON-LD.


--
Markus Lanthaler
@markuslanthaler

Received on Thursday, 1 August 2013 08:08:52 UTC