Main Principles

The OpenEdition repository follows the version 2.0 of the OAI-PMH protocol available on the Open Archives Initiative website: http://www.openarchives.org/OAI/openarchivesprotocol.html

Note

What’s new in this version?

Migration steps from v1 to v2

  • june-october 2024: OpenEdition OAI-PMH v2 is tested by partners.

  • november 2024: v2.0 is released and usable in production environment. v1 is declared Deprecated.

  • november 2024-june 2025: v1 and v2 continue to run in parallel, while harvesters upgrade to version 2.

  • june 2025: v1 is removed.

OpenEdition Identifiers

Handle and DOI

  • OpenEdition uses 2 PID system (Handle and DOI) for the documents published on the 4 platforms:

  • The Handle system covers 100% of the documents

  • The DOI system covers 100% of documents for Hypotheses and Calenda and around 90% for OpenEdition Books and Journals

  • Since the OAI-PMH protocol needs identifiers for all records, the OAI-PMH identifier system is Handle.

Retrieving Handle, DOI and URL

Handle, DOI and URL and other metadata can be retrieved from the metadata service witch return metadata (format CSL-data.json) on each document from:

  • Handle: https://metadata.openedition.org/handle/[HANDLE]?format=json

  • DOI: https://metadata.openedition.org/doi/[DOI]?format=json

  • Content Id: https://metadata.openedition.org/contentid/[CONTENTID]?format=json

Journal article example: https://journals.openedition.org/rdr/1789

  • Retrieving metadata:

Handle

https://metadata.openedition.org/handle/20.500.13089/jlrc?format=json

DOI

https://metadata.openedition.org/doi/10.4000/rdr.1789?format=json

Content ID

https://metadata.openedition.org/contentid/OJ.rdr.1789?format=json

  • Several Citation format for each document (argument format (default="mla")):

CSL-data.json

https://metadata.openedition.org/handle/20.500.13089/jlrc?format=json

Text MLA

https://metadata.openedition.org/handle/20.500.13089/jlrc?format=mla

Text APA

https://metadata.openedition.org/handle/20.500.13089/jlrc?format=apa

Text Chicago

https://metadata.openedition.org/handle/20.500.13089/jlrc?format=chicago

  • Content ID can be deduced from the url and conversely:

Platform

URL

ContentId

OpenEdition Journals

https://journals.openedition.org/rdr/1789

OJ.rdr.1789

OpenEdition Books

https://books.openedition.org/momeditions/18666

OB.momeditions.18666

Hypotheses

https://sms.hypotheses.org/43068

HO.sms.43068

Calenda

https://calenda.org/1170768

CO.calendaorg.1170768

More information about CSL format:

OAI-PMH Identifiers

Example:

https://metadata.openedition.org/oai?verb=GetRecord&identifier=20.500.13089/k1x3&metadataPrefix=oai_dc returns:

1<?xml version="1.0" encoding="UTF-8"?>
2<record>
3  <header>
4    <identifier>20.500.13089/k1x3</identifier>
5    <datestamp>2019-05-21T16:57:47Z</datestamp>
6    <setSpec>journals</setSpec>
7    <setSpec>journals:rfp</setSpec>
8  </header>

The resource is available at https://hdl.handle.net/20.500.13089/k1x3

Deleted Records

The repository supports the notion of deleted records. Deleted records are persistent, meaning the information is still availaible over time in the repository.

Example: https://metadata.openedition.org/oai?verb=ListRecords&set=journals:ges&metadataPrefix=oai_dc

 1<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">
 2  <responseDate>2024-06-10T06:24:24Z</responseDate>
 3  <request verb="ListRecords" set="journals:ges" metadataPrefix="oai_dc" cursor="0">https://metadata.openedition.org/oai</request>
 4  <ListRecords>
 5    <record>
 6      [...]
 7    </record>
 8    <record>
 9      <header status="deleted">
10        <identifier>20.500.13089/vmnb</identifier>
11        <datestamp>2024-01-19T12:06:50Z</datestamp>
12        <setSpec>journals</setSpec>
13        <setSpec>journals:ges</setSpec>
14      </header>
15    </record>

Note that Handles of deleted records still resolve to a landing page with metadata of the deleted resource. Example: https://hdl.handle.net/20.500.13089/vmnb

More information on deleted records at OAI-PMH website: https://www.openarchives.org/OAI/openarchivesprotocol.html#DeletedRecords

Selective Harvesting

The repository allows selective harvesting, by set and by date.

Selective harvesting by set

More info about available sets: Sets description

Selective harvesting by date

The repository allows harvesting by date, i.e. harvesting of records added or updated before or after a specified date

The parameters to use are from and until. Allowed date formats are dd-mm-yyyy and dd-mm-yyyyThh:mm:ssZ.

Example

https://metadata.openedition.org/oai/?verb=ListRecords&metadataPrefix=oai_dc&from=2017-03-13T16:47:48Z will retrieve a list of records added or updated since the 13 march 2017 at 4.47 pm.

resumptionToken

The repository uses the resumptionToken system. Therefore, it is not possible to retrieve all documents with a single ListRecords, ListIdentifiers or ListSets request.

For instance, for retrieving the metadata of all documents from the journal Revista Crítica de Ciências Sociais, you will use the query:

https://metadata.openedition.org/oai/?verb=ListRecords&set=journals:rccs&metadataPrefix=oai_dc

The repository will return a list of the first 100 documents + a resumptionToken element at the end of the response.

 1<?xml version="1.0" encoding="UTF-8"?>
 2<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">
 3  <responseDate>2024-06-09T19:39:32Z</responseDate>
 4  <request verb="ListRecords" set="journals:rccs" metadataPrefix="oai_dc" cursor="0">https://metadata.openedition.org/oai</request>
 5  <ListRecords>
 6    <record>
 7      [...]
 8    </record>
 9    <record>
10      [...]
11    </record>
12    [...]
13
14    <resumptionToken cursor="0" completeListSize="1075">set%3Djournals%3Arccs%26metadataPrefix%3Doai_dc%26cursor%3D100%26cursorMark%3DAoErT0oucmNjcy44NjI%3D</resumptionToken>
15  </ListRecords>

For retrieving the next 10 documents, you will pass the content of the resumptionToken element as an argument of a new URL request:

https://metadata.openedition.org/oai?verb=ListRecords&resumptionToken=set%3Djournals%3Arccs%26metadataPrefix%3Doai_dc%26cursor%3D100%26cursorMark%3DAoErT0oucmNjcy44NjI%3D and so on.

The OAI-PMH documentation available at http://www.openarchives.org/OAI/openarchivesprotocol.html gives a more detailed insight of the resumptionToken parameter.