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 of OSLC Attachments 3.0

Thanks Ian for the great review. Comments embedded below in <jra> tags...

Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data

From:        Ian Green1 <ian.green@uk.ibm.com>
To:        OASIS (oslc-core@lists.oasis-open.org) <oslc-core@lists.oasis-open.org>
Date:        01/26/2016 08:54 AM
Subject:        [oslc-core] Review of OSLC Attachments 3.0
Sent by:        <oslc-core@lists.oasis-open.org>

Here is a review of https://tools.oasis-open.org/version-control/svn/oslc-core/trunk/specs/attachments.html

as at svn 325

Section 5

The table seems to suggest (this section is non-normative) that Content-Length maps to oslc:attachmentSize but Content-Length can be wrong (just because clients that don't get it right) and it need not be present at all. In these cases, the suggested mapping is inappropriate.  Do we need to make this clearer, or perhaps remove Content-Length from this table?

<jra>Like Slug, Content-Length would be the client-suggested attachmentSize, but the server could calculate a different value if it for some reason changed the format or content of the attached resource, perhaps adding additional properties of it own. I'll add text clarifying this.

I also moved some of the detailed text out of the Basics section into the normative sections where it is more applicable.</jra>.

Content-Type has two parts - the type and the sub-type.  Is it appropriate to store the

<jra> I added a reference to http://www.iana.org/assignments/media-types/media-types.xhtmland indicated the media type and subtype are part of the attachment description format.</jra>

Typo: "
Additional, if the server..." should be "Additionally, if the server..."

Section 6.4

I think "To update an attachment, PUT the attachment content to the attachment container for the resource " should be "To update an attachment, PUT the attachment content to the attachment resource ".

<jra>Actually either could be correct. LDP servers are not required to support PUT on an LDPC, but if they do, then 1) the PUT cannot (directly) update the LDPC's containment triples, and 2) servers that allow creation of members via PUT (in addition to POST) should not re-use URIs.

But I don't think its that useful to mix create and update. PUT to an LDPC should be used to update the properties of the LDPC, not its members. I've included your update.</jra>  

The DELETE case shows a delete on the attachment container, not on an attachment.  DELETE on a container is not specified - see q below.

<jra>Agreed, the DELETE should be on the Attachment URI, not the LDPC. When the attachment is deleted, the container must update its containment triples (which are likely calculated by most server implementations). I fixed the example to include the attachment URI.  

Section 6.6  The example has a size declared as xsd:int but section 7 specified xsd:integer.  Likely some sort of conversion is ok, but I'm not sure.  Best for the example to use xsd:integer.

<jra>Fixed, it should be an unbound value not 32 bit</jra>

Section 7

7.2.1 seems to suggest that more than one attachment container is acceptable "... at least one Link header...".  Is this the case?  The non-normative wording suggested that there was at most one.

<jra>Fixed - change "An attachment is added" in Basics to "Attachments are added".</jra>

7.3.3 Since AttachmentDescription is optional, clients cannot tell from OPTIONS/etc whether any of the listed "describedby" Links are AttachmentDescriptor resources or some other resource that describes the attachment (there could be several).  Is there a justification for use of describedby rather than a predicate with this precise meaning in the OSLC namespace?

<jra>The expectation is that the client would use OPTIONS on the describedBy target URI to reflect on what the describing resource is. This is how any discovery is done in OSLC and LDP.</jra>

7.3.4 Seems a bit too strong to me.  I can imagine cases where the server would choose not to update the dcterms:modified, even tho the attachment state was updated.  I think we want the requirement to be that the server MUST ensure that any attachment descriptor resource is consistent with the state of the attachment, where consistent is defined by the server.  The upshot is that a server is responsible for defining the relationship between the attachment and its descriptor and once defined, it has to keep them coherent.  I think we could truncate the current text to "When servers update an attachment, they MUST also update any affected
oslc:AttachmentDescriptorproperties in the associated attachment descriptor".  This section mentions "dcterms:modified" which is not in the resource shape for a descriptor.
<jra>Agreed, replaced with your text</jra>

7.4.3 could be relaxed to a SHOULD NOT without any loss, I think.  There may be servers that really do not want to accept attachments that do not have a name.  Such servers would be forced to refuse the POST for some other reason.
<jra>Agreed, updated</jra>

What requirements on DELETE of an attachment container?

<jra>Added a clause that servers MUST reject an HTTP DELETE request on an attachment container.</jra>

7.5.1 Clarify that sever is free to choose, on an attachment-by-attachment basis, whether or not an attachment has a descriptor.  The current wording leaves this ambiguous, at least to my reading.
<jra>I read "for each attachment" to mean the server is consistent - either it provides an attachmentDescriptor for each attachment or none. What would be the use case for being selective? What criteria would a server use to decide whether a specific attachment got a descriptor or not? I think this intended to be an optional server capability, not an optional property of each individual attachment.<jra>

7.5.4. Does filename include the extension?
<jra>I don't think filename makes much sense in this context - these attachments are resources, not files. This should be the value of the Slug header if provided. Otherwise the server makes up the name, which could some from some tail element of the URI.</jra>

7.5.7 What does this normative wording mean?  Isn't it essentially empty?
<jra>No, it means the server may allow PUT or PATCH to update non-readonly attachment descriptor properties, but it doesn't have to. Description and title can be updated. Note that if the server doesn't allow PUT or PATCH, there's no way to change the AttachmentDescriptor dcterms:description as no value for this is specified on POST to create the attachment.</jra>

Appendix A.1

http://mediatypes.appspot.com/is 404 when i tried it - is this the wrong link?
<jra>Changed to http://www.iana.org/assignments/media-types/media-types.xhtml</jra>

 is mentioned in the normative text but doesn't appear in the shape.
<jra>Its no longer mentioned</jra>

best wishes,

ian.green@uk.ibm.com (Ian Green1/UK/IBM@IBMGB)
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

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