Re: [oslc-core] Review comments for OLSC Resource Preview 3.0

David, 
Again thanks for the review. As always
comments in <jra> tags.

Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575

From:      
 David Honey <>
To:      
 "OASIS OSLC Core
TC Discussion List" <>
Date:      
 01/29/2016 08:48 AM
Subject:    
   [oslc-core]
Review comments for OLSC Resource Preview 3.0
Sent by:    
   <>

My comments for https://tools.oasis-open.org/version-control/svn/oslc-core/trunk/specs/resource-preview.html#bib-RFC4627in this colour 

Best regards, 
David 

------------------------------------------------------------------------------------------------

5 Working with Previews 
"Compact resources always have a JSON representation
[RFC4627],
but they can also have other representations such as XML,
T urtle [turtle]
or JSON-LD [JSON-LD].
" 
The links to JSON and JSON-LD do not work. 
<jra>These are the same ReSpec
issue.</jra>

http://open-services.net/bin/view/Main/OslcCoreUiPreview#Representation_Compactsays "The Compact document is an XML document,
even though it may be valid RDF/XML, it should be processed as an XML document.
". 
Why? 
Is the issue about preserving the ordering of the properties?
If so, why does this also not also apply to Turtle? 

For example, is it acceptable
to process that as RDF/XML using Jena? If not, why not. It seems perverse
to me to allow standard RDF formats like Turtle (which presumably can be
processed by Jena), but not allow the XML format to be processed as RDF/XML.
This seems bizarre to
me. Would it not be better to say use use standard RDF serialization formats
like RDF/XML, Turtle, and JSON-LD and then describe the RDF in the resource
shape? 

<jra>I think the motivation
was to allow tools that consume the compact resource to do so without having
to deal with RDF/XML. The use of Turtle and JSON-LD in OSLC3, and the easy
availability of APIs for processing them may eliminate the need to worry
about this, but its retained because of backward compatibility. The reason
for suggesting that it should be processed as XML is that servers might
make use of XML elements in the document for their specific extensions
that might not be RDF/XML. This is legacy compromise I suspect.</jra>

5.1 Getting the Compact Resource 
The HTTP Accept header
allows clients to access previews using the application/x-oslc-compact+xmlMIME type extension to request the Compact resource representation for
a URI instead of the content of the resource itself. This usage is considered
deprecated and is included only to maintain compatibility with [OSLCUIPreview20].

Why is this deprecated? 
One possible reason is that this only supports XML format?
The link doesn't work correctly. 
<jra>If a client
has a resource URI, and they want to access the Compact resource that provides
its resource preview, then they likely already have the Link header for
that Compact resource, provided when the resource URI was accessed. So
I think 1) the application/x-oslc-compact+xml is probably need needed to
reduce HTTP round trips, and 2) an extension header such as  application/x-oslc-compact+xml
is intended to be a temporary experimental thing, not something that should
be included in a standard. If the header is required, then the x- should
be removed and the header properly registered. Unfortunately that would
create the very incompatibilities we're trying to avoid. So deprecation
is the best way to go.</jra>

5.1.2 Discovering Compact Resources Using the HTTP Link Header 
Clients can request the Compact resource using the target URI of the Linkheader. 
Example 5: Requesting the Compact Resource 
GET /bugs/324/screenshot?compact HTTP/1.1
Host: example.com
Accept: application/json 
Does this guarantee a JSON response? 
What other media types MUST or MAY be supported by the server?
If "application/rdf+xml" is permitted, how does this differ from
the XML response format that says it should be be processed as RDF/XML?
<jra>OSLC (and LDP)
require support for Turtle and JSON-LD - that's specified in the OSLC overview
document. So application/json would guarantee a JSON response.  If
application/rdf+xml is specified, then the response body would need to
be RDF/XML. For OSLC2, the Accept header would be application/xml or text/xml.</jra>

5.1.3 Discovering Compact Resources Using the HTTP Prefer Header 
Clients can request a Compact resource by making an HTTP GET request to
the target resource's URI using the return=representationpreference of the HTTP Prefer request header [RFC7240]
and include parameter
[LDP]
value http://open-services.net/ns/core#PreferCompact.
Servers supporting resource preview must support this method of discovery
for resources with RDF or JSON representations. 
Does Accept=application/json guarantee a JSON response?
Should "must" be "MUST"? 
What other media types MUST or MAY be supported by the server?
<jra>Same as above,
Accept: application/json will return JSON. Must is ok since this section
is non-normative. LDP specifies Turtle and JSON-LD as does OSLC3. The representation
formations are described in oslc-core.html.</jra>

6.5 Displaying a small preview 
6.6 Displaying a large preview 
Is there a way that a client can request small vs large preview?
Or is the expected behaviour that servers return both small and large preview
data in the same response and the client can choose which to display?
Should a client preserve the ordering of data in the response (for JSON)?
If so, what about Turtle where ordering may not be preserved?
<jra>The client always
requests the preview it desires using either the oslc:smallPreview or oslc:largePreview
property of the Compact resource. Servers only return the specifically
requested preview. The Compact resource does not contain default preview
dialogs. There is no need to preserve the order of the data in the Compact
resource, the properties are not in a collection that could be ordered.
The small and large preview are HTML dialogs, not Turtle or JSON.</jra>

7.5 Compact Resources 
7.5.1 Servers MUST support the application/json[RFC4627]
and text/turtle[turtle]
media types for the Compact resource. 
Shouldn't this also include application/x-oslc-compact+xml?
<jra>No, since that's
deprecated. They would support application/x-oslc-compact+xml if they need
to be OSLC2 compatibile, but we don't require that, we only define how
it can be accomplished if desired.</jra>

A. Resource Constraints 
A.1 Resource: Compact 
B. JSON Representation Format 
The table in A.1 shows the RDF predicate prefixed name. However, the JSON
format in B seems to use an unqualified name, and I could not see anything
that said the JSON property names should match them, or reference some
other table where they are defined. Would it be clearer to have the JSON
section simply reference the table in A.1 with some statement about the
JSON property name? Currently the data seems duplicated between the two,
with the danger they might get out of sync with each other.
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
<jra>The JSON representation
in Appendix B is predefined JSON, not RDF or JSON-LD. The format is defined
by the constraints following the example. Its intended to be an easily
consumable format when RDF is not needed. If you add the JSON-LD context
in appendes B.1 to the JSON in B, you'll get the fully qualified names
and something that carries the full RDF representation.</jra>