OAI-PMH Implementation Guidelines - Conveying rights expressions about metadata in the OAI-PMH framework

Editors

Carl Lagoze (OAI Executive; Cornell University - Computer Science)
Herbert Van de Sompel (OAI Executive; Los Alamos National Laboratory - Research Library)
Michael Nelson (Old Dominion University - Computer Science)
Simeon Warner (Cornell University - Computer Science)

This document is one part of the Implementation Guidelines that accompany the Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH).

1. Introduction and Scope
2. Rights expressions and the OAI-PMH data model
3. Conveying rights expressions at the record level
4. Conveying a manifest of rights expressions at the repository and set levels
4.1 Repository level rights expressions
4.2 Set level rights expressions
5. Responsibilities of clients harvesting metadata with associated rights expressions
Acknowledgements

1. Introduction and Scope

The Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH) provides a mechanism for data providers to expose metadata for harvesting over the Web. This metadata is disseminated in the form of OAI-PMH records. Metadata harvested from one or more data providers using the OAI-PMH can be used by service providers for the creation of services (e.g. search, browse) across the harvested data.

Typically, an OAI-PMH record contains descriptive metadata about a resource. However, use-cases have emerged where records contain non-bibliographic metadata such as usage logs and XML-based representations of content. In order to accommodate such emerging uses of the OAI-PMH, in the remainder of this document the term "metadata" must be interpreted broadly to mean XML-formatted data pertaining to a resource, which are transmitted in OAI-PMH as the contents of the <metadata> element in OAI-PMH GetRecord and ListRecords responses.

Regardless of the nature of the metadata in an OAI-PMH record, data providers might want to associate rights expressions with it as a means to convey how the metadata may be used after it has been harvested, including how it may be shared, modified, and used as the basis for derivative products. This specification defines how such rights information can be conveyed in responses to OAI-PMH protocol requests. The described technique:

Is based on delivering rights expressions that apply to metadata contained in OAI-PMH protocol responses using the optional containers that have been defined as part of the OAI-PMH specification. As a result, no changes to the protocol are made, and compatibility with all existing OAI-PMH implementations is maintained.
Is not tied to any particular rights expression language. Examples throughout this document make use of Creative Commons licenses, but the use of this specific language is for illustrative purposes only.

In this document the key words "must", "must not", " required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional " in bold face are to be interpreted as described in RFC 2119. An implementation is not conformant if it fails to satisfy one or more of the "must" or "required" level requirements.

2. Rights expressions and the OAI-PMH data model

The OAI-PMH data model defines a number of entities, some of which aggregate other entities. These entities are as follows and are illustrated in the figure below:

repository - A network accessible server that can process the six OAI-PMH requests, and thereby makes metadata harvestable.
resource - An object that the harvestable metadata is "about".
item - An abstract constituent of a repository from which metadata, potentially in multiple formats, about a resource can be harvested using the OAI-PMH.
record - A container for metadata in a single format returned in response to an OAI-PMH harvesting request. A record consists of header information, the metadata, and may include addition information about the metadata.
set - A grouping of items for the purpose of selective harvesting. Set membership for items is not required: an item may be in no sets. Set membership is also non-exclusive: an item may be in more than one set.

OAI-PMH data model figure

This document specifies the mechanisms by which rights expressions can be conveyed at the record level (section 3), and at the repository and set aggregation levels (section 4). These mechanisms can be summarized as follows:

record level - Metadata returned in OAI-PMH ListRecords and GetRecords responses is packaged in <record> elements. Each <record> may include one or more <about> containers that provide information about the metadata. A rights expression can be associated with the metadata by including a <rights> package in an <about> container. This specification defines an XML schema to which such <rights> packages must conform. The schema allows for actual rights expressions to be specified in-line within a <rights> package, or by-reference via a URL to a network-accessible rights expression.
repository level - The response to the OAI-PMH Identify request contains information about the repository. This response may include one or more <description> containers which provide an extensible mechanism for repository description. This specification defines an optional mechanism for delivering, within the <description> container, a manifest of the rights expressions used in the repository . The purpose of this manifest is to provide a convenient way for harvesters to determine the rights expressions associated with records disseminated by a repository. This specification defines an XML schema to which the rights manifest packages must conform.
set level - The response to the OAI-PMH ListSets request contains information about the set structure of the repository. Sets are a mechanism to provide selective harvesting from a repository. This response may include one or more <setDescription> containers which provide an extensible mechanism for set description. This specification defines an optional mechanism for delivering, within the <setDescription> container, a manifest of the rights expressions associated with records disseminated by harvesting requests with a set selection. The purpose of this manifest is to provide a convenient way for harvesters to determine the rights expressions associated with records delivered by a particular set selection. This specification defines an XML schema to which the rights manifest packages must conform.

Repositories may associate different rights expressions with records in different metedata formats from the same item. Manifests should include rights expressions for all records from the items in the appropriate repository or set. (CARL: I just don't like this paragraph. It is unnecessary and confusing information that is implicit in the nature of a record, which is metadata in a specific format. Also, by strarting to talk about metadata formats at this point we mess up the generality of metadata/content that we set up at the beginning of the specification).

The specification in this document provides a generic method for delivery of rights expressions about metadata in OAI-PMH. As such, it should be the mechanism used by data providers desiring such functionality and should be recognized by harvesters that consume metadata delivered by OAI-PMH. Other mechanisms, such as incorporating rights expressions within metadata itself are possible, but should be considered non-generic and hence possibly not recognized by many harvesters.

3. Conveying rights expressions at the record level

The XML schema shown below defines the format for a <rights> package that can be used to include a rights expression within an <about> container as part of a record returned from a ListRecords or GetRecord request. Such a rights expression pertains only to the <metadata> part of the record.

The schema provides two mutually exclusive alternatives for specifying a rights expression:

in-line - The rights expression is contained in XML syntax within the <rightsDefinition> child element of the <rights> element. The XML elements and attributes used in the rights expression must be defined in a namespace distinct from that of the OAI-PMH XML elements and attributes. The schema requires only that the contents of the <rights> element are well-formed XML. However, the contained rights expression may be subject to validation with some external schema.
by-reference - The rights expression is referenced via a URL contained in <rightsReference> child element of the <rights> element. There are no restrictions on the nature of the resource referenced by this URL. However, to facilitate machine processing, the recommended format for referenced rights expressions is XML. Data providers that disseminate records with by-reference rights expressions should be aware of persistence issues related to URL references. Specifically, the possible latency between the dissemination of metadata with a by-reference rights expression and the eventual use of that metadata, and resolution of the reference, may result in a failed reference or even a reference to a changed rights expression with different meaning. Therefore, it is recommended that data providers concerned with truly static rights expressions employ the in-line method.

<?xml version="1.0" encoding="UTF-8"?>
<schema targetNamespace="http://www.openarchives.org/OAI/2.0/rights/" 
        xmlns="http://www.w3.org/2001/XMLSchema" 
        xmlns:rights="http://www.openarchives.org/OAI/2.0/rights/"
        elementFormDefault="qualified"
        attributeFormDefault="unqualified">

  <annotation>
    <documentation>
    Schema for rights statement to be included either by-reference or
    in-line. In-line statements may be in any namespace and are to be
    skipped by XML Schema validators so that rdf and non-W3C schemas
    may be used.
    Carl Lagoze and Simeon Warner (Cornell University)
    $Date: 2004/06/10 03:11:23 $
    </documentation>
  </annotation>
 
  
  <element name="rights" type="rights:rightsStatementType"/>

  <complexType name="rightsStatementType">
    <choice>
      <element name="rightsReference">
        <complexType>
          <attribute name="ref" type="anyURI" use="required"/>
        </complexType>
      </element>
      <element name="rightsDefinition">
        <complexType>
   	  <sequence>
 	    <any namespace="##other" processContents="skip"/>
  	  </sequence>
        </complexType>
      </element>
    </choice>
  </complexType>

</schema>

This schema is available at http://www.openarchives.org/OAI/2.0/rights.xsd

The following example shows the use of a <rights> element to convey an in-line rights expression. The rights expression in this example is the RDF/XML for the Creative Commons license that can be displayed in human-readable form at http://creativecommons.org/licenses/by/2.0/.

<about>
  <rights xmlns="http://www.openarchives.org/OAI/2.0/rights/"  
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/rights/
                        http://www.openarchives.org/OAI/2.0/rights.xsd">
    <rightsDefinition>
      <rdf:RDF xmlns="http://web.resource.org/cc/" 
        xmlns:dc="http://purl.org/dc/elements/1.1/" 
        xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
        <Work rdf:about="">
          <dc:type rdf:resource="http://purl.org/dc/dcmitype/Text"/>
          <license rdf:resource="http://creativecommons.org/licenses/by/2.0/"/>
        </Work>
        <License rdf:about="http://creativecommons.org/licenses/by/2.0/">
          <permits rdf:resource="http://web.resource.org/cc/Reproduction"/>
          <permits rdf:resource="http://web.resource.org/cc/Distribution"/>
          <requires rdf:resource="http://web.resource.org/cc/Notice"/>
          <requires rdf:resource="http://web.resource.org/cc/Attribution"/>
          <permits rdf:resource="http://web.resource.org/cc/DerivativeWorks"/>
        </License>
      </rdf:RDF>
    </rightsDefinition>
  </rights>
</about>

The following example shows the use of a <rights> element to convey a rights expression by-reference.

<about>
  <rights xmlns="http://www.openarchives.org/OAI/2.0/rights/"  
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/rights/
                        http://www.openarchives.org/OAI/2.0/rights.xsd">
    <rightsReference ref="http://creativecommons.org/licenses/by/2.0/"/>
  </rights>
</about>

4. Conveying a manifest of rights expressions at the repository and set levels

Manifests of rights expressions that apply to the repository and set aggregations may be included using the optional <rightsManifest> package. Details of application at the repository level (section 4.1) and the set level (section 4.2) are given separately.

The XML schema below defines the format of the <rightsManifest> package. The schema allows one or more <rights> child elements. The individual <rights> elements are identical to those included at the record level, and must contain a single rights expression either in-line or by-reference. The <rightsManifest> element has a single attribute, appliesTo, which must have the value metadata. This attribute is included as a mechanism for future expansion.

<?xml version="1.0" encoding="UTF-8"?>
<schema targetNamespace="http://www.openarchives.org/OAI/2.0/rights/"
        xmlns="http://www.w3.org/2001/XMLSchema"
        xmlns:xlink="http://www.w3.org/1999/xlink"
        xmlns:rights="http://www.openarchives.org/OAI/2.0/rights/"
        elementFormDefault="qualified"
        attributeFormDefault="unqualified">

  <annotation>
    <documentation>
    Schema for a manifest of rights statements to be included in the
    Identify and ListSets responses of an OAI server. The appliesTo
    attribute permits only the value 'metadata' but is included in
    anticipation of later extension.
    Carl Lagoze and Simeon Warner (Cornell University)
    $Date: 2004/06/10 22:04:54 $
    </documentation>
  </annotation>


  <include schemaLocation="http://www.openarchives.org/OAI/2.0/rights.xsd"/>

  <element name="rightsManifest" type="rights:rightsManifestType"/>

  <complexType name="rightsManifestType">
    <sequence>
      <element name="rights" type="rights:rightsStatementType" maxOccurs="unbounded"/>
    </sequence>
    <attribute name="appliesTo" type="rights:appliesToType"/>
  </complexType>


  <simpleType name="appliesToType">
    <restriction base="string">
      <enumeration value="metadata"/>
    </restriction>
  </simpleType>

</schema>

This schema is available at http://www.openarchives.org/OAI/2.0/rightsManifest.xsd

4.1 Repository level rights expressions

The optional <rightsManifest> package may be included in a <description> container in the response to an Identify request. The purpose of the <rightsManifest> package at the repository level is to provide a list of all the rights expressions that apply to metadata disseminated by the repository.

A typical use of this manifest is the case where all metadata disseminated by the repository is covered by a small set of rights expressions. When this small set of rights expressions is packaged as a manifest within the Identify response, harvesting clients can quickly determine the rights expressions associated with the metadata disseminated by the repository and decide whether to proceed with harvesting. While the completeness and correctness of this manifest is not mandated by this specification, it is highly recommended that data providers maintain its accuracy since its contents may affect decisions by harvesters to collect metadata from the repository.

The following example shows the use of a <rightsManifest> container within a <description> element in an Identify response.

<description>
  <rightsManifest
    xmlns="http://www.openarchives.org/OAI/2.0/rights/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/rights/ 
                        http://www.openarchives.org/OAI/2.0/rightsManifest.xsd"
    appliesTo="metadata">
    <rights>
      <rightsDefinition>
        <rdf:RDF xmlns="http://web.resource.org/cc/" 
          xmlns:dc="http://purl.org/dc/elements/1.1/" 
          xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
          <Work rdf:about="">
            <dc:type rdf:resource="http://purl.org/dc/dcmitype/Text"/>
            <license rdf:resource="http://creativecommons.org/licenses/by/2.0/"/>
          </Work>
          <License rdf:about="http://creativecommons.org/licenses/by/2.0/">
            <permits rdf:resource="http://web.resource.org/cc/Reproduction"/>
            <permits rdf:resource="http://web.resource.org/cc/Distribution"/>
            <requires rdf:resource="http://web.resource.org/cc/Notice"/>
            <requires rdf:resource="http://web.resource.org/cc/Attribution"/>
            <permits rdf:resource="http://web.resource.org/cc/DerivativeWorks"/>
          </License>
        </rdf:RDF>
      </rightsDefinition>
    </rights>
    <rights>
      <rightsDefinition>
        <rdf:RDF xmlns="http://web.resource.org/cc/" 
          xmlns:dc="http://purl.org/dc/elements/1.1/" 
          xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
          <Work rdf:about="">
            <dc:type rdf:resource="http://purl.org/dc/dcmitype/Text"/>
            <license rdf:resource="http://creativecommons.org/licenses/by-nc/2.0/"/>
          </Work>
          <License rdf:about="http://creativecommons.org/licenses/by-nc/2.0/">
            <permits rdf:resource="http://web.resource.org/cc/Reproduction"/>
            <permits rdf:resource="http://web.resource.org/cc/Distribution"/>
            <requires rdf:resource="http://web.resource.org/cc/Notice"/>
            <requires rdf:resource="http://web.resource.org/cc/Attribution"/>
            <prohibits rdf:resource="http://web.resource.org/cc/CommercialUse"/>
            <permits rdf:resource="http://web.resource.org/cc/DerivativeWorks"/>
          </License>
        </rdf:RDF>
      </rightsDefinition>
    </rights>
    <rights>
      <rightsReference ref="http://creativecommons.org/licenses/by-nd/2.0/"/>
    </rights>
  </rightsManifest>
</description>

4.2 Set level rights expressions

Sets are an optional mechanism to support selective harvesting within OAI-PMH. Repositories may or may not implement sets. Some repositories may use sets as a mechanism for allowing selective havesting by rights associated with the metadata (e.g., placing all metadata available "without restriction" in one set and all metadata encumbered in some manner in another set). Set level rights expressions provide a mechanism for associating a rights manifest with particular sets to provide harvesters with information about this use of sets.

The optional <rightsManifest> package may be included in <setDescription> containers in the response to a ListSets request, as a means of conveying rights expressions associated with the set. A data provider may find it appropriate to include manifests for some sets even when it is not feasible or appropriate for the entire repository. Data providers should not include set level rights manifests unless they provide complete, accurate and unambiguous information about rights expressions pertaining to metadata for items within a set.

The following example shows the use of a <rightsManifest> container within a <setDescription> element for one of four sets described in a ListSets response.

<ListSets>
  <set>
    <setSpec>music</setSpec>
    <setName>Music collection</setName>
  </set>
  <set>
    <setSpec>music:(muzak)</setSpec>
    <setName>Muzak collection</setName>
  </set>
  <set>
    <setSpec>music:(elec)</setSpec>
    <setName>Electronic Music Collection</setName>
    <setDescription>
      <rightsManifest 
        xmlns="http://www.openarchives.org/OAI/2.0/rights/" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/rights/ 
                            http://www.openarchives.org/OAI/2.0/rightsManifest.xsd"
        appliesTo="metadata">
        <rights>
          <rightsReference ref="http://creativecommons.org/licenses/by-nd/2.0/"/>
        </rights>
        <rights>
          <rightsReference ref="http://creativecommons.org/licenses/by-nc/2.0/"/>
        </rights>
      </rightsManifest>
    </setDescription>
  </set>
  <set>
    <setSpec>video</setSpec>
    <setName>Video Collection</setName>
  </set>
</ListSets>

5. Responsibilities of clients harvesting metadata with associated rights expressions

This specification aims to provide a canonical mechanism for the inclusion of rights expressions in OAI-PMH records. Harvesters should look for and abide by the contents of any rights expressions included using this mechanism within records they harvest.

The mechanisms described in this document are not intended to provide any level of enforcement of rights expressions. Nevertheless, consumers of metadata with which these rights expressions are associated should act in good faith and abide by the conditions as stated. Actions in response to a failure of a harvester to abide by rights expressions are outside the scope of this specification.

Acknowledgements

Support for the development of the OAI-PMH and for other Open Archives Initiative activities comes from the Digital Library Federation, the Coalition for Networked Information, and from the National Science Foundation through Grant No. IIS-9817416. Individuals who have played a significant role in the development of OAI-PMH version 2.0 are acknowledged in the protocol document.

Document History

2004-05-27: First draft of this document.
2004-06-02: Second draft with substantive changes
2004-06-08: Third draft with substantive changes

Conveying rights expressions about metadata in the OAI-PMH framework

Table of Contents

1. Introduction and Scope