Re: [oslc-core] JSON-LD of compact resources

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

(To avoid going round in circles, which
I think I have already started doing, I've numbered my paragraphs, so if
you disagree [or even agree] with me, please state exactly which paragraph
it is. I've tried to split them according to the points which may be disagreed
with separately.)

(Spoiler: at the end I say the current
draft is acceptable, IMO. If you agree, just can skip to point 8.)

1. Personally, I'm happy for the spec
to provide "a one-way [lossy] 
   mapping to a pure-JSON
representation of [compact resources] useful to 
   ...clients". 

2a. I'd like the spec to provide a JSON-LD
context that can be used to 
   map that pure JSON compact
representation back to RDF. 

2b. Therefore we should make sure the
pure JSON compact representation 
    can be mapped to the correct
RDF using a JSON-LD context (see the 
    discussion about icon
resources for some ways this could restrict us). 

3a. Given that the pure JSON compact
representation would be defined in 
    the spec, that context
could also be given by the spec. 

3b. That context can be provided in
a non-normative section of the spec. 

4. Under my train of thought here, servers
would _not_ be required to 
   link to this JSON-LD context,
as it's just a useful mapping for clients 
   that can understand JSON-LD
AND understand this particular pure JSON 
   representation. 

5. As much as it would be good to support
clients that only understand 
   JSON-LD and not the pure
JSON compact representation, that seems less 
   important to me. RDF-aware
clients should ask for JSON-LD (or Turtle, 
   etc) explicitly, not rely
on pure JSON responses having a context. 

6. Therefore, for maximum interoperability
with servers, RDF-aware 
   clients will need to be
able to understand the pure JSON compact 
   representation (e.g. by
hard-coding the JSON-LD context from the spec) - 
   as not all servers will
provide RDF representations (JSON-LD, Turtle, 
   etc).
   
7. So far, what changes would this require
to the draft [1]? None. 

8. However, there is one problem I can
see. The JSON compact 
   representation says "All
resources MAY have additional properties not 
   specified here.".
However, are we guaranteeing that we won't define 
   additional properties here
in the future? Because if we do, they may 
   clash with server-specific
properties added by individual 
   implementations. Perhaps
in JSON that doesn't matter. When these keys 
   are mapped to RDF through
a JSON-LD context, it might cause a bit more 
   of a problem (There might
be a small chance that the JSON-LD conversion 
   process fails due to, e.g.
expecting a URI and it being a nested 
   resource or a number).
But clashes are so unlikely, and their effects 
   even more unlikely to be
problematic, that we don't need to do anything 
   else to avoid them.

So, in terms of JSON vs JSON-LD, while
there are 
some potential small problems, I think
the current draft is acceptable. 
(The discussions about discovery and
icon resource are separate, I'm not 
talking about them here.) 




[1] http://tools.oasis-open.org/version-control/browse/wsvn/oslc-core/specs/resource-preview.html?rev=8&sc=0&isdir=0

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

<oslc-core@lists.oasis-open.org> wrote on 15/05/2014
14:26:55:

> From: John Arwe <johnarwe@us.ibm.com>
> To: oslc-core@lists.oasis-open.org, 
> Date: 15/05/2014 14:27
> Subject: Re: [oslc-core] JSON-LD of compact resources
> Sent by: <oslc-core@lists.oasis-open.org>
> 
> Starting with http://tools.oasis-open.org/version-control/browse/
> wsvn/oslc-core/specs/resource-preview.html 
> 
> In mutation sequence: 
> 1 = the first GET /bugs/324 HTTP/1.1 response under heading 
> Discovering Compact Resources Using the HTTP Prefer Header 
> 2 = grafting in Martin's change for icon, so it's now (incomplete
> but useful for illustrative purposes) JSON-LD not vanilla JSON 
> 3 = smushing 1 + 2 together, noting the property name conflict that
> Might be what Martin was referring to, since he was coy on the 
> reasons why he didn't think a compatible representation was possible.
> 4 = 1-character tweak to 3, just one way to resolve that conflict;
> another would be ... 
> 5 = ...to make icon an array with 1 icon-as-string and 1 icon-as-
> object member. 
> diff is your friend. 
> 
> There is a conflict using a simple union because JSON is using 
> single-valued keys instead of a triple when defining its set.  As
> usual, ways exist to solve that and none that I see are 100% free.
> 
> Given that Core 2 has no JSON mapping, there is a sense in which we
> here are defining what "equivalent" means (what vanilla-JSON
is 
> "equivalent" to compact XML).  I had been thinking
in terms of the 
> simplest possible mapping (use the XML qname (sic) as the JSON 
> property name, ala oslc:smallPreview, but I realize that's just me
> being unoffended by "things that look like qnames but aren't"
and a 
> from-scratch JSON object would just use the ncname portion, so fine
> it's a logical cosmetic change), but others were perhaps already at
> the ncname stage.  Doesn't change the outcome materially. 
> 
> Options I see, if we want a single representation that can be 
> treated either as JSON or JSON-LD: 
> - deconflict the property name; some variation on 4 
> - make icon's value an array or object and push the deconfliction
> down one level; some variation on 5 
> 
> Given that no existing JSON clients exist (alternatively: any that
> do exist are wholly outside the 2.0 spec so they can be ignored) we
> do have flexibility in how faithful to the compact XML we choose to
be.   
> 
> On the "is it RDF or not" front, we should stop kidding
ourselves: 
> if we make it consumable as /json (sic), people will use it that way
> and then we will not be able to also say "it's really RDF though!"
> and make a change that breaks the JSON client but not the RDF (JSON-
> LD) client.  If we have a /json format that an RDF-aware server
can 
> easily create from an RDF model (e.g. by serializing it as JSON-
> compact), helpful to some.... but it 's still JSON not RDF if we 
> serve it as /json.   
> 
> We could also (if this serves someone's purpose) say "UI previews
> are really RDF resources" + "and here is a one-way [lossy]
mapping 
> to a pure-JSON representation of them useful to ...clients",
which 
> is separate and distinct from existing [lossless, from a "what
are 
> the triples" standpoint] standard RDF <> JSON transforms
like JSON-
> LD.  We can define that transform ONLY for UI previews, too,
as a 
> practical concession to widespread implementation practice. 
> 
> Best Regards, John
> 
> Voice US 845-435-9470  BluePages 
> Cloud and Smarter Infrastructure OSLC Lead 
> 
> 
> 
> 
> From:        Martin P Pain <martinpain@uk.ibm.com>
> To:        John Arwe/Poughkeepsie/IBM@IBMUS, 
> Cc:        oslc-core@lists.oasis-open.org 
> Date:        05/06/2014 05:58 AM 
> Subject:        Re: [oslc-core] JSON-LD of compact
resources 
> 
> 
> 
> In the interests of the "doing it right first time" approach
(if I 
> understood you John), and your suggestion of using concrete 
> examples, I believe this example shows one way of using a plain JSON
> structure for the icon resource (using a nested object) and a JSON-
> LD context that maps this to the "pretty trivial" RDF approach
that 
> John suggested. 
> 
> This JSON structure:
> { 
>  "icon": { 
>    "url": "http://example.com/icon.png",
>    "title": "Icon" 
>  } 
> } 
> 
> with this context: 
> { 
>  "@context": { 
>    "icon": "http://open-services.net/ns/core#icon",
>    "url": "@id", 
>    "title": "http://purl.org/dc/terms/title"
>  } 
> } 
> 
> results in these triples: 
> _:b0 <http://open-services.net/ns/core#icon>
<http://example.com/icon.png>
. 
> <http://example.com/icon.png>
<http://purl.org/dc/terms/title>
"Icon" . 
> 
> However, this doesn't attempt to allow a JSON structure that is 
> backwards-compatible with the XML/conceptual approach in 2.0. I 
> don't think there's a way to do that (that is, create those triples
> without a nested JSON object, without any JSON-LD keywords in the
> JSON structure), at least not from my knowledge of JSON-LD.
> 
> 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: [image removed]  and within IBM on: [image removed]
  
> 
> [image removed] 
> 
> 
> 
> 
> 
> IBM United Kingdom Limited
> Registered in England and Wales with number 741598
> Registered office: PO Box 41, North Harbour, Portsmouth, Hants. PO6
3AU 
> 
> <oslc-core@lists.oasis-open.org> wrote on 05/05/2014 19:51:05:
> 
> > From: John Arwe <johnarwe@us.ibm.com> 
> > To: oslc-core@lists.oasis-open.org, 
> > Date: 05/05/2014 19:51 
> > Subject: Re: [oslc-core] JSON-LD of compact resources 
> > Sent by: <oslc-core@lists.oasis-open.org> 
> > 
> > As long as we're in RDF space (as the subject's use of "JSON-LD"
> > could be read to imply), one should not require any new properties.
> > Things get murkier if we also have to stay in "generic JSON
(no ...-
> > LD) space" (as the subject's use of "compact resources"
could be 
> > read to imply when considering other threads).
> > 
> > As long as the content is RDF, it's pretty trivial to make 
> > assertions about properties of the image file: 
> > <>, oslc:icon, <...defect.jpg>   => unchanged
> > <>, oslc:iconTitle, "Defect" => <...defect.jpg>,
dcterms:title, "Defect" 
> > and so on.  An implementation that cared to serve a single
> > representation to both Core 2.0 and Core 3.0 clients could simply
> > union the triples. 
> > If we have or develop a "pure JSON" convention for
doing the same 
> > thing in 3.0, done. 
> > If we need to "get it right the first time" (at model
definition 
> > time) to have a single JSON/JSON-LD-compatible representation
of the
> > same thing (because we lack that "pure JSON" convention),
then we 
> > likely have a larger problem at that JSON/JSON-LD level and that
> > might lead us to re-examine other decisions.  This spec
provides a 
> > convenient venue for flushing those practicalities out I hope.
> > A separate issue perhaps is whether the restrictions on oslc:icon
as
> > a vocabulary term are desirable.  In the 2.0 generation
of specs, 
> > because we had a fuzzy boundary between what's part of the base
> > vocabulary and what's part of the resource shape (which is a
> > separate layer of requirement specific to a certain usage context),
> > I've seen cases where things seemed to bleed across the boundary
in 
> > ways that I wasn't crazy about.  The mention of 'provider'
in the 
> > definition demonstrates that - if we believe that's a restriction
on
> > the terms usage, does its use in Publisher actually fall within
it? 
> > The favicon format and 16x16 statements would be completely 
> > appropriate for a resource shape, I'm less sanguine about them
in a 
> > vocabulary document.  OTOH they're a should not a must,
so any 
> > client depending upon them is, in theory, already broken in the
> > general case.  In more recent vocabulary documents I've
generally 
> > argued for generality at that level in the formal definition,
and 
> > inclusion of a *clearly marked* example usage that is more specific,
> > in the vocab term comment. 
> > If the Core TC decided to accept them as limiting (presumably
in the
> > name of better compatibility with 2.0's ecosystem) and use something
> > different in 3.0, then there are other vocabularies to choose
from, 
> > and if none are to our liking the fallback to defining-new is
always
> > available.  A quick search of LOV shows a general (unrestricted
to 
> > favicon format) http://open.vocab.org/terms/icon
(at http://
> > open.vocab.org/terms.ttl) and FOAF (with some inconvenient RDFS
> > assertions) terms like http://xmlns.com/foaf/spec/#term_img
, 
> > http://xmlns.com/foaf/spec/#term_thumbnail
, and http://xmlns.com/
> > foaf/spec/#term_Image float to the top. 
> > When I was doing this sort of thing for Actions (how to handle
the 
> > blizzard of options for serializing http requests, with and without
> > parameters of various sorts), I made progress by just stamping
out 
> > concrete examples and showing them around.  Seems like that
pattern 
> > would be useful here.  Even if they never make it into a
spec (most 
> > of mine did not survive even my own eyeballs' opinions, let alone
> > others'), they do tend to communicate your intent better than
prose.
> > If you prune one yourself but still save it, and then someone
later 
> > says "what about X", it's already there to show why
it was pruned, 
> > or it's new and should be examined. 
> > Best Regards, John
> > 
> > Voice US 845-435-9470  BluePages
> > Tivoli OSLC Lead - Show me the Scenario
> > 
> > 
> > [image removed] Samuel Padgett---05/01/2014 01:52:24 PM---Hey,
John.
> > Steve and I had discussed this, and I agree. One problem is that
we 
> > might need a need pro
> > 
> > From: Samuel Padgett/Durham/IBM
> > To: John Arwe/Poughkeepsie/IBM@IBMUS, 
> > Cc: oslc-core@lists.oasis-open.org
> > Date: 05/01/2014 01:52 PM
> > Subject: Re: [oslc-core] JSON-LD of compact resources
> > 
> > 
> > Hey, John. Steve and I had discussed this, and I agree. One problem
> > is that we might need a need property or we'd be changing the
> > meaning of an existing property. It's also used by the Publisher
in 
> > the service description document. Would we want to change that
too?
> > 
> > http://open-services.net/ns/core#
> > 
> >     <rdf:Property rdf:about="http://open-services.net/ns/core#icon">
> >         <rdfs:isDefinedBy rdf:resource="http://open-services.net/ns/core#
> " />
> >         <rdfs:label>icon</rdfs:label>
> >         <rdfs:comment>URL to an icon
file that represents the 
> > provider. This icon should be a favicon format and 16x16 pixels
in 
> > size.</rdfs:comment>
> >         <rdfs:seeAlso
> > rdf:resource="http://open-services.net/bin/view/Main/
> > OslcCoreSpecification#Resource_Publisher" />
> >     </rdf:Property>
> > 
> > -- 
> > Samuel Padgett | IBM Rational | spadgett@us.ibm.com
> > Eclipse Lyo: Enabling tool integration with OSLC
> > 
> > 
> > 
> > [image removed] John Arwe---05/01/2014 10:54:20 AM---in  http://
> > tools.oasis-open.org/version-control/browse/wsvn/oslc-core/specs/
> > resource-preview.html
> 
> > 
> > [image removed] 
> > From: 
> > 
> > [image removed] 
> > John Arwe/Poughkeepsie/IBM@IBMUS 
> > 
> > [image removed] 
> > To: 
> > 
> > [image removed] 
> > oslc-core@lists.oasis-open.org 
> > 
> > [image removed] 
> > Date: 
> > 
> > [image removed] 
> > 05/01/2014 10:54 AM 
> > 
> > [image removed] 
> > Subject: 
> > 
> > [image removed] 
> > Re: [oslc-core] JSON-LD of compact resources 
> > 
> > [image removed] 
> > Sent by: 
> > 
> > [image removed] 
> > <oslc-core@lists.oasis-open.org> 
> > 
> > 
> > 
> > 
> > in http://tools.oasis-open.org/version-control/browse/wsvn/oslc-
> > core/specs/resource-preview.html section 4 Compact, I think icon
> > should also be a separate resource ala the previews. 
> > The icon has its own properties, like title, and its own URI
(the 
> > icon property shows this), so this seems pretty obvious.  
> > Implementations that want to populate the OSLC 2.0 properties
as 
> > well would still be free to do so, in order to interop with 2.0
clients.   
> > 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
> [attachment "Example1-Get-JSON-209-Response1.json" deleted
by Martin
> P Pain/UK/IBM] [attachment "Example1-Get-JSON-209-Response2.jsonld"
> deleted by Martin P Pain/UK/IBM] [attachment "Example1-Get-JSON-209-
> Response3-almost-compatible.json" deleted by Martin P Pain/UK/IBM]
> [attachment "Example1-Get-JSON-209-Response4-compatible.json"
> deleted by Martin P Pain/UK/IBM] [attachment "Example1-Get-JSON-209-
> Response5-compatible.json" deleted by Martin P Pain/UK/IBM] 
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail.  Follow this link to all your TCs in OASIS
at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
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