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
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
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
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-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.
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 a
ListSets request. Servers that support both keyword and fielded searching via OAI-SQ should return both
OAI-SQ-F as part of the
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.
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.
setSpec to retrieve records or identifiers that include the word "biochemistry":
URI to retrieve records that include the word "biochemistry":
setSpec to retrieve records or identifiers that include the word "anthropology" in the Description field and "diamond" in the Creator field:
URI to retrieve identifiers that include the word "anthropology" in the Description field and "diamond" in the Creator field:
setSpec to retrieve records or identifiers that include the term "yahoo!" in the Publisher field and the term "stewart brand" in the Creator field:
(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
If you have comments or questions about OAI-SQ, please e-mail firstname.lastname@example.org