Philosophy, was framing

Hi Markus,

Sorry about the HTML... must have been from cut/pasting out of the spec.
As the framing issue is solved, thanks!, I changed the subject.

I have to disagree philosophically with you here.  I think that the
JSON-ness (is "jsonic" a word?) of JSON-LD is a huge strength. Perhaps the
fundamental strength of JSON-LD over any other RDF serialization. As Manu
implies in his blog post on nuclear rdf, the fact that RDF/XML is unable to
be usefully processed by XML tools or understood by people familiar with
XML is a massive failing that has negatively impacted the adoption of RDF
in general for many years.

And to quote the post:
  "RDF is plumbing... and developers don't need to know about it to use
JSON-LD"

If you want to understand why your tools are adding this stupid "@graph"
and "@id": "_:b1" crud all over your nice JSON, the answer is... RDF.  But
not even just RDF, it's a choice in the algorithms to include them as
there's nothing in the spec that says they have to be there when not
necessary.  That a JSON developer can look at an RDF serialization and
instantly understand what is going on, without knowing the underlying
model, is /the/ saving grace for the semantic web, IMO.  It is all about
being easy /and/ semantic.

So I would implore you to please reconsider the "anti-pattern" stance.

Rob

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

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