Re: [oslc-core] Review of OSLC Attachments 3.0

["Jim Amsden" <jamsden@us.ibm.com>]

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


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




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..."
<jra>Fixed.</jra>

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>

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

best wishes,
   -ian

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