.. SPDX-FileCopyrightText: 2026 Helmholtz-Zentrum Dresden-Rossendorf (HZDR) .. .. SPDX-License-Identifier: GPL-3.0-or-later Metadata Harvesting =================== HELIPORT's digital objects provide a variety of metadata, readable both for humans and machines. This page describes the main ideas to understand in order to harvest metadata from a HELIPORT instance. .. note:: When harvesting a HELIPORT instance, please conform to the ``/robots.txt`` file. Persistent Identifiers ---------------------- All digital objects have persistent identifiers which can be used to refer to them. If the identifier can be used as a URL (e.g. a Handle or a HELIPORT ID), it points directly at the landing page of the referenced digital object. More background on how persistent identifiers are assigned can be found in the :doc:`developer documentation <../development/persistent-identifiers>`. Landing Pages ------------- Landing pages (e.g. ``/object/H123/``), by default, present metadata in a human-readable way. `Content negotiation `_ is supported to retrieve the data in machine-readable formats. You can either send the ``Accept`` header with a matching MIME type, or append a ``format`` query parameter to the URL. These are the most important supported formats: ====================== ============================================== ===================== Format MIME type ``format`` value ====================== ============================================== ===================== HTML (human-readable) ``text/html`` ``landing_page`` JSON-LD ``application/ld+json``, ``application/json`` ``json``, ``jsonld`` Turtle ``text/turtle`` ``turtle`` RDF/XML ``application/rdf+xml``, ``application/xml`` ``xml`` N-Triples ``application/n-triples`` ``nt`` DataCite JSON ``application/vnd.datacite.datacite+json`` ``datacite_json`` DataCite XML ``application/vnd.datacite.datacite+xml`` ``datacite`` ====================== ============================================== ===================== If an unsupported MIME type or format value is supplied, the server responds with ``406 Not Acceptable`` and lists supported MIME types as plain text. The "Export Metadata" dropdown on the human-readable landing page lists all available formats. While landing pages for most digital objects present only metadata about the object itself, landing pages of project incorporate metadata of all digital objects which are associated with that project. Content Negotiation Example 1 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To retrieve the Turtle representation of digital object ``H123``, you could send the following request with ``curl``: .. code-block:: bash curl -H "Accept: text/turtle" https://heliport.example.com/object/H123/ Content Negotiation Example 2 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To retrieve the DataCite XML representation of this object, you could send the following request using Python: .. code-block:: python from urllib.parse import urlencode from urllib.request import urlopen url = "https://heliport.example.com/object/H123/?" + urlencode({"format": "datacite"}) with urlopen(url) as response: xml_text = response.read().decode() print(xml_text) Digital Object Metadata ----------------------- Metadata is provided using a variety of vocabularies and ontologies. Among them are DataCite, Dublin Core (``dcterms``), FOAF, schema.org (``sdo``), FRBR, and FABIO. Metadata can be either private or publicly readable; this is configured by the project owner on a per-object basis. Unauthenticated harvesters only receive metadata which the project owner has marked as public. Currently, no authentication methods for harvesters are available. Sitemaps -------- Project landing pages can be found in a machine-readable way via the sitemap at ``/sitemap.xml``. The sitemap lists all projects whose landing pages are accessible. The ``/robots.txt`` file of a HELIPORT instance references the sitemap, so that crawlers can discover it automatically. Atom Feeds ---------- HELIPORT offers an Atom feed for the digital objects of a project, at ``/feed/project//digital-objects/``. It lists the digital objects created in the given project via their landing pages. Feed items only expose metadata which is public, authentication is not supported. The feeds can be subscribed to by any client which wants to track newly created digital objects within a project.