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.

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 set parameter in a ListIdentifiers or ListRecords request.

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.

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 the metadataPrefix argument to the OAI-PMH query).

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.

(Please Note: Early implementations of OAI-SQ (e.g. SPT/CWIS 1.3.1) use "|" instead of "!" as a separator character and differ in a couple of other respects (see below).)

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 a ListSets 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.

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.

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.

Early implementations of OAI-SQ (e.g. versions of SPT and CWIS prior to 1.4.0) differ from the version described here in three respects:

• They use "|" as a separator in setSpec values instead of "!",
• They do not recognize the "~" character escape mechanism, and
• They will not return OAI-SQ and OAI-SQ-F as part of their response to ListSets.

Because of the "|" separator character, These early implementations are not strictly backward compatible with OAI-PMH.

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/SPT--OAI.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/SPT--OAI.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
Last Updated:  Thursday April 6th, 2006