Review comments for OLSC Resource Preview 3.0

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