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

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

Thanks Jim,
follow-up from me on a couple of items:

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>


That's certainly a position we can take but does the the
"all-or-nothing" proviso buy anything?  A client must inspect
headers to determine the descriptor URI - and it must do this attachment-by-attachment.
 Another concern - consider a server which initially does not have
support for descriptors.  Then a new version of the server comes out
with descriptors as a new feature.  Ensuring that "already created"
attachments have a descriptor might be problematic (eg, those in a baseline).
 These questions would have to be answered by any implementation effort
but we don't want the spec to make that effort more difficult, especially
when (afaict) there is no obvious benefit to the client.


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>

I don't think I captured what I was getting at.  A
client can only determine if a server supports PUT/PATCH on a descriptor
by making that request or by issuing an OPTIONS on that resource.  But
that is standard http - so what is the import of 7.5.7?

Thanks for all your hard work dealing with everyone's
comments!

best wishes,
    -ian

ian.green@uk.ibm.com (Ian Green1/UK/IBM@IBMGB)
IBM



From:      
 Jim Amsden/Raleigh/IBM
To:      
 Ian Green1 <ian.green@uk.ibm.com>
Cc:      
 OASIS (oslc-core@lists.oasis-open.org)
<oslc-core@lists.oasis-open.org>
Date:      
 27/01/2016 22:50
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
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.xhtml
and 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:AttachmentDescriptor
properties 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>


img: that's certainly a position we can
take.  Is it right then that each attachment 

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>
img: I don't think I captured what I was getting at.  A
client can only determine if a server supports PUT/PATCH on a descriptor
by making that request or by issuing an OPTIONS on that resource.  But
that is standard http - so what is the import of 7.5.7?

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


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