Open Archives Initiative Protocol (OAI-PMH) Verification in OJS
Detailed technical guide to testing and validating the OAI-PMH endpoint in OJS. Covers standard OAI verbs, XML schema validation, and resolving harvesting bugs.
Real Problem
Many journals discover that university library networks cannot harvest their content because unescaped XML characters or misconfigured base URLs break the OAI-PMH endpoint.
Practical Solution
Verify and troubleshoot your OJS OAI-PMH endpoint: audit standard verbs (Identify, ListRecords, ListIdentifiers), sanitize XML encoding bugs, and register with international repositories.
The Global Library Harvesting Standard
The Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH) is an international standard protocol for repository interoperability. It allows library discovery platforms (such as WorldCat, BASE, Primo, and EBSCO) to automatically query and ingest your journal’s bibliographic records.
If your OAI-PMH endpoint is broken, your journal is effectively invisible to institutional library search systems.
The Core OAI-PMH Verbs
An OAI-PMH endpoint must support six standard request verbs:
1. Identify
Retrieves general repository information:
https://journal.institution.edu/oai?verb=Identify
Expected output: XML containing <repositoryName>, <baseURL>, <protocolVersion>2.0</protocolVersion>, and <adminEmail>.
2. ListMetadataFormats
Shows supported metadata formats:
https://journal.institution.edu/oai?verb=ListMetadataFormats
Mandatory format: oai_dc (Dublin Core).
Optional formats: marcxml, rfc1807, oai_etdms.
3. ListSets
Retrieves the journal sections or discipline categories:
https://journal.institution.edu/oai?verb=ListSets
4. ListIdentifiers
Lists unique record identifiers and datestamps:
https://journal.institution.edu/oai?verb=ListIdentifiers&metadataPrefix=oai_dc
5. ListRecords
Harvests full bibliographic records:
https://journal.institution.edu/oai?verb=ListRecords&metadataPrefix=oai_dc
6. GetRecord
Retrieves metadata for a solitary specific submission:
https://journal.institution.edu/oai?verb=GetRecord&identifier=oai:journal.institution.edu:article/123&metadataPrefix=oai_dc
Common OAI-PMH Errors and Fixes
Error 1: XML Syntax Error (Unescaped Characters)
Symptom: Browser displays "XML Parsing Error: not well-formed" on ListRecords.
Cause: An author pasted an abstract containing an unescaped ampersand (e.g., "AT&T" or "R&D") or invalid ASCII control characters (0x00 - 0x1F).
Fix: Ensure OJS database and connection encoding are set to utf8mb4 and that XML output functions pass strings through htmlspecialchars($string, ENT_XML1, 'UTF-8').
Error 2: Resumption Token Timeouts
Symptom: Large harvesters fail midway through harvesting 5,000 articles.
Cause: OJS generates a resumptionToken for pagination. If the harvester delays between requests, the temporary token expires in the database.
Fix: In config.inc.php, adjust [oai] oai_max_records = 100 to increase batch size, or optimize MySQL query performance for oai_resumption_tokens table.
Validation and Registration
Verify your endpoint using the official Open Archives Initiative protocol validator at openarchives.org. Once validated with zero warnings, submit your journal URL to international harvesters including BASE (Bielefeld) and WorldCat.
Step-by-Step Action Plan
Locate OAI-PMH Base Endpoint
Identify your journal’s harvesting endpoint at https://journal.institution.edu/index.php/{journal}/oai.
Test the Identify Verb
Query ?verb=Identify to confirm repository name, admin email, protocol version (2.0), and deletion policies.
Verify Metadata Formats
Query ?verb=ListMetadataFormats to ensure oai_dc, rfc1807, and marcxml schemas are available.
Harvest Article Records via ListRecords
Query ?verb=ListRecords&metadataPrefix=oai_dc to inspect actual publication records and resumption tokens.
Run Open Archives Official Validator
Submit your endpoint to the official Open Archives validation suite (openarchives.org/Register/Validate) for certification.
Questions People Usually Ask
What is OAI-PMH and why do libraries use it?
OAI-PMH is an XML-based network protocol enabling institutional repositories and library discovery systems (like Primo, Summon, and WorldCat) to automatically pull journal metadata without human intervention.
Why does an OAI endpoint return an XML parsing error?
XML parsing errors occur when article abstracts or titles contain unescaped ampersands (& instead of &), raw angle brackets (<, >), or non-UTF-8 control characters that violate XML specification.
What is an OAI resumption token?
When an OJS repository contains thousands of articles, ListRecords returns results in batches (e.g., 100 per page). A resumptionToken is an alphanumeric cursor allowing harvesters to request subsequent pages.
Is Your OAI-PMH Endpoint Failing Validation?
AcademiaTech audits and repairs broken OAI-PMH harvesting feeds, ensuring seamless discovery across international library catalogues.