Explain Operation (SRU Version 1.2 Specifications)
The Explain operation allows a client to retrieve a description of the facilities available at an SRU server. It can then be used by the client to self-configure and provide an appopriate interface to the user. The record is in XML and follows the ZeeRex Schema.
There are two methods for getting the explain record:
- Via the SRU Explain Operation.
- Via the http GET request at the base URL for the service (no parameters).
This can be considered an SRU request (and hence have a default recordPacking of 'xml'), with no extraRequestData and leaving it up to the server to determine the version of the response.
Otherwise, the response is identical to an SRU explainResponse message.
PARAMETERS
Request Parameters
| Name | Mandatory/Optional? | Description |
|---|---|---|
| operation | Mandatory | The string: 'explain'. |
| version | Mandatory | The version of the request, and a statement by the client that it wants the response to be less than, or preferably equal to, that version. See Versions. |
| recordPacking | Optional | A string to determine how the explain record should be escaped in the response. Defined values are 'string' and 'xml'. The default is 'xml'. See Records. |
| stylesheet | Optional | A URL for a stylesheet. The client requests that the server simply return this URL in the response. See Stylesheets. |
| extraRequestData | Optional | Provides additional information for the server to process. See Extensions. |
Response Parameters
| Name | Type | Mandatory? | Description |
|---|---|---|---|
| version | xsd:string | Mandatory | The version of the response. This MUST be less than or equal to
the version requested by the client. >> See Versions. |
| record | record | Mandatory | A single Explain record, wrapped in the record metadata fields. >> See Records. |
| extraResponseData | xmlFragment | Optional | Additional information returned by the server. >> See Extensions. |
| echoedExplainRequest | <echoedExplainRequest> | Optional | The request parameters echoed back to the client in a simple XML form. >> See Echoing the Request. |
ZEEREX FOR SRU
ZeeRex/SRU Summary:
- The protocol attribute on the serverInfo element MUST have the value: SRU
- The transport attribute on the serverInfo element MUST be one of: http or https
- The method attribute on the serverInfo element MUST be a space separated list, comprising any number of the following values: GET POST SOAP
- The database element within serverInfo MUST contain the path section of the URL to the server, without the first / and up to the ?
- The set element within indexInfo is used to define the short names of context sets.
- Indexes are described by including the name of the index in the name element within map, and the short name for the context set in the set attribute on that element.
- The schemaInfo section is used to described the schemas supported by the server.
Full ZeeRex
Specifications (via explain.z3950.org 
)
EXAMPLES
The following URLs would all retrieve the explain document:
http://myserver.com/cgi/mysru?operation=explain&version=1.1&recordPacking=xml
http://myserver.com/cgi/mysru?
http://myserver.com/cgi/mysru
http://myserver.com/cgi/mysru?
http://myserver.com/cgi/mysru
The corresponding response from the server would be:
<sru:explainResponse xmlns:sru="http://www.loc.gov/zing/srw/">
<sru:version>1.1</sru:version>
<sru:record>
<sru:recordPacking>XML</sru:recordPacking>
<sru:recordSchema>http://explain.z3950.org/dtd/2.1/</sru:recordSchema>
<sru:recordData>
<zr:explain xmlns:zr="http://explain.z3950.org/dtd/2.1/">
<zr:serverInfo protocol="SRU" version="1.2" transport="http"
method="GET POST SOAP">
<zr:host>myserver.com</zr:host>
<zr:port>80</zr:port>
<zr:database>cgi/mysru</zr:database>
</zr:serverInfo>
<zr:databaseInfo>
<title lang="en" primary="true">SRU Test Database</title>
</zr:databaseInfo>
<zr:indexInfo>
<zr:set name="dc" identifier="info:srw/cql-context-set/1/dc-v1.1"/>
<zr:index>
<zr:map><zr:name set="dc">title</zr:name></zr:map>
</zr:index>
</zr:indexInfo>
<zr:schemaInfo>
<zr:schema name="dc" identifier="info:srw/schema/1/dc-v1.1">
<zr:title>Simple Dublin Core</zr:title>
</zr:schema>
</zr:schemaInfo>
<zr:configInfo>
<zr:default type="numberOfRecords">1</zr:default>
<zr:setting type="maximumRecords">50</zr:setting>
<zr:supports type="proximity"/>
</zr:configInfo>
</zr:explain>
</sru:recordData>
</sru:record>
</sru:explainResponse>
<sru:version>1.1</sru:version>
<sru:record>
<sru:recordPacking>XML</sru:recordPacking>
<sru:recordSchema>http://explain.z3950.org/dtd/2.1/</sru:recordSchema>
<sru:recordData>
<zr:explain xmlns:zr="http://explain.z3950.org/dtd/2.1/">
<zr:serverInfo protocol="SRU" version="1.2" transport="http"
method="GET POST SOAP">
<zr:host>myserver.com</zr:host>
<zr:port>80</zr:port>
<zr:database>cgi/mysru</zr:database>
</zr:serverInfo>
<zr:databaseInfo>
<title lang="en" primary="true">SRU Test Database</title>
</zr:databaseInfo>
<zr:indexInfo>
<zr:set name="dc" identifier="info:srw/cql-context-set/1/dc-v1.1"/>
<zr:index>
<zr:map><zr:name set="dc">title</zr:name></zr:map>
</zr:index>
</zr:indexInfo>
<zr:schemaInfo>
<zr:schema name="dc" identifier="info:srw/schema/1/dc-v1.1">
<zr:title>Simple Dublin Core</zr:title>
</zr:schema>
</zr:schemaInfo>
<zr:configInfo>
<zr:default type="numberOfRecords">1</zr:default>
<zr:setting type="maximumRecords">50</zr:setting>
<zr:supports type="proximity"/>
</zr:configInfo>
</zr:explain>
</sru:recordData>
</sru:record>
</sru:explainResponse>