 |
 |
I've got no problem with these suggestions, except for the desire to restore the operation parameter. I hate the extra work of having to verify that the query parm that I got in the request is matched by the operation parm and have to be prepared to issue a diagnostic because of it. But, if Tony is prepared to hold his breath long enough (:-) and is willing to make it optional, I won't make a big fuss. I reserve the right to grumble under my breath whenever the topic come up again. Ralph > -----Original Message----- > From: SRU (Search and Retrieve Via URL) Implementors [mailto:[log in to unmask]] > On Behalf Of Hammond, Tony > Sent: Friday, August 14, 2009 10:55 AM > To: [log in to unmask] > Subject: SRU 2.0 Draft Feedback > > Hi: > > Here's some comments on the SRU 2.0 Draft I just posted to the > <[log in to unmask]> feedback list. I am copying them > here for information and/or discussion. > > Caveat: I recently joined up to the OASIS Search Web Services TC but these > comments represent my views before joining. > > Cheers, > > Tony > > > ==== > > Hi: > > Here's some initial feedback on the SRU 2.0 Draft. > > Cheers, > > Tony > > > ##### > > 1. Parameters / Elements > > I think it would help to break out Request Parameters from Response Elements > in Sects. 4, 6 and 7. The two sets are largely disjoint. (Same remark > applies to the Abstract Protocol Definition.) > > Also might help to break out discussion of Facets into separate section (as > Diagnostics and Extensions), especially since Facets is an optional feature. > I also think that Search Result Analysis is sufficiently specialized to > warrant its own section. > > Sect. 5 seems to be misplaced coming as it does in between Sect. 4 and > Sects. 6 and 7. > > > 2. Parameter / Element Ordering > > Not clear what the basis is for the orderings given in Sect. 2 (Table 1) and > 3 (Table 6). Is it a logical ordering? > > I note that "echoedSearchRetrieveRequest" is differently located (at bottom) > from its location in the 1.* XSD schema. Is that intentional? > > <xsd:complexType name="searchRetrieveResponseType"> > ... > <xsd:sequence> > ... > <xsd:element ref="echoedSearchRetrieveRequest" minOccurs="0"/> > <xsd:element ref="diagnostics" minOccurs="0"/> > <xsd:element ref="extraResponseData" minOccurs="0"/> > </xsd:sequence> > ... > </xsd:complexType> > > Also note that ordering is different in the tables and in Sect. 4. > > > 3. Response Elements > > Response elements are given for a specific serialization - XML. > > Is that what is intended by binding? I would have thought binding would be > to a specific data model (e.g. SRU) which can then be serialized various > ways: native XML, ATOM, RSS, JSON, etc. > > Thus don't see relevance of the angle brackets in Table 6. (And that does > also have a bearing on the type constraints that are offered if the elements > are not only XML.) > > Also, heading in Sect. 3.1 is to "Actual Reponse Elements ..." and should be > "Reponse Elements ..." only. (Cf Sect. 2.1 which is to "Request Parameters > ..." alone.) > > > 4. Response Elements: "resultSetIdentifier", "timeToLive", "idleTime" > > Mentioned in Sect 2, 3 and 4.10 the element "resultSetIdentifier" should be > "resultSetId" everywhere. > > And in Sect 3, "timeToLive" and "idleTime" should be "resultSetTTL" and > "resultSetIdleTime", respectively. > > > 5. Response Elements: "diagnostics" > > Probably don't need the "(non-surrogate)" in the name value field. Perhaps > this could be footnoted in the table? > > > 6. Request Parameters: "httpAccept-*" > > I think these params are incorrectly named and should follow the standard > camelcase style used elsewhere. e.g. > > Accept-Charset: httpAccept-charset -> httpAcceptCharset > Accept-Encoding: httpAccept-encoding -> httpAcceptEncoding > Accept-Language: httpAccept-language -> httpAcceptLanguage > Accept-Ranges: httpAccept-ranges -> httpAcceptRanges > > Even though they mimic the HTTP headers they break naming convention. > > > 7. Request Parameters: "rendering" > > This is just a query. I wonder if the terms "client" / "server" would be > more appropriate than "local" / "remote". It might be more correct to talk > about "local" / "remote" but I always end up having to do a double take to > figure out my relative position. > > > 8. Request Parameters: recordSchema, sortKeys/sortSchema > > Both "recordSchema" and "SortKeys/sortSchema" allow for short names to be > used in place of URIs. But the SRU registered short names [1] are not > unique. E.g. "mods" is mapped to four different XML schema (3.0, 3.1, 3.2, > 3.3) and likewise "pam" is ampped to two different XML schema (2.0, 2.1). > > Also in Sect. 4.7.1 it says under sortSchema "the URI for an XML schema". > What is meant though is the "short name" for an XML schema, which is a > placeholder for the URI. And that is shown in the examples but needs better > explanation. > > Still, the short name to URI mapping problem remains. > > [1] http://www.loc.gov/standards/sru/resources/schemas.html > > > 9. Response ID > > There is no ID returned in the response. If there are records then a > "resultSetId" is returned but not otherwise. Some serializations (e.g. ATOM) > require an ID (actually a URI) for the response. One strategy would be to > use the "resulSetId" as the basis for a unique ID, but this fails when no > records are returned and a response is still required to carry the > diagnostics. > > Is there some other place to return a unique response ID? > > > 10. Endpoints > > I would have preferred to see the "operation" parameter maintained so that > "searchRetrieve" and "scan" could both be located on the same endpoint, and > an explicit choice be made between them. Heuristics could be applied but I > think this is an unnecessary shorthand and may only lead to problems down > the line. I would have made this parameter optional at the least. > > As regards version agree that it could be dispensed with although don;t see > any real harm in allowing for an optional parameter. Definitely not a > required parameter. > > > 11. Typos, etc > > a) Sects 2 and 3 (Tables 1 and 6) > > Suggest that all categories which are not strict parameter names (e.g. > "Facet parameters", "Extension parameters", "Extension", etc.) be set in > italics to differentiate from actual parameter names. > > And some tidying up of punctuation etc., e.g. No periods on "Reference" / > "Restrictions" columns (which by the way should both be the same head e.g. > "Reference"?). And perhaps "see" instead of "See", and "optionsl" nstead of > "Optional". > > b) 4.7.1 "Sort Sub Parameters" and "sub parameters" in text > > Preferably "sub-parameter" or "subparameter". > > c) 4.7.2 "Textual Representation of sortKeys Parameter" > > Maybe should just be something like "Represention of sortKeys Parameter > Value". Don't need the "Textual", and this is the parameter *value*, not the > parameter we're talking about. > > d) 4.9.1 > > Should everywhere be "HTTP Accept header" (lowercase "header"), and > "Content-Location" (capitalized). > > ##### > > > > > > > ************************************************************************ ******** > DISCLAIMER: This e-mail is confidential and should not be used by anyone who > is > not the original intended recipient. If you have received this e-mail in error > please inform the sender and delete it from your mailbox or any other storage > mechanism. Neither Macmillan Publishers Limited nor any of its agents accept > liability for any statements made which are clearly the sender's own and not > expressly made on behalf of Macmillan Publishers Limited or one of its agents. > Please note that neither Macmillan Publishers Limited nor any of its agents > accept any responsibility for viruses that may be contained in this e-mail or > its attachments and it is your responsibility to scan the e-mail and > attachments (if any). No contracts may be concluded on behalf of Macmillan > Publishers Limited or its agents by means of e-mail communication. Macmillan > Publishers Limited Registered in England and Wales with registered number > 785998 > Registered Office Brunel Road, Houndmills, Basingstoke RG21 6XS > ************************************************************************ ********