JSON-LD vs plain JSON of compact resources

[Martin P Pain <martinpain@uk.ibm.com>]

I'll re-word my take on this from my previous
e-mail, based on the comments e-mailed out since:

(This is based on my impression of what
was discussed on the call prior to that e-mail, that in v3 we intend to
be dealing with "compact resources" which provide a description
of another (compacted) resource for UI display, etc. The compact resource's
triples may not be a subset of those on the compacted resource.)

1. Somewhere the consumer gets the URL
for the compact resource, probably through
    following a link from
another resource (e.g. a Link header).
2. It knows, through a specification
it was implemented against and where it got that URL
    from, that the target
of that link is "likely to be" a compact resource.
3. It requests that URL, using either
Accept: application/json or Accept: application/ld+json.

4a) IF the consumer requested application/json
then:
    IF the resource really is a compact resource then its representation
contains
        property
names "title", "shorttitle", etc. If it is not, what
happens is undefined (may
        return other
properties, may return a 406 not acceptable status).
    If the consumer recognises
any of these properties, then it treats it as a compact resource.
    If the consumer does not,
then the consumer ignores it and cannot display the resource
        preview.

4b) IF the consumer requested application/ld+json
then:
    IF the resource really is a compact resource then its representation
contains
        JSON-LD
using the predicates http://purl.org/dc/terms/title,
        http://open-services.net/ns/core#shortTitle,
etc.  If it is not, what happens
        is undefined
(may return other properties, may return a 406 not acceptable status).
    If the consumer recognises
any of these predicates, then it treats it as a compact resource.
    If the consumer does not,
then the consumer ignores it and cannot display the resource
        preview.


There's nothing to stop other properties
being included for either case.

There could be a single representation
that fulfills both these cases if that representation is JSON-LD using
the context in http://tools.oasis-open.org/version-control/browse/wsvn/oslc-core/specs/resource-preview.html#h2_json-representation-format

If we said providers MUST support the
application/json route, and MAY support application/ld+json (and MAY support
application/turtle), then:
1. consumers that just wanted plain
JSON (i.e. who don't have a JSON-LD library) could always ask for it. and
2. providers that wanted RDF (who have
a JSON-LD library) could ask for "Accept: application/ld+json, application/json;q=0.9",
then if they get back "Content-Type application/json" they can
apply the @context that's in the spec, if they get back "Content-Type:
appliation/ld+json" it's already there, and then in either case they
can use their JSON-LD library to parse it.

We could require providers to include
the link to the JSON-LD context in responses, but I don't think it buys
us much. It does mean that the last sentence in my previous paragraph is
described in the HTTP response, not just in the spec (presuming that link
header makes sense when returning application/json, which I would hope
so). This just means that fully-fledged JSON-LD clients can use OSLC providers
that only support application/json without having to have them be aware
of our specification, or writing that "check the media-type, if application/json
apply ixed context), but has the downside that either the providers have
to make that context available somewhere (not cache efficient) or we have
it available at a public URL with caching information that allows consumers
to hard-code it. This seems to open a can of worms, so I suggest we don't
require this of providers.

Martin Pain
Software Developer - Green Hat
Rational Test Virtualization Server, Rational Test Control Panel
Open Services for Lifecycle Collaboration - Automation WG joint chair

E-mail: martinpain@uk.ibm.com Find me on:  and within IBM on:

IBM United Kingdom Limited
Registered in England and Wales with number 741598
Registered office: PO Box 41, North Harbour, Portsmouth, Hants. PO6 3AU
Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number
741598. 
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
3AU




Martin Pain
Software Developer - Green Hat
Rational Test Virtualization Server, Rational Test Control Panel
OASIS Open Services for Lifecycle Collaboration - Automation technical
committee chair

E-mail: martinpain@uk.ibm.com Find me on:  and within IBM on:

IBM United Kingdom Limited
Registered in England and Wales with number 741598
Registered office: PO Box 41, North Harbour, Portsmouth, Hants. PO6 3AU



From:      
 John Arwe <johnarwe@us.ibm.com>
To:      
 oslc-core@lists.oasis-open.org,

Date:      
 07/04/2014 17:48
Subject:    
   Re: [oslc-core]
JSON-LD of compact resources
Sent by:    
   <oslc-core@lists.oasis-open.org>

---

> 1. Somewhere the consumer gets the URL for the
compact resource, 
> probably through 
>     following a link from another resource. 

I'm not sure what a "compact resource" is.  In the contributed
specs, there is simply "a" resource and it either does/not have
a compact *representation*. 
There have been past discussions to the effect that the "compact  representation"
language is incorrect, and it *should be* a separate resource ... is that
your meaning?  I thought on the call we agreed to stick with the base
definitions, but maybe I missed something. 

> 2. It knows, through a specification it was implemented against 
> (i.e. a resource shape 
>     from that spec) that the target of that link is "likely
to be" a
> compact representation. 

The client only knows (sticking with contributed-specs language in this
reply) that the resource identified by the URL it holds might/not have
a compact representation.

Even without that critical distinction, in general I'd be careful about implying anything around resource shapes; in our implementations it has been 1/n-1 (against resource shapes, i.e. exactly 1 product exposes them out of a dozen-plus).

>    4ai)IF the resource really is a compact representation then it

I think that's: If the server returned a compact representation ...

Which raises a NEW question, if we have >1 compact representation: how does the client know if it got back a compact representation?  In the contributed document, there is only one media type that covers both "what it is" semantically and "what syntax does it use".  On our espoused path that relation is no longer 1:1, and the media type only conveys the syntax (I assert, given what those media type registrations say).  

(and flipping this around) If we allow these json media types *as a way for a client to ask for a compact representation*, how does the server know to send a *compact* representation, vs a JSON or JSON-LD serialization of what a client would receive on a text/turtle request to the same URL?  I.e. how does the server know (given that the URL for the "compact representation" and the not-compact one are the same) which the client is really after?

Best Regards, John

Voice US 845-435-9470  BluePages
Tivoli OSLC Lead - Show me the Scenario


Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU