OAI‐PMH Implementation

Table of Contents

1. Introduction
2. Getting Started
3. Testing the Implementation
   • Identify Verb
   • ListMetadataFormats Verb
   • ListRecords Verb
   • GetRecord Verb
4. Sample Data Insertion
5. Debugging and Validation
6. Additional Notes

---

Introduction

This documentation provides a comprehensive guide for implementing, testing, and validating the OAI-PMH (Open Archives Initiative Protocol for Metadata Harvesting) protocol in a Laravel application.

---

Getting Started 🚀

1. Start The Application Run the Laravel development server:

   php artisan serve

   The application will be accessible at http://127.0.0.1:8000.

2. Ensure Your Database is Seeded Use the Sample Data Insertion steps if required.

---

Testing the Implementation

Identify Verb

• URL: http://127.0.0.1:8000/oai-pmh?verb=Identify

• Expected Output:

  <OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/">
      <responseDate>2025-01-06T12:00:00Z</responseDate>
      <Identify>
          <repositoryName>HIKO Repository</repositoryName>
          <baseURL>http://127.0.0.1:8000/oai-pmh</baseURL>
          <protocolVersion>2.0</protocolVersion>
          <adminEmail>[email protected]</adminEmail>
          <earliestDatestamp>2000-01-01T00:00:00Z</earliestDatestamp>
          <deletedRecord>no</deletedRecord>
          <granularity>YYYY-MM-DDThh:mm:ssZ</granularity>
      </Identify>
  </OAI-PMH>

ListMetadataFormats Verb

• URL: http://127.0.0.1:8000/oai-pmh?verb=ListMetadataFormats

• Expected Output:

  <OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/">
      <responseDate>2025-01-06T12:00:00Z</responseDate>
      <ListMetadataFormats>
          <metadataFormat>
              <metadataPrefix>oai_dc</metadataPrefix>
              <schema>http://www.openarchives.org/OAI/2.0/oai_dc.xsd</schema>
              <metadataNamespace>http://www.openarchives.org/OAI/2.0/oai_dc/</metadataNamespace>
          </metadataFormat>
      </ListMetadataFormats>
  </OAI-PMH>

ListRecords Verb

• URL: http://127.0.0.1:8000/oai-pmh?verb=ListRecords&metadataPrefix=oai_dc&from=2025-01-01T00:00:00Z
• Expected Output:
  • If records exist: A list of <record> elements with metadata.
  • If no records exist: An empty response or an error indicating no matching records.

GetRecord Verb

• URL: Replace UUID_HERE with a valid uuid from your letters table: http://127.0.0.1:8000/oai-pmh?verb=GetRecord&identifier=UUID_HERE&metadataPrefix=oai_dc
• Expected Output: Metadata of the requested record in <metadata> tags.

---

Sample Data Insertion

Using Tinker

Run php artisan tinker and execute:

use App\Models\Letter;

Letter::create([
    'uuid' => \Illuminate\Support\Str::uuid(),
    'abstract' => 'Sample Abstract',
    'content' => 'Sample Content',
    'date_computed' => now(),
    'languages' => 'en',
    'updated_at' => now(),
]);

Using Seeder

Create a seeder:

php artisan make:seeder LetterSeeder

Add the following to database/seeders/LetterSeeder.php:

use Illuminate\Database\Seeder;
use App\Models\Letter;

class LetterSeeder extends Seeder
{
    public function run()
    {
        Letter::create([
            'uuid' => \Illuminate\Support\Str::uuid(),
            'abstract' => 'Sample Abstract',
            'content' => 'Sample Content',
            'date_computed' => now(),
            'languages' => 'en',
            'updated_at' => now(),
        ]);
    }
}

Run the seeder:

php artisan db:seed --class=LetterSeeder

---

Debugging and Validation

Laravel Logs

Check the logs for any errors:

tail -f storage/logs/laravel.log

Verify Database Content

Ensure that relevant tables (letters, keywords, places, etc.) contain valid data.

Use OAI-PMH Validator

Validate your implementation using an online OAI-PMH validator:

• URL: http://www.openarchives.org/Register/ValidateSite
• Steps:
  1. Enter the /oai-pmh URL.
  2. Validate.