RE: Comments on the complexity of the JSON-LD spec

Inlined...

> -----Original Message-----
> From: public-linked-json-request@w3.org [mailto:public-linked-json-
> request@w3.org] On Behalf Of Manu Sporny
> Sent: Friday, June 17, 2011 11:09 AM
> To: public-linked-json@w3.org
> Subject: Re: Comments on the complexity of the JSON-LD spec
> 
> On 06/03/11 14:24, Brian Peterson wrote:
> > I believe that the popularity of JSON is based primarily on its
> > simplicity.
> 
> I'm going to skip over most of this e-mail because Dave Longley seems
> to
> have addressed most of the issues you raised. There were a couple of
> items in here that popped out at me as fairly strong statements.
> 
> > IMHO, JS developers and other consumers of JSON are going to expect
> > simplicity. A JSON-LD specification that is 10x longer than the
> > original JSON specification is going to be a non-starter for the
> > majority of JSON developers - a big majority. Honestly, I think the
> > first JSON-LD spec should fit in an email (a short email, unlike the
> > ones I tend to write).
> 
> Yes, we want something simple, here you go:
> 
> JSON-LD (JavaScript Object Notation for Linked Data) is a lightweight
> Linked Data format. It is easy for humans to read and write. It is easy
> for machines to parse and generate. It is based on the already
> successful JSON format and provides a way to help JSON data
> interoperate
> at Web-scale.
> 
> If you are already familiar with JSON, writing JSON-LD is very easy.
> There is a smooth migration path from the JSON you use today, to the
> JSON-LD you will use in the future. These properties make JSON-LD an
> ideal Linked Data interchange language for JavaScript environments, Web
> services, and unstructured databases such as CouchDB and MongoDB.
> 
> To use JSON-LD, just pick a Web vocabulary that you want to use and
> start marking up your data. For example:
> 
> {
>    "@context": "http://purl.org/jsonld/people",
>    "name": "Brian Peterson",
>    "knows": "http://manu.sporny.org/webid"
> }
> 
> That's it. 

That's a fairly good introduction, but a simple introduction doesn't make
for a simple specification. JSON itself doesn't need an introduction because
it is quite straight forward.

> The point I am trying to make is that people rarely read
> specifications before they use technologies. That is - do you think
> that web developers have read the entire HTTP specification? 

I'd say 75% of the developers I work with have looked at parts of the HTTP
specification. I know a number that have had to look into the URI
specification to help figure out encoding problems they've run into.

> What about UTF-8? XML? TLS? JavaScript? CSS? HTML5? 

When XML first came out I did work with a developer that read the spec. I
probably would have myself if I had any interest at the time. Since then XML
has gotten really complicated. I expect the spec would be rather hard to get
through. Come to think of it, I guess many of us in the office have looked
at the XML Schema Datatypes section, if only to check on the format for
xsd:dateTime.

I don't think your other examples are good comparisons. They are not
oriented towards the same problem space as JSON. They are for technologies
that are so complicated that no one but tool implementers would read the
specification. Is that really what you want for JSON-LD?

Perhaps better comparisons would be CSV, text/plain, key/value property
files. Have developers read those specifications? Well, I'd say "No", but
only because they are so simple that they don't need specifications. In
these cases, developers really can use them without checking the spec. JSON
is the same. 

I think it would be real cool if JSON-LD could have the same adoption as
JSON, CSV, and key/value property file format. RDF doesn't need to be too
complicated for the average developer. RDF-based LD doesn't need to be a
barrier to adopting RDF or LD.

But if JSON-LD is as complicated as CSS, then I don't think it will help
with my goal. There is a strong incentive for developers to use and learn
CSS. There isn't going to be the same incentive for JSON-LD.

> Tens of thousands of Web
> developers use these technologies every day and I would be willing to
> bet that less than 1% have actually read the entire specification for
> any of those technologies.

Again, I think this is a wrong comparison. Consider the technologies used by
Web developers that are simple enough that their specification is hardly
recognized as such (e.g. JSON, CSV, property file format). That is the goal
that I'm promoting -- make JSON-LD a very light extension to JSON. It could
be made so that developers can use JSON-LD as plain JSON and not know
anything about RDF, but the RDF is still there. 

> Now, that is not to say that editors of the specification should not
> strive to make the content easy to read and understand as possible.
> However, it must not be done at the expense of being precise and
> thorough. It is better to over specify than under specify when it comes
> to Web standards. When you under specify, you end up implementations
> that do not interoperate.
> 
> > Extensions to the specification, or other JSON-based formats, can be
> > introduced for the more general use cases, ones requiring more RDF
> > features.
> 
> Define "extensions". How are they created, what are their conformance
> levels?
> 
> > I read through the JSON-LD specification ([1]) as I think a UI
> > developer would, or some other consumer of JSON. I don't mean to be
> > harsh, and I don't mean to be a smart*ss; I'm just responding from
> > the perspective of the feedback I've gotten from the developers I
> > work with.
> 
> A typical UI developer would absolutely not read through the JSON-LD
> specification. Take CSS, for example. A typical UI developer would go
> to
> a site that teaches them how to use CSS3, like this one:
> 
> http://www.css3.info/
> 
> Take a look at the 34 CSS specifications in active development:
> 
> http://www.w3.org/Style/CSS/current-work
> 
> Are you saying that you think that UI developers read those
> specifications? Here is the table of contents to the CSS2
> specification:
> 
> http://www.w3.org/TR/CSS2/
> 
> I would be surprised if a developer read through the JSON-LD
> specification. The people that read specifications are often spec
> implementers. Again, I think the spec should be understandable by most
> developers that read it. I don't understand why you think that a UI
> developer or regular Web developer would read the JSON-LD
> specification.

My hope is that JSON-LD is made to be in the class of CSS. If JSON-LD needs
books and courses to explain how to use it, then I think adoption is going
to be really slow.

The point I meant to make (but did a poor job of it) wasn't that the
specification as a document is too complicated; rather, that JSON-LD itself
is too complicated. The specification is complicated because JSON-LD is
complicated, and it is that complexity that will hold back adoption.

> > I got through sections 1 and 2 only because I'm familiar with W3C
> > specification documents, but you started to lose me around section
> > 2.4.
> 
> What do you think of Gregg's updates to the spec?
> 
> > I scanned over section 3 and landed on 3.3, Microdata, only
> > because I just heard about schema.org. My thoughts reading that
> > section is that the authors of JSON-LD didn't take into consideration
> > that URIs might work in Microdata because it is HTML based, but they
> > don't fit as keywords in JSON. Developers never use URIs as keywords
> > in JSON.
> 
> One of the design goals of Microdata is the ability to use URIs
> everywhere. That section demonstrates that it can work. If you wanted
> to, you could also use a profile and shorten the URIs. Even though JSON
> developers rarely use URIs as JSON keys, it does happen from time to
> time and we demonstrate that you can do that in JSON-LD.
> 
> That is, you don't need a context at all. If you want to use full URIs
> everywhere - you can do it in JSON-LD. It was a design requirement for
> RDFa 1.1, it was a design requirement for Microdata - we just make sure
> that you can support both of those design requirements in JSON-LD.
> 
> Perhaps I don't understand what you're getting at. Does the above make
> sense to you?

Sure it makes sense to me, but then I love RDFa. It isn't going to make
sense to any of the developers I work with, though. It is just going to
confuse things for them. I can't get people interested in RDF or RDFa
because they get lost in all to options and complications. Having a clear
demarcation in JSON-LD where developers can recognize a place to stop and
ignore the complications would be useful. It would have been useful for RDF
and for RDFa.

> > Then you lost me at section 4. A processing algorithm for a
> > JSON-based format that requires 12 term definition, 11 specialized
> > keywords, and 20 steps is just a non-starter. I'd use it if my team
> > lead made me, but I would never chose to include it in a service I'm
> > developing.
> 
> Then where is your cut-off? How many terms, specialized keywords and
> steps change it from a non-starter to something you'd be willing to
> use?

5, 3, and 3 (maybe 4) 
:-)

It isn't the complication of the processing algorithm, it is the
complication in the context of JSON.  

> I also point back to the HTML5 specification, JavaScript, CSS, TLS,
> OAuth, and a variety of other specifications that are far more
> complicated than JSON-LD, but continue to be widely used and
> implemented on the Web.

I'll point back to JSON, CSV, and property-file format -- widely used for
simple cases because they are simple. JSON-LD (or some version) might need
to be complicated in order to handle complicated use cases, but it can be
simple to handle simple cases. 

What is the point of trying to encode LD into JSON? The fact that JSON fits
well into JS? I guess that's ok if your target is just JS, but JSON is used
in a number of other languages as well. 

So a JSON-LD specification that is straight-forward and simple will make it
a lot easier for services to use RDF-based LD. They don't even need to want
to use RDF, just LD and JSON, but the RDF will still be there.

> > This might work as an advanced specification, one for hard-core
> > semantic web developers. It might work on a web with a dominating
> > presence of semantic junkies. But there is no way I could get my
> > developers to adopt this specification right off. It doesn't fit with
> > the simplicity of JSON, the simplicity currently expected by
> > consumers and producers of JSON.
> 
> Then what would? Please propose something.

Hmmm.. I thought I offered to in a previous post but I can't find it. I'll
write something up. It wouldn't be as refined as the JSON-LD document, maybe
just in an email.

> > BTW, I've never been a fan of the "a" shortcut. But that's a
> > nit-pick. I'd prefer something like "@type" to fit better with
> > "@iri".
> 
> So, you would prefer "@type" to set the type and "@iri" to set the
> subject?

Me personally, yeah.

One last point: If there was a MicroRDFa, a subset of XHTML+RDFa oriented
towards the same use cases as Microdata, what objection would schema.org
have made to using MicroRDFa instead of Microdata? Microdata itself is
(IMHO) a really crummy extension to HTML. RDFa is much better designed and
already has the expansion path mapped out for handling much harder use
cases.

Maybe the whole schema.org situation is more complicated than that, but I
hope that there would have been those involved that would have said
something along the lines of "MicroRDFa is no more complicated than
Microdata, and it already has an expansion path mapped out, so let's go with
MicroRDFa."

And maybe it doesn't really apply to this JSON-LD topic. Maybe I'm still
just really honked off at the whole schema.org business. It was such a cheap
shot and their reasoning was just silly for going with Microdata and trying
to shutout RDFa. (I really liked your post on that, Manu.)

BP

> 
> -- manu
> 
> --
> Manu Sporny (skype: msporny, twitter: manusporny)
> President/CEO - Digital Bazaar, Inc.
> blog: PaySwarm Developer Tools and Demo Released
> http://digitalbazaar.com/2011/05/05/payswarm-sandbox/

Received on Thursday, 23 June 2011 05:15:39 UTC