.. SPDX-FileCopyrightText: 2024 Helmholtz-Zentrum Dresden-Rossendorf (HZDR)
..
.. SPDX-License-Identifier: GPL-3.0-or-later

.. _pids:

Persistent Identifiers (PIDs)
=============================

Digital objects in HELIPORT are identified by globally unique persistent identifiers
(PIDs).
They are stored in :class:`heliport.core.models.DigitalObjectIdentifier`.
The method :meth:`heliport.core.models.DigitalObject.preferred_identifier` can be used
to find an appropriate identifier for an object.

.. note::

   In the past, persistent identifiers were stored in digital objects' ``persistent_id``
   and ``generated_persistent_id`` attributes.
   These fields are deprecated.

:class:`heliport.core.models.DigitalObjectIdentifier` can store identifiers for
different aspects of a digital object.
Currently, the model supports *main* identifiers which represent the digital object
itself, and identifiers for *metadata graphs*.
The latter can be used in the future as graph names in a graph database, or to implement
a multi-layered `"FAIR Digital Objects" <https://fairdo.org/>`_ approach.
Other aspects may be added in the future.

PIDs can also be differentiated by their "scheme".
This attribute combines the notion of a "PID provider" (think DOI or Handle.net) with
information about how to display the PID to the user, and which HELIPORT-internal
implementation to use to make changes to this PID at the provider site.

PID Generation
--------------

HELIPORT uses post-save hooks to automatically generate, or mint, identifiers for a
digital object, when it is first saved.

For all digital objects, an associated "HELIPORT ID" will be created, which is a
fallback identifier that can be used if the object has no other identifiers.
The HELIPORT ID is equal to the landing page URL of the digital object.
Each digital object will also receive an additional HELIPORT ID for its metadata graph.

HELIPORT also supports minting Handle.net identifiers, or "handles".
If Handle.net integration is set up correctly, these are created in addition to the
HELIPORT ID.
Handles are only created as main identifiers, not for the metadata graph.
Handles consist of a fixed prefix which you `acquire through the CNRI
<https://handle.net/>`_, and a suffix which is unique to each minted handle.
All handles can be resolved via the resolver URL ``https://hdl.handle.net/<handle>``
which redirects to the landing page of the associated digital object.

HELIPORT chooses the handle suffix based on the :ref:`namespace <namespaces>` associated
with the digital object, and its primary key.
:meth:`heliport.core.models.DigitalObject.suffix_for_pid_generation` provides a string
which is used for this purpose.

More information can be found in :mod:`heliport.core.pid_registration`.

External Identifiers
--------------------

HELIPORT can also use external identifiers, i.e., identifiers which were not generated
by HELIPORT, to refer to digital objects.
Typically, these will be entered by the user, or imported from an external system or
database.
Possible examples are `DOIs of publications <https://doi.org>`_ (issued by
`DataCite <https://datacite.org/>`_ or `Crossref <https://www.crossref.org/>`_),
`IGSNs for physical samples <https://igsn.org/>`_, or URLs for ontology terms.

To associate an external identifier with a digital object,
:meth:`heliport.core.models.DigitalObject.set_identifier` can be used.
If this method is called *before* saving the object for the first time, no other
main identifier will be created for this digital object.

:meth:`heliport.core.models.DigitalObject.set_identifier` determines which identifier
was passed based on the `DataCite Ontology <http://purl.org/spar/datacite>`_.
The implementation can be found in :mod:`heliport.core.utils.identifiers`.