Straw Proposal for Jangle Connector JSON refactor
Ross Singer
improved JSON response for a 'feed' request (i.e., your normal
connector response). It's quite different from the current response.
In the "root" of the response, there are some new elements ("type",
"formats", "alternate_formats", "stylesheets" and "availableResults").
"type" replaces the mime type response that was previously used. Here
I'm just using a string ("feed"), but I'd probably be more inclined to
use a URI (i.e. http://jangle.org/vocab/responses#feed or something)
"formats" is an array of Jangle format URIs to define what's being
sent in the feed. I'm not sure, yet, how this could be used.
"alternate_formats" is a hash of Jangle format URIs and the value
needed to request the alternate format
"stylesheets" is an array of urls to stylesheets to be applied to the atom feed.
"availableResults" is the number of resources requested that are
actually available. "totalResults" is the number of resources that
are either available or unavailable at a given URI.
In a given "resource", the new elements are: "format",
"alternate_formats", "relationships" and "available".
"format" is the singular of the above. The Jangle format URI for the resource.
"alternate_formats" is exactly like above.
"relationships" is a hash of the Jangle entity URI and the actual uri:
so the Items associated with a resource would be:
"http://jangle.org/vocab/entities#Item":"/resources/1234/items/", for
example. I think it should be legal for the value of this to be an
array, if the implementor wants to explicitly list all of the
relationships (this has the potential of getting really ugly,
however).
"available" is a boolean to indicate whether or not the specified
resource *still* exists at this location (I think 404s should be used
for requests to things that never have actually existed).
"links" is an optional key to populate the atom:links elements (the
Jangle core will populate the links with the 'alternate_formats' and
'relationships' values -- this is for links *outside* of Jangle, such
as a link from a Resource to the OPAC page for that resource).
Previously all the atom:links were transported here, which (in my
mind) tied the Jangle connector a little too closely to Atom.
The last resource in this request indicates a record that was deleted.
In this case, Jangle core would issue a Tombstone for that URI.
As always, comments/criticisms welcome.
{
"type":"feed",
"formats":["http://www.loc.gov/MARC21/slim"],
"alternate_formats":{"http:\/\/jangle.org\/vocab/formats#http:\/\/www.loc.gov\/mods\/v3":"mods",
"http:\/\/jangle.org\/vocab#formats#http:\/\/www.openarchives.org\/OAI\/2.0\/oai_dc\/":"oai_dc",
"http:\/\/jangle.org\/vocab/formats#http:\/\/purl.org\/dc\/elements\/1.1\/":"dc"},
"stylesheets":["foo","bar"],
"request":"\/resources\/5878,5830,920",
"offset":0,
"totalResults":3,
"availableResults":2,
"extensions":
{
},
"time":"2008-09-02T14:19:37-05:00",
"data":
[
{
"content":"<record
xmlns='http:\/\/www.loc.gov\/MARC21\/slim'><leader> Z 22
4500<\/leader><datafield tag='245' ind1='0' ind2='0'><subfield
code='a'>From Sand Hill to Pine<\/subfield><subfield
code='b'><\/subfield><subfield code='c'>by Bret
Harte<\/subfield><\/datafield><datafield tag='100' ind1='0'
ind2='z'><subfield code='a'>Harte,
Bret,
<\/subfield><\/datafield><datafield tag='42' ind1='z'
ind2='z'><subfield code='a'>dc<\/subfield><\/datafield><datafield
tag='50' ind1='z' ind2='z'><subfield
code='a'>PS<\/subfield><\/datafield><datafield tag='100' ind1='z'
ind2='z'><subfield
code='d'>1836-1902<\/subfield><\/datafield><datafield tag='245'
ind1='z' ind2='z'><subfield code='h'>
[
electronic resource
]
\/<\/subfield><\/datafield><datafield tag='260' ind1='z'
ind2='z'><subfield code='b'>Project Gutenberg,
<\/subfield><subfield
code='c'>2001<\/subfield><\/datafield><datafield tag='500' ind1='z'
ind2='z'><subfield code='a'>Project
Gutenberg<\/subfield><\/datafield><datafield tag='506' ind1='z'
ind2='z'><subfield code='a'>Freely
available.<\/subfield><\/datafield><datafield tag='516' ind1='z'
ind2='z'><subfield code='a'>Electronic
text<\/subfield><\/datafield><datafield tag='830' ind1='z'
ind2='z'><subfield code='a'>Project Gutenberg<\/subfield><subfield
code='v'>2544<\/subfield><\/datafield><datafield tag='856' ind1='z'
ind2='z'><subfield
code='u'>http:\/\/www.gutenberg.org\/etext\/2544<\/subfield><subfield
code='3'>Rights<\/subfield><\/datafield><datafield tag='856' ind1='z'
ind2='z'><subfield
code='u'>http:\/\/www.gutenberg.org\/license<\/subfield><\/datafield><\/record>",
"updated":"2008-03-18T15:56:59-05:00",
"title":"From Sand Hill to Pine",
"available":true,
"content_type":"application\/xml",
"created":"2008-03-18T15:56:59-05:00",
"format":"http://www.loc.gov/MARC21/slim",
"alternate_formats":{"http:\/\/jangle.org\/vocab/formats#http:\/\/www.loc.gov\/mods\/v3":"mods",
"http:\/\/jangle.org\/vocab#formats#http:\/\/www.openarchives.org\/OAI\/2.0\/oai_dc\/":"oai_dc",
"http:\/\/jangle.org\/vocab/formats#http:\/\/purl.org\/dc\/elements\/1.1\/":"dc"},
"relationships":{"http:\/\/jangle.org\/vocab/entities#Item":"\/resources\/5830\/items",
"http:\/\/jangle.org\/rel\/related#Collection":"\/resources\/5830\/collections\/"},
"id":"\/resources\/5830",
"links":
{
"alternate":
[
{
"type":"text\/html",
"href":"http:\/\/catalog.jangle.org\/shared\/biblio_view.php?bibid=5830&tab=opac",
"title":"Link to OPAC"
}
],
}
},
{
"content":"<record
xmlns='http:\/\/www.loc.gov\/MARC21\/slim'><leader> Z 22
4500<\/leader><datafield tag='245' ind1='0' ind2='0'><subfield
code='a'>The Untamed<\/subfield><subfield
code='b'><\/subfield><subfield code='c'>by Max
Brand<\/subfield><\/datafield><datafield tag='100' ind1='0'
ind2='z'><subfield code='a'>Brand,
Max,
<\/subfield><\/datafield><datafield tag='42' ind1='z'
ind2='z'><subfield code='a'>dc<\/subfield><\/datafield><datafield
tag='100' ind1='z' ind2='z'><subfield
code='d'>1892-1944<\/subfield><\/datafield><datafield tag='245'
ind1='z' ind2='z'><subfield code='h'>
[
electronic resource
]
\/<\/subfield><\/datafield><datafield tag='260' ind1='z'
ind2='z'><subfield code='b'>Project Gutenberg,
<\/subfield><subfield
code='c'>2004<\/subfield><\/datafield><datafield tag='500' ind1='z'
ind2='z'><subfield code='a'>Project
Gutenberg<\/subfield><\/datafield><datafield tag='506' ind1='z'
ind2='z'><subfield code='a'>Freely
available.<\/subfield><\/datafield><datafield tag='516' ind1='z'
ind2='z'><subfield code='a'>Electronic
text<\/subfield><\/datafield><datafield tag='830' ind1='z'
ind2='z'><subfield code='a'>Project Gutenberg<\/subfield><subfield
code='v'>10886<\/subfield><\/datafield><datafield tag='856' ind1='z'
ind2='z'><subfield
code='u'>http:\/\/www.gutenberg.org\/etext\/10886<\/subfield><subfield
code='3'>Rights<\/subfield><\/datafield><datafield tag='856' ind1='z'
ind2='z'><subfield
code='u'>http:\/\/www.gutenberg.org\/license<\/subfield><\/datafield><\/record>",
"updated":"2008-03-18T15:57:00-05:00",
"title":"The Untamed",
"available":true,
"content_type":"application\/xml",
"created":"2008-03-18T15:57:00-05:00",
"id":"\/resources\/5878",
"format":"http://www.loc.gov/MARC21/slim",
"alternate_formats":{"http:\/\/jangle.org\/vocab/formats#http:\/\/www.loc.gov\/mods\/v3":"mods",
"http:\/\/jangle.org\/vocab#formats#http:\/\/www.openarchives.org\/OAI\/2.0\/oai_dc\/":"oai_dc",
"http:\/\/jangle.org\/vocab/formats#http:\/\/purl.org\/dc\/elements\/1.1\/":"dc"},
"relationships":{"http:\/\/jangle.org\/vocab/entities#Item":"\/resources\/5878\/items",
"http:\/\/jangle.org\/rel\/related#Collection":"\/resources\/5878\/collections\/"},
"links":
{
"alternate":
[
{
"type":"text\/html",
"href":"http:\/\/catalog.jangle.org\/shared\/biblio_view.php?bibid=5878&tab=opac",
"title":"Link to OPAC"
}
],
}
},
{
"id":"/resources/920",
"available":false,
"updated":"2008-08-29T13:21:00-05:00"
}
]
}
-Ross.
Ross Singer
intertubes can barely contain your chatter.
One more field that I inadvertently left out:
"categories" - (optional) this could appear either in the 'root'
object or in one of the resources (or both). It would be an array
category terms.
More on category syntax later today.
-Ross.
rossf...@gmail.com
refactored design that they didn't need to comment upon it, I'll throw
the redesigned output for the 'service document'.
This (and the opensearch description document response) was *much* too
closely tied to Atom. So now it conforms a little more to the new
design and adds some more versatility. I think most of the fields
should be pretty obvious.
I've added the "path" field so a backend Jangle connector doesn't have
to conform 1:1 with the semantics of the core. An incoming request to
http://jangle.org/service_name/actors/ could really map to
http://connector.jangle.org/path/to/patrons/
I'm not sure 'searchable' is necessary or not here since I don't know,
yet, how that might map to an Atom service document. I suppose this
is another place where namespacing in an extension might be a useful
prospect.
{
"type":"services",
"title":"openbiblio",
"entities":{
"Actor":{
"path":"/actors/",
"title":"Borrowers",
"searchable":false,
"accept":["text/x-vcard"],
"categories":[]
},
"Collection":{
"path":"/collections/",
"title":"Categories",
"searchable":false
},
"Item":{
"path":"/items/",
"title":"Holdings records",
"searchable":false
},
"Resource":{
"path":"/resources/",
"title":"Bibliographic Records",
"searchable":true,
"accept":["application/marc","application/xml","text/
html"],
"categories":[]
}
}
}
-Ross.
On Sep 2, 5:19 pm, "Ross Singer" <rossfsin...@gmail.com> wrote:
> Ok, after some consideration, here is a proposal for (in my mind)
> improved JSON response for a 'feed' request (i.e., your normal
> connector response). It's quite different from the current response.
>
> In the "root" of the response, there are some new elements ("type",
> "formats", "alternate_formats", "stylesheets" and "availableResults").
>
> "type" replaces the mime type response that was previously used. Here
> I'm just using a string ("feed"), but I'd probably be more inclined to