Version 1.X, ...
The Record Update service allows for remote maintenance and administration of records within a compliant database. It has a very simple and extensable mechanism for doing this, a single request/response pair that allows for creation, replacing and deleting records and metadata about those records.
The need for such a protocol has been expressed by several groups, but may benefit many. In particular, it is required for datasets which are maintained by distributed collaboration and contribution such as union catalogues, local history databases, book review databases and so on. Going further, it also allows many clients to be created for one service rather than a very tightly linked client/server relationship.
Although the protocol is being developed under the SRW 'umbrella', there is no need to implement SRW/U. It would be perfectly feasable to implement Update in order to maintain a database served only via OAI, or only via a proprietary HTML interface. To contrast OAI and Update, OAI is a pull mechanism to update databases and is used generally for scheduled batch processing, whereas Update is a push mechanism and is intended for more interactive use.
The following issues are discussed in subsequent pages with respect to Update:
Messages use elements from three different namespaces. WSDL and Schema files are available for them.
| Prefix | Namespace URI | Description |
|---|---|---|
| srw | http://www.loc.gov/zing/srw/ | The SRW schema |
| ucp | http://www.loc.gov/zing/srw/update | Additional elements for Update |
| diag | http://www.loc.gov/zing/srw/diagnostic | SRW Diagnostics schema |
There are two operations in Update, Update and Explain. Update (below) contains a parameter which specifies the type of update operation to perform, and may be extended by profiles. Explain requests a service description record for the Update service.
| Name | Type | Required |
|---|---|---|
| srw:version | xsd:string | Mandatory |
| ucp:operation | xsd:string | Mandatory |
| ucp:recordIdentifier | xsd:string | Optional |
| ucp:recordVersions | sequence | Optional |
| ucp:recordVersion | Mandatory | |
| ucp:versionType | xsd:string | Mandatory |
| ucp:versionValue | xsd:string | Mandatory |
| srw:record | Optional | |
| srw:recordPacking | xsd:string | Mandatory |
| srw:recordSchema | xsd:string | Mandatory |
| srw:recordData | srw:stringOrXmlFragment | Mandatory |
| srw:extraRecordData | srw:extraDataType | Optional |
| srw:extraRequestData | srw:extraDataType | Optional |
| Name | Type | Required |
|---|---|---|
| srw:version | xsd:string | Mandatory |
| ucp:operationStatus | xsd:string | Mandatory |
| ucp:recordIdentifier | xsd:string | Optional |
| ucp:recordVersions | sequence | Optional |
| ucp:recordVersion | Mandatory | |
| ucp:versionType | xsd:string | Mandatory |
| ucp:versionValue | xsd:string | Mandatory |
| srw:record | Optional | |
| srw:recordPacking | xsd:string | Mandatory |
| srw:recordSchema | xsd:string | Mandatory |
| srw:recordData | srw:stringOrXmlFragment | Mandatory |
| srw:extraRecordData | srw:extraDataType | Optional |
| srw:diagnostics | sequence | Optional |
| diag:diagnostic | Mandatory | |
| diag:uri | xsd:anyURI | Mandatory |
| diag:details | xsd:string | Optional |
| diag:message | xsd:string | Optional |
| srw:extraResponseData | srw:extraDataType | Optional |
The version parameter on both request and response has the same semantics as the version parameter from SRW.
| Identifier | Description |
|---|---|
| info:srw/operation/1/create | Create a new record |
| info:srw/operation/1/replace | Wholly replace an existing record with a new record |
| info:srw/operation/1/metadata | Wholly replace the metadata about an existing record with a new metadata record |
| info:srw/operation/1/delete | Delete an existing record |
Further profiles may at their discretion create new identifiers for either new operations or extensions of the above operations with additional processing requirements.
The status of the operation is returned in this field. Defined values are:
| Identifier | Description |
|---|---|
| success | The server has completed the operation successfully |
| fail | The server could not complete the operation, additional information may be present in the diagnostics |
| partial | Part of the operation was successful, additional information may be present in the diagnostics |
| delayed | The server has not yet finished the operation |
A record identifer is a unique way to distinguish a record within the current context. The string may be any means to determine identity of the record, including but not limited to identifier strings, references to a result set and a position within it or a query which will evaluate to a single record. The recommended solution is an identifier string.
Some servers may also support identifying records by sending them in the record parameter. If the recordIdentifier parameter is present, then the record parameter must not be used in this way.
The server may create a result set with the record and return it as an identifier. If so, the result set should last for a reasonable amount of time, depending on the context, to allow futher references to it.
RecordVersions is a list of version information concerning the record. This is a means of tracking changes to a single record such that it maintains a persistent identifier throughout its existence, but the changes can still be tracked and referenced. A server may require that the most recent version of the record be supplied in a request to ensure that the operation is taking place on the most recent copy of the record.
Each recordVersion entry in the list is a pair consisting of a type and a value. Each type must be unique within the list. All entries must pertain to the same version. For example, if a checksum and a versionNumber are supplied, then the checksum must be that for the given versionNumber.
| Identifier | Description |
|---|---|
| versionNumber | An incrementing number or combination of numbers |
| datestamp | A datestamp for the time the record was last modified |
| checksum | A checksum for the record |
The record structure contains the actual record data to be used as part of the operation. It has the same structure and semantics as the SRW record structure.
Profiles and operations may require the presence of the record in either request or response for different operations.
Update also allows for a third type of recordPacking: 'url'. If the value of recordPacking in a request is URL, then the value of recordData is a string containing a URL to the record to be operated on. The expected use for this is to allow for clients to send a reference to a large record, possibly on an alternate site, and for the server to collect it at its leisure.