Review comments for OLSC Resource Preview 3.0

[David Honey <david.honey@uk.ibm.com>]

My comments for https://tools.oasis-open.org/version-control/svn/oslc-core/trunk/specs/resource-preview.html#bib-RFC4627
in 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.

http://open-services.net/bin/view/Main/OslcCoreUiPreview#Representation_Compact
says "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?


5.1 Getting the Compact Resource
The HTTP Accept
header allows clients to access previews using the application/x-oslc-compact+xml
MIME 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.

5.1.2 Discovering Compact Resources Using the HTTP
Link Header
Clients can request the Compact resource using the target
URI of the Link header.

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?

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=representation preference 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?

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?

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?

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