Retrieving Records in SRW

Version 1.1, 12th January 2004

Introduction

All records in SRW are returned in the XML format. Any records which are not natively XML must be transformed into XML before returning them. Such transformations are left up to other profiles to standardise if necessary. Records are not assumed to have any schema, and indeed may not even be stored as XML at all. Records in the response may be expressed as a single string, or as embedded XML. If the record is returned as embedded XML, it must be well formed and should be validatable against the requested schema.

Request Parameters

recordPacking

In order that records which are not well formed do not break the entire message, it is possible to request that they be returned as a single string with the < > and & escaped to their entity forms. Secondly some toolkits may not be able to distinguish record XML from the XML which forms the response.
However, some clients may prefer that the records be returned as XML in order to manipulate them directly with a stylesheet which renders the records and potentially also the user interface.

This distinction is made via the recordPacking parameter in the request. If the value of the parameter is 'string', then the server should escape the record before returning it. If the value is 'xml', then it should embed the XML directly into the response. Either way, the data is returned within the 'recordData' field. If the server cannot comply with this packing request, then it must return a diagnostic.

maximumRecords

Records are returned from a successful query if the maximumRecords parameter was supplied and positive. A query may be either a search, a reference to an existing result set or a combination of searches and resultsets. If the maximumRecords parameter is 0, then no records should be returned. If it is not supplied then the server is at liberty to return any number of records it desires. The number of records retrieved may not be the number requested but may not be greater than it. For example if the end of the result set is reached, then fewer records than requested may be returned. The maximum number of records that a server will return in one transaction is listed in the Explain setting 'maximumRecords'.

recordSchema

This parameter contains either a short name for a record schema or the full URI which identifies it, and is a request that the server should return any records in this schema. The short name must be the one advertised in the explain record for the database. If the server cannot return a record in this schema, then it must return a surrogate diagnostic saying so.
For example, if the explain record advertises that the Dublin Core schema's short name is 'dc', then either the client may send either 'dc' or 'http://www.loc.gov/zing/srw/dcschema/v1.0/' and expect to recieve the record in unqualified Dublin Core.

More details about record schemas are available.

recordXPath

This parameter may contain an xpath expression designating one or more nodes to return rather than the complete record. Note that this may mean that there is more than one element directly inside the recordData section of the record structure, if more than one element is referenced by the xpath expression. It may also mean that there are no elements within the recordData section, for example if the xpath supplied matches the content of an attribute. This xpath expression should be considered as relative to the recordSchema parameter, or the default record schema if the parameter is not supplied. If the server cannot evaluate the xpath expression, perhaps through lack of implementation or because the expression supplied was not valid, then it must return a diagnostic.

Examples of the use of the recordXPath paramater are available.

Records Response Parameter

The records parameter in the response is a sequence of 'record' elements, each of which contains either a record or a surrogate diagnostic explaining why that particular record could not be returned.

Each 'record' element within the 'records' sequence has the following contents:

Name Type Required Description

recordSchema xsd:string Mandatory The URI identifier of the XML schema in which the record is encoded. Although the request may use the server's assigned short name, the response must always be the full URI.

recordPacking xsd:string Mandatory The packing used in recordData, as requested by the client or the default.

recordData stringOrXmlFragment Mandatory The record itself, either as a string or embedded XML

recordPosition xsd:integer Optional The position of the record within the result set. This parameter is recommended for use in SRU, but may be returned in SRW as well.

extraRecordData xmlFragment Optional Any additional information to be returned with the record.

Name	Type	Required	Description
recordSchema	xsd:string	Mandatory	The URI identifier of the XML schema in which the record is encoded. Although the request may use the server's assigned short name, the response must always be the full URI.
recordPacking	xsd:string	Mandatory	The packing used in recordData, as requested by the client or the default.
recordData	stringOrXmlFragment	Mandatory	The record itself, either as a string or embedded XML
recordPosition	xsd:integer	Optional	The position of the record within the result set. This parameter is recommended for use in SRU, but may be returned in SRW as well.
extraRecordData	xmlFragment	Optional	Any additional information to be returned with the record.

An example record, in the simple Dublin Core schema, packed as XML:

  <record>
    <recordSchema>http://www.loc.gov/zing/srw/dcschema/v1.0/</recordSchema>
    <recordPacking>xml</recordPacking>
    <recordData>
      <dc:record>
        <dc:title>This is a Sample Record</dc:title>
      </dc:record>
    </recordData>
    <recordPosition>1</recordPosition>
    <extraRecordData>
      <rel:rank>0.965</rel:rank>
    </extraRecordData>
  </record>