SRU VERSION 1.1 ARCHIVE

SRU Extra Data

Messages in all of the operations, both in the request and in the response, have a field in which additional information may be provided. This is a built in extension mechanism where profiles may specify a schema for what to include in this section without requiring the developers to change the basic messages and thus render their implementation uninteroperable with other servers and clients. It is expected that if there is sufficient demand for a particular piece of additional information, that piece of information will be migrated into the protocol in a later version. In this way, only implemented and useful features will be added in future versions, rather than features which just seem like a good idea.

Profiles and Semantics

If the server does not understand a piece of information in an extraRequestData field, it may silently ignore it. This is unlike many other request parameters, where if the server does not implement that particular feature it should respond with a diagnostic. If the particular request requires some confirmation that it has been carried out rather than ignored, then the profile designer should include a field in the extraResponseData.

The semantics of parameters in the request may not be modified by extraRequestData. For example, a x-qt-queryType parameter could not change query to be an SQL query, as a server that does not understand the x-qt-queryType extension would expect the query to be in CQL, and thus be unable to parse it. Instead, the extraData should create a new element for the information.

The semantics of parts of the response may be modified by extensions. It would be possible (though very strange), for example, to replace the recordSchema field in the record structure with your favorite chocolate cookie recipe when the client sends a x-cookieType=chocolate request parameter. The response semantics may be changed in this way only if the client specifically requests the change. Clients should also expect to receive the regular semantics, as servers are at liberty to ignore extraRequestData fields.

ExtraResponseData may be sent that is not connected to the search in the request.  For example it may contain cost information regarding the query or information on the server or database supplying the results. This data must, however, have been requested.

SRU Parameter

For SRU the name for an extra-data parameter must begin with 'x-'  -- lower case x followed by hyphen. (The SRU protocol will never include an official parameter with a name beginning with 'x-'.) It is suggested, but not required, that the parameter name be 'x-' followed by an identifier for the namespace for the extension (again followed by hyphen), followed by the name of the element within the namespace. For example 'x-info-4-onSearchFail' for <theo:onSearchFail>. (In this example 'info-4' identifies the namespace; see next paragraph.). Note that this convention does not guarantee uniqueness since (in contrast to SRW - see SRW Parameter below.) the parameter name will not include a URI. The extension owner should try to make the name as unique as possible.

If the namespace is identified by an 'info:srw' URI (and note that there is no such requirement, the namespace may be identified by a URI of a different scheme, for example 'http'), then a convention that may be used (as in the example above) is to name the parameter "x-info-<nnn>-<element name>" where <nnn> is the 'srw:info' authority string. This convention (suggested but not required) should guarantee uniqueness. It is strongly suggested that an extension name never be assigned with this form except by the proper authority for the given 'info' namespace.

As the request may be echoed in SRU, the server must be able to transform the parameters into their XML form. If it encounters an unrecognised parameter, the server may either make its best guess as to how to transform the parameter, or simply not return it at all. It should not, however, add an undefined namespace to the element as this would invalidate the response.

If the contents of the parameter is an XML structure, then the profile designer should also specify how to encode this structure for SRU. This may simply be to escape all of the special characters, but the designer could also create a string encoding form with rules as to how to generate the XML in much the same fashion as the relationship between CQL and XCQL.

SRW Parameter

For SRW, The extra data fields is an XML structure. Even if there is only one piece of additional information supplied, it must be within a namespaced XML element. This is in order to ensure that servers can distinguish a field from one profile from another.  Examples:

<extraRequestData>
      < theo:onSearchFail xmlns:theo="info:srw/extension/4/searchextensions">scan
< /theo:onSearchFail> </extraRequestData>

<extraResponseData>
       <rob:relevancyAlgorithm xmlns:rob="info:srw/extension/2/relevancy">CORI
     < /rob:relevancyAlgorithm>
< /extraResponseData>

Extra data fields are identified by the root XML element qualified by the supplied namespace. In the above examples, for the extra request data the extension's identifier is 'onSearchFail' from namespace info:srw/extension/4/searchExtensions. The extra response data has identifier 'relevancyAlgorithm' from namespace info:srw/extension/2/relevancy. Below there is another example, where the extension's identifier is 'rank', also from the latter namespace.

Extra Data Example

Following is an example of how to create an extension - the "Record Schema Negotiation Extension" whose purpose is to allow the client to propose multiple record schemas that it will accept in response and let the server select one, rather than the client giving the server an ultimatum as to which record schema to return. Therefore this extension modifies the base semantics of the protocol, as the record schema URI in the response might not be the one in the recordSchema parameter of the request.

This is an example only, not part of the SRU (or SRW) protocol itself.

Record Schema Negotiation Extension

This is version 1.0 of the Record Schema Negotation Extension.

The extension's namespace id is:
info:srw/extension/2/schemaNegotiation-1.0
When used with SRU, the prefix 'info-2-rsn-' should be put before the parameter name.

The extension defines one parameter for the request: schemaNegotation.

This parameter contains a single string. The string is a space separated list of record schema URIs or short names. It is recommended that the list be supplied in priority order.

Note that the following record schema URI: "info:srw/schema/1/server-choice" may be included in the list. If so, this is an indication that the client wants the server to select an alternative schema if none in the list is supported. If this URI is included, it is recommended that it be included last. (Note: this URI is not intended for use as the value of the recordSchema parameter in a searchRetrieveRequest.) When used with SRU, the prefix 'info-1-' should be put before the parameter name; thus the parameter would be rendered as: x-info-1-server-choice.

If this extension is supported, then the server should select one of these record schemas (preferably the first in the list that the server supports) rather than the recordSchema request parameter. The selected record schema's URI should be in the recordSchema field of the record as usual. The server may select different schemas for records within the same response.

If the server cannot support any schemas in the list:

• If the client wishes the server to select an alternative schema, it is recommended (in addition to including the server choice URI described above in the list) to omit the recordSchema parameter (thus if the server does not support the extension, non-support will be transparent).
• If the client does not want the server to select an alternative schema, it is recommended (in addition to not including the server choice URI in the list) to include the recordSchema parameter (similarly, if the server does not support the extension, non-support will be transparent).

In SRU, this parameter should be rendered as: x-info-2-rsn-schemaNegotation

Example

Given the request:

 http://srw.cheshire3.org/l5r?operation=searchRetrieve&version=1.1
     &query=dc.title%20any%20%3Dcat dog%3D&recordSchema=dc
     &x-info-2-rsn-schemaNegotation=dc%20ccg%20marcxml
      

Or the equivalent request in SRW:

 <searchRetrieveRequest>
   <version>1.1</version>
   <query>dc.title any "cat dog"</query>
   <recordSchema>dc</recordSchema>
   <extraRequestData>
     <rsn:schemaNegotiation
 xmlns:rsn="info:srw/extension/2/schemaNegotiation-v1.0">
         dc ccg marcxml
     </rsn:schemaNegotation>
   </extraRequestData>
 </searchRetrieveRequest>  
      

Then the server may select any of DC, CCG or MarcXML as the record schema for any record returned in the response.

extraRecordData and extraTermData

In addition to extraRequestData and extraResponseData, there are two further elements in which "extra data" can occur. These are (1) within the record element for any individual record, in a searchRetrieveResponse and (2) within the term element for any term in a scanResponse message. These contain profiled information about the record or term. This data can include (but is not limited to) metadata about the record or term. For example, extraRecordData might include a field with the relevance associated with the record in a relevance ranked search; extraTermData might include a link to the term within a thesaurus.

extraRecordData example (highlighted in orange):

<record> 
   < recordSchema>info:srw/schema/1/dc-v1.1</recordSchema> 
       <recordPacking>xml</recordPacking>
    <recordData> 
        < srw_dc:dc>
            <dc:title>Thisis a Sample Record</dc:title> </srw_dc:dc> 
    < /recordData>
    <recordPosition>1</recordPosition>
    <extraRecordData>
     <rel:rank xmlns:rel="xmlns:rob="info:srw/extension/2/relevancy">0.965</rel:rank
   < /extraRecordData> 
< /record> 
      

(extraTermData example to come.....)

Registered Extensions

The URIs in the first column of the table below are extension namespaces. See the reference for extensions defined within that namespace.