Overview
OAI-SQ is a simple extension to the Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH), intended to provide a method of performing keyword or field-based searches of an OAI repository. It is not intended to provide the level of sophistication available via other established search and retrieval protocols such as Z39.50.
Syntax
OAI-SQ queries are backwards-compatible versions of the OAI-PMH 2.0 ListRecords and ListIdentifiers requests. The search string (for a simple keyword search) or set of field name / search string pairs (for a fielded search) are conveyed as part of the setparameter in a ListIdentifiers or ListRecords request.
Keyword Search
An OAI-SQ keyword search request value consists of the string OAI-SQ! followed by one or more search keywords. So, for example, to perform a search for records that contain the keyword "biochemistry" you would pass in a setSpec value of OAI-SQ!biochemistry.
Fielded Search
An OAI-SQ fielded search request value consists of the string OAI-SQ-F! followed by one or more field name / search string pairs separated by "!" characters (both the pairs and the field name and search string are separated by "!"). So, for example, to search for "hawking" in the "author" field and "astrophyics" in the "subject" field you would pass in a setSpec value of OAI-SQ-F!author!hawking!subject!astrophysics. Field names should correspond to element names within the selected metadata format (specified in themetadataPrefix argument to the OAI-PMH query).
Escaping Characters
Any character within the search request string except the "!" separators and the initial OAI-SQ or OAI-SQ-F may be encoded in the form "~XX" where "XX" is the ASCII value of the character expressed in two-digit hexadecimal form. So, for example, to search for the string "foo!" you would pass in a setSpec value of OAI-SQ!foo~21 ("21" is the ASCII value of the "!" character, expressed in hexadecimal). Because the "!" character is reserved (has special meaning) in OAI-SQ it must be escaped (replaced with "~21") to be part of a search string.
Considerations
Identifying OAI-SQ Capability
OAI-PMH servers that support OAI-SQ keyword searching should return OAI-SQ as one of the available sets in response to a ListSets request. OAI-PMH servers that support OAI-SQ fielded searching should return OAI-SQ-F as one of the available sets in response to aListSets request. Servers that support both keyword and fielded searching via OAI-SQ should return both OAI-SQ and OAI-SQ-F as part of the ListSets results.
Search Mechanism Specifics
Because OAI-SQ is only intended to provide a mechanism for conveying search parameters to an OAI-PMH server, particulars of the search operation, such as the ordering of search results or support for mechanisms like phrase searching or term exclusion, are left to the discretion of the individual OAI-SQ implementer.
OAI-PMH Compatibility
Use of the "~XX" encoding mechanism may be necessary to maintain strict compliance with the OAI-PMH protocol because OAI-PMH 2.0 specifies that only characters that appear in the RFC2396 "unreserved character" set may appear in a setSpec value. For reference, this character set consists of letters, numbers, and the following punctuation marks:
mark = "-" | "_" | "." | "!" | "~" | "*" | "'" | "(" | ")"
Some OAI-SQ servers may allow characters outside the above set, so if strict OAI-PMH base protocol compliance is not a concern (e.g. when both server and client are known entities) then use of the "~XX" mechanism may only be necessary if search terms include a "!" character.
Examples
setSpec to retrieve records or identifiers that include the word "biochemistry":
OAI-SQ!biochemistry
URI to retrieve records that include the word "biochemistry":
http://scout.wisc.edu/archives/index.php?verb=ListRecords&metadataPrefix=oai_dc&set=OAI-SQ!biochemistry
setSpec to retrieve records or identifiers that include the word "anthropology" in the Description field and "diamond" in the Creator field:
OAI-SQ-F!description!anthropology!creator!diamond
URI to retrieve identifiers that include the word "anthropology" in the Description field and "diamond" in the Creator field:
http://scout.wisc.edu/archives/index.php?verb=ListIdentifiers&metadataPrefix=oai_dc&set=OAI-SQ-F!description!anthropology!creator!diamond
setSpec to retrieve records or identifiers that include the term "yahoo!" in the Publisher field and the term "stewart brand" in the Creator field:
OAI-SQ-F!publisher!yahoo~21!creator!stewart~0Abrand
(Note the use of "~21" to include the "!" character in the first search string, since that character is reserved by OAI-SQ, and the use of "~0A" to include a space in the second search string, since the space character is not allowed in OAI-PMH setSpec values.)
If you have comments or questions about OAI-SQ, please e-mail oaisq@scout.wisc.edu