Implementation Guidelines for the Open Archives Initiative Protocol for Metadata Harvesting
OAI logo

Conveying rights expressions about metadata in the OAI-PMH framework

  Protocol Version 2.0 of 2002-06-14
Document Version 2005/05/03T22:55:00Z
http://www.openarchives.org/OAI/2.0/guidelines-rights.htm

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).

Table of Contents

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 harvesters regarding metadata with rights expressions
A1. Appendix: A detailed example
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 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) based on the harvested data.

Data providers might want to associate rights expressions with the metadata to indicate how it may be used, shared, and modified after it has been harvested. This specification defines how rights information pertaining to the metadata should be included in responses to OAI-PMH requests. The described technique:

Metadata in OAI-PMH responses is packaged within the <metadata> element. In most applications of the OAI-PMH, this is descriptive metadata about a resource. However, use-cases have emerged where the <metadata> element contains non-bibliographic metadata such as usage logs and XML-based representations of the resource. This specification details how to convey rights information pertaining to the content of the <metadata> element, irrespective of the use-case.

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:

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:

Repository and set level manifests must not be used as a substitute for the inclusion of rights expressions at the record level. The manifests at the repository and set levels provide a convenient way to expose rights expressions associated with those aggregations. Harvesters must, however, refer to the individual records for authoritative rights expressions about the metadata.

The specification in this document provides a generic method for delivery of rights expressions about metadata in the OAI-PMH framework. 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 about metadata within the 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:

Data providers that disseminate records with by-reference rights expressions should be aware of persistence issues related to URI references. Specifically, in the time between the dissemination of metadata with a by-reference rights expression and the eventual resolution of the reference, the URI for the expression may disappear or have a different meaning. Therefore, data providers concerned with persistent rights expressions should ensure that their by-reference URIs and the rights expressions those URIs resolve to are persistent, or employ the in-line method.

Data providers must not include multiple <rights> packages in a single OAI-PMH record. However, multiple <about> containers may be present in a single record to included different packages (perhaps a <rights> package and a <provenance> package; see Appendix A1 for an example). Each individual <about> container must have exactly one child element.

<?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 
    subject to "strict" validation, meaning that an XML schema must be 
    available to validate them.
    Carl Lagoze and Simeon Warner (Cornell University)
    $Date: 2005/04/27 15:37:43 $
    </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="strict"/>
  	  </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 GNU Free Documentation License available at http://www.gnu.org/licenses/fdl.txt. There is no machine readable for of this license so instead a Dublin Core record is used to describe it.

<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>
      <oai_dc:dc xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/"
        xmlns:dc="http://purl.org/dc/elements/1.1/"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai_dc/
                            http://www.openarchives.org/OAI/2.0/oai_dc.xsd">
        <dc:title>GNU Free Documentation License, Version 1.2</dc:title>
        <dc:date>2002-11</dc:date>
        <dc:creator>Free Software Foundation, Inc.</dc:creator>
        <dc:description>Copyright (c) 2005 Fred Bloggs.
          Permission is granted to copy, distribute and/or modify this document
          under the terms of the GNU Free Documentation License, Version 1.2
          or any later version published by the Free Software Foundation;
          with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
          Texts.</dc:description>
        <dc:identifier>http://www.gnu.org/licenses/fdl.txt</dc:identifier>
      </oai_dc:dc>
    </rightsDefinition>
  </rights>
</about>

The following example shows the use of a <rights> element to convey a rights expression by-reference. The URI http://creativecommons.org/licenses/by-nd/2.0/rdf refers to the XML/RDF version of the Creative Commons license that can be displayed in human-readable form at http://creativecommons.org/licenses/by-nd/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">
    <rightsReference ref="http://creativecommons.org/licenses/by-nd/2.0/rdf"/>
  </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. The purpose of these manifests is to provide a convenient way for harvesters to determine the rights expressions associated with metadata available from the repository and set aggregations respectively. Details of application at the repository level (section 4.1) and the set level (section 4.2) are given separately. Repository and set level manifests must not be used as a substitute for the inclusion of rights expressions at the record level. Harvesters must refer to the individual records for authoritative rights expressions. Even if repository or set level manifests are present, the rights pertaining to the <metadata> portion of a record remain unknown unless a <rights> package is included in an <about> container in that record.

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 mandatory attribute, appliesTo, which must have the value http://www.openarchives.org/OAI/2.0/entity#metadata. This attribute is included as a mechanism for future expansion. Harvesters must not assume that the same rights expression applies to all metadata formats from an item; or that particular rights expressions in a <rightsManifest> apply to particular metadata formats.

<?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 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 
    'http://www.openarchives.org/OAI/2.0/entity#metadata' but is 
    included in anticipation of later extension.
    Carl Lagoze and Simeon Warner (Cornell University)
    $Date: 2004/11/05 15:52:02 $
    </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="anyURI">
      <enumeration value="http://www.openarchives.org/OAI/2.0/entity#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. The completeness and correctness of this manifest is not mandated by this specification due to lack of a practical enforcement mechanism. However, it is highly recommended that data providers maintain accurate manifests since their 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. The example uses the two rights statements used in section 3.

<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="http://www.openarchives.org/OAI/2.0/entity#metadata">
    <rights>
      <rightsDefinition>
        <oai_dc:dc xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/"
          xmlns:dc="http://purl.org/dc/elements/1.1/"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai_dc/
                              http://www.openarchives.org/OAI/2.0/oai_dc.xsd">
          <dc:title>GNU Free Documentation License, Version 1.2</dc:title>
          <dc:date>2002-11</dc:date>
          <dc:creator>Free Software Foundation, Inc.</dc:creator>
          <dc:description>Copyright (c) 2005 Fred Bloggs.
            Permission is granted to copy, distribute and/or modify this document
            under the terms of the GNU Free Documentation License, Version 1.2
            or any later version published by the Free Software Foundation;
            with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
            Texts.</dc:description>
          <dc:identifier>http://www.gnu.org/licenses/fdl.txt</dc:identifier>
        </oai_dc:dc>
      </rightsDefinition>
    </rights>
    <rights>
      <rightsReference ref="http://creativecommons.org/licenses/by-nd/2.0/rdf"/>
    </rights>
  </rightsManifest>
</description>

4.2 Set level rights expressions

Sets are an optional mechanism to support selective harvesting within the OAI-PMH. Some repositories may use sets as a mechanism for partitioning the repository to permit selective harvesting based on 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). Repositories may or may not implement sets. Set level rights expressions provide a mechanism for associating rights manifests with particular sets to provide harvesters with information about the rights expressions associated with metadata available from items in the set.

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 metadata from items in 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 from items in a set.

The following example shows the use of <rightsManifest> containers within <setDescription> elements for two of four sets described in a ListSets response. The response indicates that metadata from items in the music:(elec) set have either of two Creative Commons licenses as associated rights expressions, and that metadata from items in the music:(history) set has rights expressed by the GNU Free Documentation License.

<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="http://www.openarchives.org/OAI/2.0/entity#metadata">
        <rights>
          <rightsReference ref="http://creativecommons.org/licenses/by-nd/2.0/rdf"/>
        </rights>
        <rights>
          <rightsReference ref="http://creativecommons.org/licenses/by-nc/2.0/rdf"/>
        </rights>
      </rightsManifest>
    </setDescription>
  </set>
  <set>
    <setSpec>music:(history)</setSpec>
    <setName>Music History Documentation Project</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="http://www.openarchives.org/OAI/2.0/entity#metadata">
        <rights>
          <rightsDefinition>
            <oai_dc:dc xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/"
              xmlns:dc="http://purl.org/dc/elements/1.1/"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai_dc/
                                  http://www.openarchives.org/OAI/2.0/oai_dc.xsd">
              <dc:title>GNU Free Documentation License, Version 1.2</dc:title>
              <dc:date>2002-11</dc:date>
              <dc:creator>Free Software Foundation, Inc.</dc:creator>
              <dc:description>Copyright (c) 2005 Music History Documentation Project.
                Permission is granted to copy, distribute and/or modify this document
                under the terms of the GNU Free Documentation License, Version 1.2
                or any later version published by the Free Software Foundation;
                with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
                Texts.</dc:description>
             <dc:identifier>http://www.gnu.org/licenses/fdl.txt</dc:identifier>
           </oai_dc:dc>
         </rightsDefinition>
        </rights>
      </rightsManifest>
    </setDescription>
  </set>
</ListSets>

5. Responsibilities of harvesters regarding metadata with rights expressions

This specification aims to provide a canonical mechanism for the inclusion of rights expressions about metadata 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, clients should act in good faith and abide by the rights expressions about the metadata they harvest. Actions in response to a failure of a harvester to abide by rights expressions are outside the scope of this specification.

A1. Appendix: A detailed example

The following example shows the complete response to a GetRecord request, which includes a <rights> package. The <rights> package contains a by-reference rights expression that provides a reference to a description of rights associated with the <metadata> part of the record. Also included, in a separate <about> container, is a <provenance> package that provides provenance information for the <metadata> part of the record. Neither of these <about> containers say anything about the resource described by the <metadata> part of the record.

The <metadata> part of the record contains metadata expressed in unqualified Dublin Core format (using the oai_dc metadataPrefix and associated schema). This includes a dc:rights element which, according to the semantics of Dublin Core, expresses rights information about the resource. This element says nothing about rights associated with the metadata. In this particular example, the dc:rights element references another Creative Commons license, one that is more restrictive than the license associated with the metadata.

<?xml version="1.0" encoding="UTF-8"?> 
<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/
         http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
  <responseDate>2002-02-08T08:55:46Z</responseDate>
  <request verb="GetRecord" identifier="oai:arXiv.org:cs/0112017"
           metadataPrefix="oai_dc">http://arXiv.org/oai2</request>
  <GetRecord>
    <record> 

      <header>
        <identifier>oai:an.oa.org:zxy123</identifier> 
        <datestamp>2004-08-08</datestamp>
      </header>

      <metadata>
        <oai_dc:dc 
         xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/" 
         xmlns:dc="http://purl.org/dc/elements/1.1/" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai_dc/ 
         http://www.openarchives.org/OAI/2.0/oai_dc.xsd">
          <dc:title>Using elephants to crack peanuts in a factory setting</dc:title> 
          <dc:creator>Nutcase, A</dc:creator>
          <dc:subject>Elephants</dc:subject> 
          <dc:description>With the increasing technical sophistication of 
            well-trained elephants it is becoming practical to consider
            their use in factory settings.</dc:description> 

          <!-- dc:rights, IF USED, REFERS TO RIGHTS ABOUT THE RESOURCE --> 
          <dc:rights>http://creativecommons.org/licenses/by-nc-sa/2.0/</dc:rights>

          <dc:date>2004-04-01</dc:date>
        </oai_dc:dc>
      </metadata>

      <about>  

        <!-- RIGHTS INFORMATION FOR metadata ABOVE -->
        <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-nd/2.0/rdf"/>
        </rights>
      </about>

      <about>  

        <!-- PROVENANCE INFORMATION FOR metadata ABOVE -->
        <provenance xmlns="http://www.openarchives.org/OAI/2.0/provenance"
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/provenance
                                        http://www.openarchives.org/OAI/2.0/provenance.xsd">
          <originDescription harvestDate="2004-08-08T14:10:02Z" altered="false">
            <baseURL>http://the.oa.org</baseURL>
            <identifier>oai:the.oa.org:abc987</identifier>
            <datestamp>2004-04-01</datestamp>
            <metadataNamespace>http://www.openarchives.org/OAI/2.0/oai_dc/</metadataNamespace>
          </originDescription>
        </provenance>
      </about>

    </record>
  </GetRecord>
</OAI-PMH>

Acknowledgements

Support for the development of the OAI-PMH and for other Open Archives Initiative activities has come from a number of sources including the National Science Foundation, the Digital Library Federation, and the Coalition for Networked Information.

The development of these guidelines was inspired, in part, by the work of the RoMEO project. Individuals who have played a significant role in the development of these guideline are: Caroline Arms (Library of Congress), Chris Barlas (Rightscom), Tim Cole (University of Illinois at Urbana-Champaign), Mark Doyle (American Physical Society), Henk Ellerman (Erasmus Electronic Publishing Initiative), John Erickson (Hewlett Packard & DSpace), Elizabeth Gadd (Loughborough University & RoMEO), Brian Green (EDItEUR), Chris Gutteridge (Southampton University & eprints.org), Carl Lagoze (Cornell University & OAI), Mike Linksvayer (Creative Commons), Uwe Müller (Humboldt University), Michael Nelson (Old Dominion University & OAI), John Ober (California Digital Library), Charles Oppenheim (Loughborough University & RoMEO), Sandy Payette (Cornell University), Andy Powell (UKOLN, University of Bath), Steve Proberts (Loughborough University & RoMEO), Herbert Van de Sompel (Los Alamos National Laboratory & OAI), and Simeon Warner (Cornell University, arXiv & OAI).

Document History

2005-05-03: Release of this document.
2004-05-27: First draft of this document.

Creative Commons License
This work is licensed under a Creative Commons License.