--- title: Share your metadata with OAI-PMH description: Expose your public catalog for harvesting by aggregators and discovery services using the built-in OAI-PMH endpoint. section: guides order: 17 updated: 2026-06-25 verified: 2026-06-25 related: [ guides/custom-fields, guides/subjects-concepts-and-authorities, guides/collections-and-permissions, guides/importing-photos, ] features: [metadata-export, custom-fields] --- # Share your metadata with OAI-PMH Let aggregators, union catalogs, and discovery services collect your records on their own schedule. Every institution exposes a standard **OAI-PMH 2.0** endpoint that publishes your public artifacts as Dublin Core, mapping your fields to the standard terms harvesters expect. The endpoint is the export counterpart to importing: the same crosswalk that maps incoming columns to your fields also maps your fields _out_ to standard elements, so the records you publish carry recognized terms (`dc:title`, `dc:subject`, …) rather than Preservated-internal keys. ## The endpoint Your repository base URL is: ``` https:////oai ``` It is public — no key or login — and serves only **public** artifacts. Members-only and private artifacts are never harvested, and field-level privacy is honored (see [What gets shared](#what-gets-shared)). A harvester begins by asking the repository to describe itself: ``` GET //oai?verb=Identify ``` This returns the repository name, the earliest record date, and the supported options. From there the six standard OAI-PMH verbs work as usual: `Identify`, `ListMetadataFormats`, `ListSets`, `ListIdentifiers`, `ListRecords`, and `GetRecord`. ## Metadata formats Five formats are advertised by `ListMetadataFormats`: - **`oai_dc`** — simple Dublin Core, the lowest common denominator every harvester accepts. Use this unless you have a reason not to. - **`oai_qdc`** — qualified Dublin Core. Surfaces refinements that simple DC has to collapse, such as provenance, medium, and precise creation dates. - **`lido`** — LIDO 1.0, the XML harvesting format for museum objects. Use this for object-level descriptions (work type, title, production event, subjects, rights) when the harvester is a museum aggregator such as Europeana. - **`cdwalite`** — Getty CDWA-Lite 1.1, the object-description harvesting schema used by Getty/ARTstor-style aggregators. - **`marc21`** — MARC21-slim (MARCXML), the library bibliographic interchange format. Use this when the harvester is a library catalog or a WorldCat-style union catalog. Each record carries a leader, the control number, name and title access points, and topical/geographic/genre subject headings. For the museum and library formats, a controlled term carries its authority on the term element — LIDO as a `lido:conceptID`, CDWA-Lite as `termsource`/`termsourceID` attributes, and MARC21 as a `$0` subfield (the authority URI) plus a `$2` source code on subject headings — so a harvester can rebind to the same vocabulary record. Request records in a format with the `metadataPrefix` argument: ``` GET //oai?verb=ListRecords&metadataPrefix=oai_dc ``` ## Harvest a collection (sets) Each **public collection** is exposed as an OAI _set_. List them with: ``` GET //oai?verb=ListSets ``` The `setSpec` of each set is the collection's URL slug. Restrict a harvest to one collection by adding `set`: ``` GET //oai?verb=ListRecords&metadataPrefix=oai_dc&set=photographs ``` ## Harvest only what changed For incremental harvesting, bound the request by the record modification date with `from` and `until` (inclusive). Both accept a date (`2024-01-01`) or a full UTC timestamp (`2024-01-01T00:00:00Z`); use the same granularity for both: ``` GET //oai?verb=ListRecords&metadataPrefix=oai_dc&from=2024-01-01 ``` ## Paging through large result sets Long lists are returned in pages. When more records remain, the response ends with a ``. Send it back — and _only_ it — to fetch the next page: ``` GET //oai?verb=ListRecords&resumptionToken= ``` The token already encodes your original format, set, and date window, so you do not repeat those arguments. An empty `` element marks the end of the list. ## What gets shared The endpoint maps your data to standard elements through the field crosswalk, with three rules that decide what leaves your repository: - **Your fields carry standard terms.** First-class fields (title, identifier, date, creators, description, place, rights) and your [controlled concepts](/docs/en-US/guides/subjects-concepts-and-authorities) map to the matching Dublin Core elements automatically. Concepts are published with the authority and identifier you recorded — nothing is re-derived or guessed. - **Controlled terms carry their authority.** In `oai_qdc`, a concept or authority-linked reference is published with its vocabulary identifier and scheme attached to the element (a `valueURI` and `authority` attribute). A harvester — including a re-import into Preservated — can then rebind to the same authority instead of creating a duplicate. (Strict `oai_dc` carries the label only, to stay schema-valid.) - **Custom fields share only when mapped.** A [custom field](/docs/en-US/guides/custom-fields) appears in harvest output only if it carries a crosswalk to the target standard. An unmapped field stays internal. This makes sharing deliberate: you choose what is interoperable. - **Private fields never leave.** A field marked **private** — valuations, donor details, storage location — is excluded from all harvest output, the same way it is hidden from public pages. :::note Several local fields can map to the same standard element. If you keep separate "Photographer," "Artist," and "Maker" fields all crosswalked to `dc:creator`, a harvester sees one consistent `dc:creator` list — which is exactly what makes a mixed collection searchable alongside everyone else's. ::: ## Linked data (JSON-LD) For applications that work with linked-open-data graphs rather than harvest-format records, each public artifact also publishes a **JSON-LD** representation modeled on [CIDOC-CRM](https://www.cidoc-crm.org/) — the museum world's linked-data ontology: ``` GET //artifacts/.jsonld ``` It returns `application/ld+json`: the artifact as a CIDOC-CRM `E22 Human-Made Object`, with its production event (creators, date, place, technique), object types, materials, and subjects expressed as typed, linkable nodes. Where you recorded an authority identifier for a concept, person, or place, that authority URI _is_ the node's identity in the graph — so an aggregator can line your records up against the same Getty AAT, LCSH, or Wikidata entity another institution used, with no guessing or re-derivation. Like the OAI endpoint, this is public and serves only **public** artifacts; a non-public or unknown artifact returns 404. The same privacy rules apply — private and unmapped data stay internal. ## Deletions The repository declares `deletedRecord` as `no`: it does not publish tombstones for removed artifacts. A harvester that needs to drop deleted items should periodically re-harvest rather than rely on incremental deletion notices.