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

On Jun 17, 2011, at 8:09 AM, Manu Sporny wrote:

On 06/03/11 14:24, Brian Peterson wrote:
...
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"
}

In the latest draft of the spec, I started to prefer the use of terms to CURIEs, such as Manu show's here. I think this is a great way to go, and corresponds with much existing practice in naming keys. Another way to think of a CURIE is an expansion on a basic term; I do really think that both have a place in JSON-LD, but they can be resolved through basic rules:

resource: IRI | term [':' suffix]?
term: NCNAME
suffix: relative-iri

A good place to start for existing vocabularies could be to adapt existing MicroFormat patterns, such as hCard and XFN/FOAF, into pre-defined JSON-LD  profiles, and use them for early examples.

(As an aside, RDFa could benefit from this too, and I've suggested elsewhere that we might look to have a common profile format that could be used across many different serialization formats).

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

+1, specs are for people writing processors mostly. A typical developer shouldn't have to get past the introduction and examples of use.

More advanced usage (such as explicit literals, and RDF List processing) needs to be specified, but really isn't of concern to 90% of the users, but without it JSON-LD cannot be used to fully express existing RDF use cases.

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<http://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?

IMHO MicroFormats more closely fit the expectation of JSON developers, and sticking to defined terms from one or more profiles is the way to do this. Hopefully, upcoming work between the MicroFormat, Microdata and RDFa groups will help resolve the conceptual differences and yield something that is better than any individually. JSON-LD could play into this and become a relevant part of the discussion.

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?

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.

The new version should be much easier to understand, and could probably be made even simpler. That said, it's really mostly of use for people writing processors.

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.

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?

I like the use of "@type", but think that "@iri" is a bad idea: this doesn't convey the same information as "@subject".

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

Gregg