310 lines
9.6 KiB
YAML
310 lines
9.6 KiB
YAML
id: https://nde.nl/ontology/hc/class/OAIPMHEndpoint
|
|
name: oai_pmh_endpoint
|
|
title: OAIPMHEndpoint Class
|
|
prefixes:
|
|
linkml: https://w3id.org/linkml/
|
|
hc: https://nde.nl/ontology/hc/
|
|
dcat: http://www.w3.org/ns/dcat#
|
|
dcterms: http://purl.org/dc/terms/
|
|
schema: http://schema.org/
|
|
xsd: http://www.w3.org/2001/XMLSchema#
|
|
imports:
|
|
- linkml:types
|
|
- ../enums/OAIDeletedRecordPolicyEnum
|
|
- ../enums/OAIGranularityEnum
|
|
- ../metadata
|
|
- ../slots/has_or_had_score
|
|
- ../slots/response_format
|
|
- ../slots/specificity_annotation
|
|
- ./DataServiceEndpoint
|
|
- ./SpecificityAnnotation
|
|
- ./TemplateSpecificityScore
|
|
- ./TemplateSpecificityType
|
|
- ./TemplateSpecificityTypes
|
|
classes:
|
|
OAIPMHEndpoint:
|
|
is_a: DataServiceEndpoint
|
|
class_uri: hc:OAIPMHEndpoint
|
|
description: "OAI-PMH (Open Archives Initiative Protocol for Metadata Harvesting) endpoint.\n\n**Purpose:**\n\nModels OAI-PMH endpoints for automated metadata harvesting from heritage repositories.\nOAI-PMH is the dominant protocol for metadata aggregation in the GLAM sector.\n\n**Protocol Overview:**\n\nOAI-PMH defines six verbs:\n1. **Identify** - Repository information\n2. **ListMetadataFormats** - Available metadata formats\n3. **ListSets** - Collection/set hierarchy\n4. **ListIdentifiers** - Record identifiers\n5. **ListRecords** - Full records with metadata\n6. **GetRecord** - Single record by identifier\n\n**Example - Nationaal Archief OAI-PMH:**\n\n```yaml\noai_pmh_endpoint:\n endpoint_name: \"Nationaal Archief OAI-PMH\"\n base_url: \"https://www.nationaalarchief.nl/onderzoeken/oai-pmh\"\n protocol_version: \"2.0\"\n repository_name: \"Nationaal Archief\"\n admin_email: \"helpdesk@nationaalarchief.nl\"\n earliest_datestamp: \"2010-01-01\"\n deleted_record_policy: NO\n\
|
|
\ granularity: YYYY_MM_DD\n metadata_prefixes:\n - oai_dc\n - ese\n - edm\n sets:\n - name: \"Fotografische documenten\"\n spec: \"foto\"\n - name: \"Kaarten en tekeningen\"\n spec: \"kaarten\"\n```\n\n**Harvesting Workflow:**\n\n1. Call Identify to get repository info\n2. Call ListMetadataFormats to discover available formats\n3. Call ListSets to understand collection structure\n4. Call ListRecords with resumptionToken for incremental harvesting\n\n**See Also:**\n\n- OAI-PMH Specification: http://www.openarchives.org/OAI/openarchivesprotocol.html\n- Europeana Harvesting: https://pro.europeana.eu/page/harvesting-and-downloads\n"
|
|
attributes:
|
|
base_url:
|
|
slot_uri: dcat:endpointURL
|
|
description: "Base URL for OAI-PMH requests.\n\nAll OAI-PMH verbs are appended as query parameters to this URL.\n\nExample: \n- Base URL: \"https://www.nationaalarchief.nl/onderzoeken/oai-pmh\"\n- Identify request: \"https://www.nationaalarchief.nl/onderzoeken/oai-pmh?verb=Identify\"\n"
|
|
range: uri
|
|
required: true
|
|
protocol_version:
|
|
slot_uri: schema:version
|
|
description: 'OAI-PMH protocol version supported.
|
|
|
|
|
|
Current standard is version 2.0 (since 2002).
|
|
|
|
Earlier version 1.x is deprecated but may exist in legacy systems.
|
|
|
|
|
|
Values:
|
|
|
|
- "2.0" (current standard)
|
|
|
|
- "1.1" (legacy)
|
|
|
|
- "1.0" (legacy)
|
|
|
|
'
|
|
range: string
|
|
pattern: ^[12]\.[0-9]+$
|
|
repository_name:
|
|
slot_uri: schema:name
|
|
description: 'Human-readable name of the repository.
|
|
|
|
|
|
From OAI-PMH Identify response: <repositoryName>
|
|
|
|
|
|
Example: "Nationaal Archief"
|
|
|
|
'
|
|
range: string
|
|
admin_email:
|
|
slot_uri: schema:email
|
|
description: 'Email address of repository administrator.
|
|
|
|
|
|
From OAI-PMH Identify response: <adminEmail>
|
|
|
|
|
|
May be multiple emails.
|
|
|
|
|
|
Example: "helpdesk@nationaalarchief.nl"
|
|
|
|
'
|
|
range: string
|
|
multivalued: true
|
|
earliest_datestamp:
|
|
slot_uri: dcterms:temporal
|
|
description: 'Earliest datestamp available in the repository.
|
|
|
|
|
|
From OAI-PMH Identify response: <earliestDatestamp>
|
|
|
|
|
|
Records with dates before this are not available.
|
|
|
|
|
|
Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ssZ (depending on granularity)
|
|
|
|
|
|
Example: "2010-01-01"
|
|
|
|
'
|
|
range: string
|
|
deleted_record_policy:
|
|
slot_uri: schema:additionalProperty
|
|
description: 'Policy for reporting deleted records.
|
|
|
|
|
|
From OAI-PMH Identify response: <deletedRecord>
|
|
|
|
|
|
Values:
|
|
|
|
- NO: Repository does not maintain deleted records
|
|
|
|
- PERSISTENT: Deleted records are kept with "deleted" status
|
|
|
|
- TRANSIENT: Deleted records are kept for some time
|
|
|
|
'
|
|
range: OAIDeletedRecordPolicyEnum
|
|
granularity:
|
|
slot_uri: dcterms:accrualPeriodicity
|
|
description: 'Datestamp granularity supported by the repository.
|
|
|
|
|
|
From OAI-PMH Identify response: <granularity>
|
|
|
|
|
|
Values:
|
|
|
|
- YYYY_MM_DD: Day-level precision (YYYY-MM-DD)
|
|
|
|
- YYYY_MM_DD_THH_MM_SS_Z: Second-level precision (YYYY-MM-DDThh:mm:ssZ)
|
|
|
|
|
|
Determines format for `from` and `until` parameters in selective harvesting.
|
|
|
|
'
|
|
range: OAIGranularityEnum
|
|
metadata_prefixes:
|
|
slot_uri: dcterms:format
|
|
description: 'Metadata formats (prefixes) supported by this repository.
|
|
|
|
|
|
From OAI-PMH ListMetadataFormats response.
|
|
|
|
|
|
Common prefixes:
|
|
|
|
- **oai_dc**: Dublin Core (required by OAI-PMH specification)
|
|
|
|
- **ese**: Europeana Semantic Elements
|
|
|
|
- **edm**: Europeana Data Model
|
|
|
|
- **mods**: MODS (Metadata Object Description Schema)
|
|
|
|
- **marc21**: MARC 21
|
|
|
|
- **ead**: Encoded Archival Description
|
|
|
|
- **lido**: LIDO (museum objects)
|
|
|
|
- **dc**: Dublin Core (variant)
|
|
|
|
- **qdc**: Qualified Dublin Core
|
|
|
|
|
|
Example: ["oai_dc", "ese", "edm"]
|
|
|
|
'
|
|
range: string
|
|
multivalued: true
|
|
required: true
|
|
compression:
|
|
slot_uri: schema:encodingFormat
|
|
description: 'Compression methods supported.
|
|
|
|
|
|
From OAI-PMH Identify response: <compression>
|
|
|
|
|
|
Examples: ["gzip", "deflate"]
|
|
|
|
'
|
|
range: string
|
|
multivalued: true
|
|
sets:
|
|
slot_uri: dcat:theme
|
|
description: "Sets (collections) available for selective harvesting.\n\nFrom OAI-PMH ListSets response.\n\nStructured as list of set specifications with names.\n\nExample:\n```yaml\nsets:\n - spec: \"foto\"\n name: \"Fotografische documenten\"\n - spec: \"kaarten\" \n name: \"Kaarten en tekeningen\"\n```\n"
|
|
range: OAIPMHSet
|
|
multivalued: true
|
|
inlined_as_list: true
|
|
sample_identifier:
|
|
slot_uri: dcterms:identifier
|
|
description: 'Example identifier format used by this repository.
|
|
|
|
|
|
From OAI-PMH Identify response: <sampleIdentifier> (optional in spec)
|
|
|
|
|
|
Helps understand the identifier scheme.
|
|
|
|
|
|
Example: "oai:nationaalarchief.nl:2.04.87.01"
|
|
|
|
'
|
|
range: string
|
|
endpoint_description:
|
|
slot_uri: dcterms:description
|
|
description: 'Repository description from OAI-PMH Identify response.
|
|
|
|
|
|
May contain structured XML (oai-identifier, eprints, friends, etc.)
|
|
|
|
or free-text description.
|
|
|
|
'
|
|
range: string
|
|
supports_resumption_token:
|
|
slot_uri: schema:additionalProperty
|
|
description: 'Whether the repository supports resumption tokens for large result sets.
|
|
|
|
|
|
Required by OAI-PMH spec for ListRecords/ListIdentifiers/ListSets.
|
|
|
|
Most compliant repositories support this.
|
|
|
|
'
|
|
range: boolean
|
|
batch_size:
|
|
slot_uri: schema:maxValue
|
|
description: 'Typical number of records per response (before resumption token).
|
|
|
|
|
|
Not part of OAI-PMH spec but useful for harvesting optimization.
|
|
|
|
|
|
Example: 100
|
|
|
|
'
|
|
range: integer
|
|
total_records:
|
|
slot_uri: schema:numberOfItems
|
|
description: 'Total number of records in the repository (approximate).
|
|
|
|
|
|
From completeListSize attribute in OAI-PMH response (optional).
|
|
|
|
|
|
Example: 1500000
|
|
|
|
'
|
|
range: integer
|
|
last_harvested:
|
|
slot_uri: schema:dateModified
|
|
description: 'Date when this endpoint was last successfully harvested.
|
|
|
|
|
|
Useful for tracking incremental harvesting.
|
|
|
|
|
|
ISO 8601 format.
|
|
|
|
|
|
Example: "2025-12-01T10:30:00Z"
|
|
|
|
'
|
|
range: datetime
|
|
slot_usage:
|
|
response_format:
|
|
ifabsent: string(application/xml)
|
|
comments:
|
|
- Primary protocol for metadata harvesting in heritage sector
|
|
- All compliant repositories MUST support oai_dc (Dublin Core) format
|
|
- Use incremental harvesting with from/until parameters for efficiency
|
|
see_also:
|
|
- http://www.openarchives.org/OAI/openarchivesprotocol.html
|
|
- https://www.openarchives.org/OAI/2.0/guidelines.htm
|
|
slots:
|
|
- specificity_annotation
|
|
- has_or_had_score
|
|
annotations:
|
|
specificity_score: 0.1
|
|
specificity_rationale: Generic utility class/slot created during migration
|
|
custodian_types: "['*']"
|
|
OAIPMHSet:
|
|
class_uri: hc:OAIPMHSet
|
|
description: 'Represents an OAI-PMH Set (collection) available for selective harvesting.
|
|
|
|
|
|
Sets provide hierarchical organization of records, allowing harvesters
|
|
|
|
to request records from specific collections.
|
|
|
|
|
|
Set hierarchies use colon separator: "category:subcategory:item"
|
|
|
|
'
|
|
attributes:
|
|
name:
|
|
slot_uri: schema:name
|
|
range: string
|
|
required: true
|
|
record_count:
|
|
slot_uri: schema:numberOfItems
|
|
range: integer
|
|
slots:
|
|
- specificity_annotation
|
|
- has_or_had_score
|