Hi Richard and all, Apologies for taking so long to give the draft profile a good read, I finally did so on my flight to OR. I have a few global and structure comments, a question about intention meaning, and then a number of more specific comments. Sorry if I say something silly because I missed discussion, feel free to flame any such comments.
Cheers, Simeon Structure and Global - There is a great deal of repetition between the descriptions of requests for separate metadata and file create/replace/add, and for Multipart create/replace/add, which I think makes them seem more different and complicated than they are. Could sections 6.3.2, 6.5.3 and 6.7.4 be rewritten to specify only the behaviors specific to the Multipart combination and avoiding repetition of the metadata/file parts? - It seems odd to me that section 6.3.2 (Multipart Deposit) before section 6.3.3 (Metadata / Atom Entry Deposit)? Would is be better to mirror 6.5.X and 6.7.X and do file/metadata/both? - For symmetry, should section 6.5.3 be renamed "Replacing the Metadata and File Content of a Resource" - There are several "(or other allowed)" => "(or other allowed value)" in packaging descriptions Question - In sections 6.5 and 6.6 there are requirements for the server to "effectively replace" or "effectively delete" all the existing content. This is very vague and I wonder whether we can say something more specific. I'll hazard a suggestion: Do we really mean that these actions should replace/delete all existing content at the Cont-IRI? And that any mechanism to implement versioning would, in effect, move existing content to some other URI? I know that this is a way to think of how it happens for arXiv and I have been trying to think how one could meet the conditions currently specified without renaming the resources (changing the IRIs). Detailed comments - 3. in Cont-IRI parens: "...is returned will be through..." => "...is returned will be decided through.." - 3. last para: "differentiable" => "distinct". - 5. I think the opening sentence needs few more words explaining what this is about. Perhaps start "SWORD defines the following IRIs to indicate basic packaging formats. Additional packaging format IRIs may be added to this namespace as described in [Section 7]." - 6.1 sword:maxUploadSize bullet: would it be simpler and less open to m-is-interpretation (k = 1000 or 1024?) to specify this in bytes rather than kB. HTTP, for example, use bytes for Content-Length so this would seem more consistent. - 6.1 sword:maxUploadSize bullet after example: I'm really not sure what this ends up saying with a mix of "don't make assumptions" and then "be reasonable" which, of course, depends on some assumption. To me the idea of no size limit at all is silly: there will be one either intentionally or by some practical limitation (might not be well defined though). I would propose removing the recommendation: "If no sword:maxUploadSize is specified, the client MUST NOT assume any particular size limit unless one has been communicated outside of the SWORD protocol." - 6.1 sword:acceptPackaging bullet: I think it is a little misleading to describe the binary package format as for "opaquely packaged content" as I think a more common case would be a file that is not packaged. Perhaps change the ending from "in order to deposit opaquely packaged content" => "in order to deposit content that the server should not attempt to unpack" (Having read the notion of binary format wrong the first time I read through the document I am now quite happy with that a null-packaging or don't unpack format that could stand for either a file that isn't otherwise packaged or is "opaquely packaged".) - 6.3.1 Should the title of this section be "Creating a Resource with a File Deposit" (the current use of the word "Binary" seems confusing with the binary packaging when it could be any packaging format). - 6.3.1 first para, following on from suggested change of title I would also change "binary content" in the first sentence: "The client can create a resource by POSTing the binary content as the body of an HTTP request" => "The client can create a resource by POSTing content as the body of an HTTP request"? - 6.3.1 after second set of bullets: "Once the server has processed..." => "Once the server has successfully processed...". I think "successfully" has to be added in all the cases where there isn't an explicit ", or an appropriate error code". I'll try to note each one. - 6.3.2 after second set of bullets: "Once the server has processed..." => "Once the server has successfully processed..." - 6.3.3 after second set of bullets: "Once the server has processed..." => "Once the server has successfully processed..." - 6.4 start of first para: perhaps "The Deposit Receipt MUST contain two IRIs...."? since this is a requirement for the server. - 6.4 end of first para: I'm a bit confused by the language which I think is trying to say "don't worry it isn't complicated" and "in the examples we use EM-IRI but you could issue the same GET requests using Cont-IRI". I suggest replacing the last sentence: "The Deposit Receipt MAY specify the same URI for both the EM-IRI and the Cont-IRI, though this is not required. The examples in this section use the EM-IRI but the same GET requests may be issued against the Cont-IRI." - 6.4 para about On-Behalf-Of header: What does "for informational purposes" mean? It could mean, you may put it in the request but the server isn't allowed to do anything with it. Or it could mean, you can put it in the request and it is not specified whether or what the server might do with it. I think this should be made clear. - 6.4 enumerated point 1: can one have SHOULD/MAY as options? Would that have to be RECOMMENDED/MAY? Either way the second sentence needs to be more general than saying SimpleZip, perhaps: "If the Accept-Packaging header is not supplied, it is RECOMMENDED that the server provide the content using simple ZIP packaging (see Section 5: IRIs), but MAY elect another format. The server MUST supply the client with a package which meets the chosen specifications, and SHOULD provide the appropriate format IRI in a Packaging header on the response." - 6.5.1 Metadata Relevant bullet: "Metadata Relevant" => "Metadata-Relevant" - 6.7.1 third para: "the operation will not formally support metadata handling" seems very vague. I think the intent of this paragraph is to say that this operation does not allow a client to specify make any explicit change to the metadata associated with the item, but that the Metadata-Relevant header gives control over whether the server may try extracting metadata. I suggest: "The EM-IRI represents the Media Resource rather than the Container (SE-IRI, see Section 6.7.2). Thus, a POST to EM-IRI does not provide the client with any explicit control over the metadata associated with the Container, nor does it provide control over packaging of the Media Resource. Nonetheless, the client may use the Metadata-Relevant header to indicate that the file being uploaded may contain extractable metadata that could be used to augment the metadata of the container." - 6.7.2 end of para 3: "should consider implementing Section 6.7.1 for such operations" => "should consider implementing Section 6.7.1 to add files to the Media Resource." - 6.10 suggest change of section heading to "Use of SWORD headers with arbitrary IRIs" - 6.10 last para, suggest being more explicit than "arbitrary" => "The client MUST NOT assume that a SWORD server will support these headers for IRIs not specified in this profile." - 7.1 first para, typo and suggest removing redundant "reasonable" in: "both binary and Multipart deposits, and make reasonable requests..." => "both single file and Multipart deposits, and make requests...". - 7.2 suggest as "and replacement" to section heading - 7.2 para 3: I think this applies to both POST and PUT requests. I suggest: "If a server receives a POST or PUT request with an unacceptable Packaging header value, it MUST reject the request by returning an HTTP response with a status code of 415 (Unsupported Media Type), or store the content without further processing (as per [SWORD001])." - 11. At some level a name is a name and it doesn't matter two much what we call this provided we are consistent. However, I'm really not sure that "SWORD Statement" is the best name for this, particularly as we mix in some semweb stuff where we might call a triple a statement or assertion. Maybe folks have been round the block on this a bunch but I could think of options like "Manifest" or "State Document" or "Status Document" - 12. Error Documents. Is it worth suggesting that the short error description (atom:summary) might be presented to a user? This seems to me a useful distinction from the sword:verboseDescription which is suggested to be for developers. LocalWords: maxUploadSize kB ------------------------------------------------------------------------------ EditLive Enterprise is the world's most technically advanced content authoring tool. Experience the power of Track Changes, Inline Image Editing and ensure content is compliant with Accessibility Checking. http://p.sf.net/sfu/ephox-dev2dev _______________________________________________ Sword-app-techadvisorypanel mailing list Sword-app-techadvisorypanel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/sword-app-techadvisorypanel
