[openbiblio-dev] [JSON] usage example, JSON and RDF I/O in openbiblio

[William Waites]

This came up in a side discussion in the RDF-WG call
today and explicit documentation on how this works in
our application is lacking, so I'll try to remedy that
here and hopefully it will also serve as some 
discussion fodder.

Firstly, SPARQL is used by the back-end the same way
SQL might be in another world. It is not at present
used by the front-end though it probably will be at
some point in the future.

We have many graphs. Here's an example,

  http://bnb.bibliographica.org/entry/GB5105626

This graph has several representations,

  http://bnb.bibliographica.org/entry/GB5105626.html
  http://bnb.bibliographica.org/entry/GB5105626.json
  http://bnb.bibliographica.org/entry/GB5105626.rdf
  http://bnb.bibliographica.org/entry/GB5105626.n3

  (also equivalently retrievable with Accept header
   negotiation)

A GET operation retrieves data, a PUT replaces and
a POST appends. Any of these representations can be
written excepting HTML which is purely for human
consumption.

>From a web user interface development point of view
the most important of these is the JSON. The user 
interactions (at present just manipulating collections
of books) are written in JavaScript and the program
running in the browser speaks a JSON protocol with
the server.

The JSON representation for a particular subject is
built like so, starting with an empty dictionary:

  1. put "id": "<subject_uri>" (URI is expressed in
     angle brackets as in ntriples/turtle/n3
  2. for each predicate, do we have an explictly
     modelled property on the server side object?
     if so make a key with that name
  3. if we do not have an explicitly modelled 
     property and we do have a useable namespace
     make a curie, e.g. dc:isPartOf
  4. if we do not have a useable namespace, use the
     predicate URI in angle brackets as key.
  5. for the objects, do we have more than one? use
     a list, else use a single value
  6. if the object is a (modelled) URI, the value
     is a dictionary, go recursively to step 1 for that
     object
  7. if the object is an unmodelled URI, represent
     according to steps 3,4
  8. if the object is a literal, encode it directly,
     paying attention to datatypes that are representable
     directly in JSON (e.g. integers, floats, strings)
     and ignoring language tags.

This algorithm is applied in reverse for a PUT or POST
operation, the "id" key for the subject being required
in the case of a PUT or being generated by the server
in the case of a POST.

A "better" (for some values of better) protocol would
to be to use RDF with GET/PUT/POST directly which is
supported by the server software but has proven very
difficult for otherwise skilled and competent user 
interface developers to wrap their heads around.

Nathan asked if we need the three possibilities of
directly modelled simple property names, curies and
explicit URIs or if we could dispense with curies.
The ideal case from the Javascript programmer's point
of view is that they are all simple property names 
and they never have to think about properties with
namespaces. Failing that, curies are more friendly
than full URIs but do require at least some convention
on well-known namespace prefixes at least within the
context of a single application. Full URIs as properties
are actually disorienting, they are not expressible
in the usual OO kind of notation that JS programmers
are used to, they are acceptable as values but not
really as keys.

Cheers,
-w
-- 
William Waites                <mailto:ww at styx.org>
http://river.styx.org/ww/        <sip:ww at styx.org>
F4B3 39BF E775 CF42 0BAB  3DF0 BE40 A6DF B06F FD45