Review of OSLC Attachments 3.0

[Ian Green1 <ian.green@uk.ibm.com>]

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?

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

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
".

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

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.

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.

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?

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:AttachmentDescriptor
properties in the associated attachment descriptor".  This section
mentions "dcterms:modified"
which is not in the resource shape for a descriptor.

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.

What requirements on DELETE of an attachment container?

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.

7.5.4. Does filename include the extension?

7.5.7 What does this normative wording mean?  Isn't
it essentially empty?


Appendix A.1
http://mediatypes.appspot.com/
is 404 when i tried it - is this the wrong link? 

dcterms:modified  is
mentioned in the normative text but doesn't appear in the shape.

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