SRU
Diagnostics
Sometimes things go wrong. In these cases the server is obliged to report that something went wrong, by sending a diagnostic record explaining what happened. A list of currently supported diagnostics is available and more may be identified in the future.
Diagnostics fall into two categories, 'fatal' and 'non-fatal'. A fatal diagnostic is one in which the execution of the request cannot procede and no records are available to return. For example, if the client supplied an invalid query there is nothing that the server can do. A non-fatal diagnostic on the other hand is one where processing may be affected but the server can continue. For example if a particular record is not available in the requested schema but others are, the server may return the ones which are available rather than failing the entire request.
Non-fatal diagnostics are also divided into two categories 'surrogate' and 'non-surrogate'. Surrogate diagnostics take the place of a record. For example if the second of three records was not available in the requested schema, then the response would include the first record, a surrogate diagnostic explaining that the second record is not available, and then the final record. Non-surrogate, non-fatal diagnostics are diagnostics saying that while some or all the records are available, something else went wrong. For example the requested sorting algorithm might not be available.
Surrogate diagnostics take the place of the record for which they are a surrogate in the 'records' parameter of the response. Non-surrogate records, both fatal and non-fatal, are returned in the 'diagnostics' parameter.
DIAGNOSTIC SCHEMA
Diagnostics are returned in a very simple schema which has only three elements, 'uri', 'details' and 'message'.
The required 'uri' field is a URI, identifying the particular diagnostic. When the URI begins with "info:srw/diagnostic/1/" (for example, 'info:srw/diagnostic/1/7') then the diagnostic is from the standard SRU diagnostic list. The 'details' part contains information specific to the diagnostic, format as specified by the individual diagnostic definition. The 'message' field contains a human readable message to be displayed. Only the uri field is required, the other two are optional.
It is recommended for all diagnostics that the final section should be a distinguishing integer (for example 'http://srw.cheshire3.org/diagnostics/1')
The identifier for the diagnostic schema is: info:srw/schema/1/diagnostics-v1.1
| Name | Type | Mandatory/Optional? | Description |
|---|---|---|---|
| uri | xsd:anyURI | Mandatory | The diagnostic's identifying URI. |
| details | xsd:string | Optional | Any supplementary information available, often in a format specified by the diagnostic |
| message | xsd:string | Optional | A human readable message to display to the end user. The language and style of this message is determined by the server, and clients should not rely on this text being appropriate for all situations. |
Examples
Non-surrogate, fatal diagnostic:
<diagnostic xmlns="//www.loc.gov/zing/srw/diagnostic/">
<uri>info:srw/diagnostic/1/38</uri>
<details>10</details>
<message>Too many boolean operators, the maximum is 10. Please try a less complex query.</message>
</diagnostic>
</diagnostics>
Surrogate, non-fatal diagnostic:
<record>
<recordSchema> info:srw/schema/1/diagnostics-v1.1</recordSchema>
<recordData>
<diagnostic xmlns="//www.loc.gov/zing/srw/diagnostic/">
<uri>info:srw/diagnostic/1/65</uri>
<message>Record deleted by another user.</message>
</diagnostic>
</recordData>
</record>
...
</records>
SRU Diagnostic Schema
see also .xsd
<!-- -->
<xsd:schema targetNamespace="http://www.loc.gov/zing/srw/diagnostic/" xmlns="http://www.loc.gov/zing/srw/diagnostic/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">
<xsd:element name="diagnostic" type="diagnosticType" nillable="false"/>
<xsd:complexType name="diagnosticType">
<xsd:all>
<xsd:element ref="uri"/>
<xsd:element ref="details" minOccurs="0"/>
<xsd:element ref="message" minOccurs="0"/>
</xsd:all>
</xsd:complexType>
<xsd:element name="uri" type="xsd:anyURI" nillable="false"/>
<xsd:element name="details" type="xsd:string" nillable="false"/>
<xsd:element name="message" type="xsd:string" nillable="false"/>
</xsd:schema>