OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

oslc-core message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: 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 <david.honey@uk.ibm.com>
To:        "OASIS OSLC Core TC Discussion List" <oslc-core@lists.oasis-open.org>
Date:        01/29/2016 08:48 AM
Subject:        [oslc-core] Review comments for OLSC Resource Preview 3.0
Sent by:        <oslc-core@lists.oasis-open.org>




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>




[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]