1 Introduction

This is one of a set of documents for the OASIS Search Web Services (SWS) initiative.

This document is the specification of the Explain Operation.

The documents in this collection of specifications are:

1. Overview

2. APD

3. SRU1.2

4. SRU2.0

5. OpenSearch

6. CQL

7. Scan

8. Explain (this document)

1.1 Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].

1.2 References

All references for the set of documents in this collection are supplied in the Overview document:

searchRetrieve: Part 0. Overview Version 1.0

http://docs.oasis-open.org/search-ws/searchRetrieve/v1.0/csd01/part0-overview/searchRetrieve-v1.0-csd01-part0-overview.doc

1.3 Namespace

All XML namespaces for the set of documents in this collection are supplied in the Overview document:

searchRetrieve: Part 0. Overview Version 1.0

http://docs.oasis-open.org/search-ws/searchRetrieve/v1.0/csd01/part0-overview/searchRetrieve-v1.0-csd01-part0-overview.doc

2 Model

2.1 Operation Model

The SWS initiative defines three operations:

SearchRetrieve Operation. The main operation. The SRU protocol [1] defines a request message (sent from an SRU client to an SRU server) and a response message (sent from the server to the client). This transmission of an SRU request followed by an SRU response constitutes a SearchRetrieve operation.
Scan Operation. The Scan operation is defined by the Scan protocol [2]. Similar to SRU, it defines a request message and a response message. The transmission of a Scan request followed by a Scan response constitutes a Scan operation.
Explain Operation. Every SRU or scan server provides an associated Explain document, providing information about the server’s capabilities, retrievable as the response of an HTTP GET at the base URL for the server. A client may retrieve this document and use the information to self-configure and provide an appropriate interface to the user. When a client retrieves an Explain document, this constitutes an Explain operation.

2.2 The Explain Document

The purpose of the explain document is to provide sufficient information for a third party to access, query and process results from a database or query service.

The document describes a server’s capability in respect of:

how to search

query language, context sets, sample queries as URLs
specify optional requirements for results (sorting, syntax, schema, character set encoding, facets)
example queries

how to browse

query language, context sets, sample queries as URLs
defaults

how to negotiate and process results

specification of defaults
response formats

The Explain document may be made by the provider of a database or query service or it may be made by a third party. The documents are designed to be harvested and collected into centralised registries. Where made by third parties, the document may or may not be shared.

The schema for the Explain document is the same, whether created by the provider of the database or query service or provided by a third party.

3 Explain Elements

The Explain elements and attributes are shown in the table below. There are xx sections:

the root level
General description of the server and its capabilities
How to formulate a request
How to interpret a response

In addition to the element and attributes specified in this table, proprietary information including derived query languages and context sets may be included. Proprietary inclusions should be resolvable by namespaces. Similarly, proprietary schemas are permitted as well as well or in lieu of known ones and where included should be resolvable by namespaces.

The document schema has been designed so that documents may be easily mapped to it from existing SRU Zeerex [3] descriptions. Zeerex is the Explain specification for earlier versions of SRU.

Servers using SRU 2.0 may use a Zeerex document instead of an SRU explain document if they are not using any of the new featured covered by the latter documents.

In the second column of the table, whose heading is “M/O R/N” , ‘M/O’ means “mandatory or optional” and ‘R/N’ means “repeatable or non-repeatable”. And so the value is one of:

MR – Mandatory, repeatable (one or more occurrences)
MN – Mandatory, non-repeatable (exactly one occurrence)
OR – Optional, repeatable (Zero or more occurrences)
ON - Optional, non-repeatable (zero or one occurrence)

Element/Attribute	M/O R/N	Definition and Notes
Root level
explain	MN
attr: ‘authoritative’	ON	an indication that the owner of the database has also made the explain document and thus this is the definitive description.
attr: ‘id’	ON	an indication of the person or institution that created this document
General description of the server and its capabilities
serverInfo	MN	basic details required to start a network connection to the described server
attr: ‘protocol’	ON	name of the protocol used to access the server at this URL endpoint
attr: ‘version’	ON	indication of the latest version of the protocol supported for accessing the server
attr: ‘transport’	ON	name of the protocol used to access the database
attr: ‘wsdl’	ON	URL to a WSDL file which describes the server
serverInfo / host	MN	address of the server which provides the service, usually a name which will resolve to a correct IP address
serverInfo / port	MN	number of the port used for connection to the service
serverInfo / database	MN	name of the database accessed by the service described
attr: ‘numRecs	ÓN	indication of the number of records in the database
attr: ‘lastUpdate’	ON	date and time in format ISO 8601 (YYYYMMDDHHMMSS) of the latest addition or modification in the database
serverInfo / authentication	ON	authentication details that are required to access this server
attr: ‘required’	ON	an indication that authentication is required for access to the database by this method. Default is ‘true’
serverInfo / authentication / open	MN (choice)	publically available token which can be used for access
serverInfo / authentication / [string] user group password		publically available authentication elements which can be used for access
databaseInfo	ON	description of the database that is accessed by the server
the following attributes are common to databaseInfo elements
attr: primary	ON	indicates the default text that should be provided if language is not specified
attr: lang	ON	2 letter code from RFC 1766 indicating the language of the text
databaseInfo / title	OR	name of the database
databaseInfo / description	OR	free text information about the database including but not limited to coverage, strengths, size, quality and currency
databaseInfo / author	ON	name of a person or organization credited with the creation of the database
databaseInfo / contact	ON	name and address of a person to contact for information on the database
databaseInfo / extent	ON	indicates completeness of the database
databaseInfo / history	ON	information on the origin, development and evolution of this database
databaseInfo / langUsage	ON	indication of the languages covered in the database
databaseInfo / restrictions	ON	indication of limitations that may affect access to the database or reuse of its records
databaseInfo / subjects	OR	list of terms from a controlled vocabulary indicating the topical coverage of the database
databaseInfo / links	OR	URL links to alternative accesses to this database
databaseInfo / implementation	OR	information on the software and other technical components used by this database
metaInfo	ON	information concerning this explain document
metaInfo / dateModified	MN	date and time on which this explain document was last created or modified
metaInfo / aggregatedFrom	ON	URL linking to another server, indicating that the explain document was not created on this server but harvested
metaInfo / dateAggregated	ON	date and time on which this explain document was harvested
How to formulate a request
indexInfo	OR
indexInfo / set	OR	recognized scheme of pre-defined indexes
attr: name	MN	name of a recognized scheme of pre-defined indexes
attr: identifier	MN	identifier in the form of a URI pointing to a definition of the index scheme
indexInfo / set / title	OR	name of index scheme with an indication of language
attr: primary	ON	indicates the default text that should be provided if language is not specified
attr: lang	ON	2 letter code from RFC 1766 indicating the language of the text
indexInfo / index	OR	an index or access point that can be used in queries of data in a database
attr: id	ON	identifier of the index other than its title
attr: search	ON	indicates that this index is used by the server in search
attr: scan	ON	indicates that this index is used by the server in scan
attr: sort	ON	indicates that this index is used by the server in sort
indexInfo / index / title	OR	index name supported by the server
attr: primary	ON	indicates the default text that should be provided if language is not specified
attr: lang	ON	2 letter code from RFC 1766 indicating the language of the text
indexInfo / index / map	MR	indication of equivalent alternative names for the index within other sets
indexInfo / index / configInfo	OR	includes server defaults, fixed settings and indication of support for the index
indexInfo / index / configInfo	OR	includes server defaults, fixed settings and supported elements
indexInfo / index / configInfo / default /	MN	indicates that if an element is not given in a search, the server will apply this default value
indexInfo / index / configInfo / supports	MN	indicates that only one setting for an element is possible
indexInfo / index / configInfo / setting	MN	indicates that the server supports an element
indexInfo / sortKeyword	ON

searchInfo	MN	information on building a search, including sample queries, information on query types supported, how to requests facet counts and sorting
searchInfo / queryExample	OR	one or more complete sample queries that will be accepted by the server (OpenSearch element – recommend for SRU)
searchInfo / queryType	OR	repeatable structure indicating support for query types other than CQL. (CQL is the default if omitted from a search; searchTerms is a reserved value)
searchInfo / queryType / name	MN	name of the query type such as CQL, searchTerms, or other server defined query type
searchInfo / queryType / URI	MN	URI identifying the query type’s definition
searchInfo / queryType / URL	ON	Resolvable URL for a location where the query type’s definition may be found
searchInfo / queryType / supportLevel	ON
searchInfo / queryType / queryTemplate	ON	template that can be used as a guide to creating a query. Not required for CQL and searchTerms (OpenSearch element)
searchInfo / queryType / otherInformation	ON	additional information on the query type

searchInfo / facets	ON	indication of the level of support for facets, which provide analysis of search results giving counts and facilitate selection within a result set
searchInfo / facets / facet	MR	repeatable structure for each facet type supported and delivered by a server
searchInfo / facets / facet / facetType	MN	name of a facet
searchInfo / facets / facet / facetDescription	ON	additional information on a facet
searchInfo / facets / facet / limit	ON	indicates whether or not the server will accept a request to limit the facet count for a particular facet
searchInfo / facets / facet / limit / limitDefault	MN	limit on facet counts imposed by the server
searchInfo / facets / facet / limit / otherLimit	MN	an indication that a server will accept limits other than its own default
searchInfo / facets / facet / start	MN	an offset into the list of counts to allow paging
searchInfo / facets / facet /start / startDefault	MN	the offset applied by the server if no instruction is given in the query
searchInfo / facets / facet / start / otherStart	MN	an indication that a server will accept offsets other than its own default
searchInfo / facets / facet / sort	ON	indicates that a server will supply the facets in a sorted order on request
searchInfo / facets / facet / sort / sortBy	ON	indicates that a server supports sorting of facets alphabetically or by record count or both and indicates its default behavior
searchInfo / facets / facet / sort / sortOrder	ON	indicates that a server supports facet sorting in ascending or descending sequence or both and indicates its default behavior
searchInfo / facets / facet / sort / caseSensitivity	ON	indicates that a server supports case sensitive or case insensitive facet sorting or both and indicates its default behavior
searchInfo / sortKeys	ON	indicates that a server will supply results in a sorted order on request
searchInfo / sortKeys / sortKey	MR	repeatable sequence for each sort key supported by a server
searchInfo / sortKeys / sortKey / sortKeyName	MN	name of sort key to be used in queries
searchInfo / sortKeys / sortKey / sortOrder	ON	indicates that a server supports results sorting in ascending or descending sequence or both and indicates its default behavior
searchInfo / sortKeys / sortKey / caseSensitivity	ON	indicates that a server supports case sensitive or case insensitive results sorting or both and indicates its default behavior
searchInfo / sortKeys / sortKey / missingValue	ON	indicates the default applied by the server if the data being sorted lacks the necessary data element

searchInfo / inputEncoding	OR	indicates the character encoding conventions accepted by the server for Unicode characters beyond U+007F that are not valid in a URI.
recordInfo	MN	indicates the types of records used by a server to deliver results (Either recordInfo or schemaInfo must be present. For SRU generally, schemaInfo is used)
recordInfo / recordSyntax	MR	indicates the record structure supported by a server
recordInfo / elementSet	MR	indicates the content schemas for a record structure supported by a server
recordInfo / recordXMLEscaping	ON	Indicates whether ‘string’ or ‘xml’ or both is or are supported
recordInfo / recordXMLEscaping / delivers	MR	List of escapes supported. String and XML are reserved definitions
recordInfo / recordPacking	ON	Indicates whether ‘packed’ or ‘unpacked’ or both is or are supported
recordInfo / recordPacking / delivers	MR	List of packing supported. Packed is a reserved definition

schemaInfo	MN	indicates the defined schemas used by a server to deliver and / or to sort results (Either recordInfo or schemaInfo must be present. For SRU generally, schemaInfo is used)
schemaInfo / schema	MR	information on the schemas employed for sorting and presenting data from the database
attr: identifier	MN	identifier of this schema
attr: name	MN	name of this schema
attr: location	ON	URL linking to a copy of this schema
attr: sort	ON	indicates that this schema may be used for sorting: default is false
attr: retrieve	ON	indicates that records may be retrieved from the database using this schema: default is true
schemaInfo / schema / title	MR	name of the schema with an indication of language
attr: primary	ON	indicates the default text that should be provided if language is not specified
attr: lang	ON	2 letter code from RFC 1766 indicating the language of the text
stylesheet	ON	information on the support of stylesheets by a server
stylesheet / echoInResponse	MN	indication that the server will supply a stylesheet reference in the response for the client to do the rendering upon request
stylesheet / serverRendering	ON	indication that the server will apply a stylesheet to a result set prior to sending
stylesheet / serverRendering / stylesheet name	MR	sequence of URLs pointing to the stylesheets supported for server rendering
extensions	OR	list of URLs of extensions supported which are returned in extraRecordData and extraResponseData only if requested in extraSearchData
How to interpret a response
configInfo	OR	includes server defaults, fixed settings and supported elements
configInfo / default /	MN	indicates that if an element is not given in a search, the server will apply this default value
configInfo / supports	MN	indicates that only one setting for an element is possible
configInfo / setting	MN	indicates that the server supports an element
responseFormats	OR	list of response formats supported, e.g. sru+xml, rss+xml, atom+xml (httpAccept parameter in request)
responseFormats / responseFormat / nameString	MN	name identifier used in a request to indicate the response format
responseFormats / responseFormat / URI	MN	URI identifying response format's definition
responseFormats / responseFormat / URL	ON	URL for a locaion where the response format's definition may be found
responseFormats / responseFormat / mediaType	OR	media types for which this response format is valid
diagnosticSets	OR	indicates support for diagnostic sets other than SRU
diagnosticSets / diagnosticSet / setName	MN	name of diagnostic set
diagnosticSets / diagnosticSet / URI	MN	URI identifying diagnostic set's definition
diagnosticSets / diagnosticSet / URL	ON	URL for a locaion where the diagnostic set's definition may be found

4 Conformance

The Explain document MUST contain a <serverInfo> element with <host>, <port> and <database> subelements. An HTTP URL constructed from the <host>, <port> and <database> elements MUST provide a sufficient base URL from which Explain and SearchRetrieve URLs can be built.

Appendix A. Acknowledgements

Acknowlegements are supplied in the Overview document:

searchRetrieve: Part 0. Overview Version 1.0

http://docs.oasis-open.org/search-ws/searchRetrieve/v1.0/csd01/part0-overview/searchRetrieve-v1.0-csd01-part0-overview.doc

Appendix B. Comparison of Explain and ZEEREX (Non Normative)

The following table presents a comparison of the Explain elements and attributes with those of ZEEREX.

Explain Element/Attribute	Corresponding ZEEREX Element/Attribute	Note
explain	explain
attr: ‘authoritative’	attr: ‘authoritative’
attr: ‘id’	attr: ‘id’
serverInfo	serverInfo
attr: ‘protocol’	attr: ‘protocol’
attr: ‘version’	attr: ‘version’
attr: ‘transport’	attr: ‘transport’
attr: ‘wsdl’	attr: ‘wsdl’
serverInfo / host	serverInfo / host
serverInfo / port	serverInfo / port
serverInfo / database	serverInfo / database
attr: ‘numRecs	attr: ‘numRecords’
attr: ‘lastUpdate’	attr: ‘lastUpdate’
serverInfo / authentication	serverInfo / authentication
attr: ‘required’	attr: ‘required’
serverInfo / authentication / open	serverInfo / authentication / open
serverInfo / authentication / [string] user group password	serverInfo / authentication / [string] user group password

databaseInfo	databaseInfo
attr: primary	attr: primary
attr: lang	attr: lang
databaseInfo / title	databaseInfo / title
databaseInfo / description	databaseInfo / description
databaseInfo / author	databaseInfo / author
databaseInfo / contact	databaseInfo / contact
databaseInfo / extent	databaseInfo / extent
databaseInfo / history	databaseInfo / history
databaseInfo / langUsage	databaseInfo / langUsage
databaseInfo / restrictions	databaseInfo / restrictions
databaseInfo / subjects	databaseInfo / subjects
databaseInfo / links	databaseInfo / links
databaseInfo / implementation	databaseInfo / implementation
metaInfo	metaInfo
metaInfo / dateModified	metaInfo / dateModified
metaInfo / aggregatedFrom	metaInfo / aggregatedFrom
metaInfo / dateAggregated	metaInfo / dateAggregated	Zeerex data type is string and not date/time
indexInfo	indexInfo
indexInfo / set	indexInfo / set
attr: name	attr: name
attr: identifier	attr: URI
indexInfo / set / title	indexInfo / set / title
attr: primary	attr: primary
attr: lang	attr: lang
indexInfo / index	indexInfo / index
attr: id	attr: id
attr: search	attr: search
attr: scan	attr: scan
attr: sort	attr: sort
indexInfo / index / title	indexInfo / index / title
attr: primary	attr: primary
attr: lang	attr: lang
indexInfo / index / map	indexInfo / index / map
indexInfo / index / configInfo	indexInfo / index / configInfo
indexInfo / index / configInfo	indexInfo / index / configInfo
indexInfo / index / configInfo / default /	indexInfo / index / configInfo / default
indexInfo / index / configInfo / supports	indexInfo / index / configInfo / supports
indexInfo / index / configInfo / setting	indexInfo / index / configInfo / setting
indexInfo / sortKeyword	indexInfo / sortKeyword
searchInfo	New, no corresponding Zeerex element/attribute
searchInfo / queryExample	New, no corresponding Zeerex element/attribute
searchInfo / queryType	New, no corresponding Zeerex element/attribute
searchInfo / queryType / name	New, no corresponding Zeerex element/attribute
searchInfo / queryType / URI	New, no corresponding Zeerex element/attribute
searchInfo / queryType / URL	New, no corresponding Zeerex element/attribute
searchInfo / queryType / supportLevel	New, no corresponding Zeerex element/attribute
searchInfo / queryType / queryTemplate	New, no corresponding Zeerex element/attribute
searchInfo / queryType / otherInformation	New, no corresponding Zeerex element/attribute
	New, no corresponding Zeerex element/attribute
searchInfo / facets	New, no corresponding Zeerex element/attribute
searchInfo / facets / facet	New, no corresponding Zeerex element/attribute
searchInfo / facets / facet / facetType	New, no corresponding Zeerex element/attribute
searchInfo / facets / facet / facetDescription	New, no corresponding Zeerex element/attribute
searchInfo / facets / facet / limit	New, no corresponding Zeerex element/attribute
searchInfo / facets / facet / limit / limitDefault	New, no corresponding Zeerex element/attribute
searchInfo / facets / facet / limit / otherLimit	New, no corresponding Zeerex element/attribute
searchInfo / facets / facet / start	New, no corresponding Zeerex element/attribute
searchInfo / facets / facet /start / startDefault	New, no corresponding Zeerex element/attribute
searchInfo / facets / facet / start / otherStart	New, no corresponding Zeerex element/attribute
searchInfo / facets / facet / sort	New, no corresponding Zeerex element/attribute
searchInfo / facets / facet / sort / sortBy	New, no corresponding Zeerex element/attribute
searchInfo / facets / facet / sort / sortOrder	New, no corresponding Zeerex element/attribute
searchInfo / facets / facet / sort / caseSensitivity	New, no corresponding Zeerex element/attribute
	New, no corresponding Zeerex element/attribute
searchInfo / sortKeys	New, no corresponding Zeerex element/attribute
searchInfo / sortKeys / sortKey	New, no corresponding Zeerex element/attribute
searchInfo / sortKeys / sortKey / sortKeyName	New, no corresponding Zeerex element/attribute
searchInfo / sortKeys / sortKey / sortOrder	New, no corresponding Zeerex element/attribute
searchInfo / sortKeys / sortKey / caseSensitivity	New, no corresponding Zeerex element/attribute
searchInfo / sortKeys / sortKey / missingValue	New, no corresponding Zeerex element/attribute
	New, no corresponding Zeerex element/attribute
searchInfo / inputEncoding	New, no corresponding Zeerex element/attribute
	New, no corresponding Zeerex element/attribute
recordInfo	recordInfo
recordInfo / recordSyntax	recordInfo / recordSyntax
recordInfo / elementSet	recordInfo / elementSet
recordInfo / recordXMLEscaping	New, no corresponding Zeerex element/attribute
recordInfo / recordXMLEscaping / delivers	New, no corresponding Zeerex element/attribute
recordInfo / recordPacking	New, no corresponding Zeerex element/attribute
recordInfo / recordPacking / delivers	New, no corresponding Zeerex element/attribute
schemaInfo	schemaInfo
schemaInfo / schema	schemaInfo / schema
attr: identifier	attr: identifier
attr: name	attr: name
attr: location	attr: location
attr: sort	attr: sort
attr: retrieve	attr: retrieve
schemaInfo / schema / title	schemaInfo / schema / title
attr: primary	attr: primary
attr: lang	attr: lang
stylesheet	New, no corresponding Zeerex element/attribute
stylesheet / echoInResponse	New, no corresponding Zeerex element/attribute
stylesheet / serverRendering	New, no corresponding Zeerex element/attribute
stylesheet / serverRendering / stylesheet name	New, no corresponding Zeerex element/attribute
extensions	New, no corresponding Zeerex element/attribute
configInfo	configInfo
configInfo / default /	configInfo / default
configInfo / supports	configInfo / supports
configInfo / setting	configInfo / setting
responseFormats	New, no corresponding Zeerex element/attribute
responseFormats / responseFormat / nameString	New, no corresponding Zeerex element/attribute
responseFormats / responseFormat / URI	New, no corresponding Zeerex element/attribute
responseFormats / responseFormat / URL	New, no corresponding Zeerex element/attribute
responseFormats / responseFormat / mediaType	New, no corresponding Zeerex element/attribute
diagnosticSets	New, no corresponding Zeerex element/attribute
diagnosticSets / diagnosticSet / setName	New, no corresponding Zeerex element/attribute
diagnosticSets / diagnosticSet / URI	New, no corresponding Zeerex element/attribute
diagnosticSets / diagnosticSet / URL	New, no corresponding Zeerex element/attribute