Differential D536 Diff 1708 docs/persistent-identifiers.rst

Changeset View

Standalone View

docs/persistent-identifiers.rst

Show First 20 Lines • Show All 122 Lines • ▼ Show 20 Lines	* ``swh:1:rev:309cf2674ee7a0749978cf8265ab91a60aea0f7d`` points to a commit in
the development history of Darktable, dated 16 January 2017, that added		the development history of Darktable, dated 16 January 2017, that added
undo/redo supports for masks		undo/redo supports for masks
* ``swh:1:rel:22ece559cc7cc2364edc5e5593d63ae8bd229f9f`` points to Darktable		* ``swh:1:rel:22ece559cc7cc2364edc5e5593d63ae8bd229f9f`` points to Darktable
release 2.3.0, dated 24 December 2016		release 2.3.0, dated 24 December 2016
* ``swh:1:snp:c7c108084bc0bf3d81436bf980b46e98bd338453`` points to a snapshot		* ``swh:1:snp:c7c108084bc0bf3d81436bf980b46e98bd338453`` points to a snapshot
of the entire Darktable Git repository taken on 4 May 2017 from GitHub		of the entire Darktable Git repository taken on 4 May 2017 from GitHub


Resolution
----------

Persistent identifiers can be resolved using the Software Heritage Web
application (see :py:mod:`swh.web`).

In particular, the root endpoint ``/`` can be given a persistent identifier and
will lead to the browsing page of the corresponding object, like this:
``https://archive.softwareheritage.org/<identifier>``. For example:

* `<https://archive.softwareheritage.org/swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2>`_
* `<https://archive.softwareheritage.org/swh:1:dir:d198bc9d7a6bcf6db04f476d29314f157507d505>`_
* `<https://archive.softwareheritage.org/swh:1:rev:309cf2674ee7a0749978cf8265ab91a60aea0f7d>`_
* `<https://archive.softwareheritage.org/swh:1:rel:22ece559cc7cc2364edc5e5593d63ae8bd229f9f>`_
* `<https://archive.softwareheritage.org/swh:1:snp:c7c108084bc0bf3d81436bf980b46e98bd338453>`_


Contextual information		Contextual information
======================		======================

It is often useful to complement persistent identifiers with **contextual		It is often useful to complement persistent identifiers with **contextual
information** about where the identified object has been found as well as which		information** about where the identified object has been found as well as which
specific parts of it are of interest. To that end it is possible, via a		specific parts of it are of interest. To that end it is possible, via a
dedicated syntax, to extend persistent identifiers with the following pieces of		dedicated syntax, to extend persistent identifiers with the following pieces of
information:		information:
Show All 30 Lines	* line numbers: it is possible to specify a single line number or a line range,
separating two numbers with ``-``. Note that line numbers are purely		separating two numbers with ``-``. Note that line numbers are purely
indicative and are not meant to be stable, as in some degenerate cases		indicative and are not meant to be stable, as in some degenerate cases
(e.g., text files which mix different types of line terminators) it is		(e.g., text files which mix different types of line terminators) it is
impossible to resolve them unambiguously.		impossible to resolve them unambiguously.

* software origin: where a given object has been found or observed in the wild,		* software origin: where a given object has been found or observed in the wild,
as the URI that was used by Software Heritage to ingest the object into the		as the URI that was used by Software Heritage to ingest the object into the
archive		archive


		Resolution
		==========


		Dedicated resolvers
		-------------------

		Persistent identifiers can be resolved using the Software Heritage Web
		application (see :py:mod:`swh.web`). In particular, the root endpoint
		``/`` can be given a persistent identifier and will lead to the browsing page
		of the corresponding object, like this:
		``https://archive.softwareheritage.org/<identifier>``.

		A dedicated ``/resolve`` endpoint of the HTTP API is also available to
		explicitly request persistent identifier resolution; see:
		:http:get:`/api/1/resolve/(swh_id)/`.

		Examples:

		* `<https://archive.softwareheritage.org/swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2>`_
		* `<https://archive.softwareheritage.org/swh:1:dir:d198bc9d7a6bcf6db04f476d29314f157507d505>`_
		* `<https://archive.softwareheritage.org/api/1/resolve/swh:1:rev:309cf2674ee7a0749978cf8265ab91a60aea0f7d>`_
		* `<https://archive.softwareheritage.org/api/1/resolve/swh:1:rel:22ece559cc7cc2364edc5e5593d63ae8bd229f9f>`_
		* `<https://archive.softwareheritage.org/api/1/resolve/swh:1:snp:c7c108084bc0bf3d81436bf980b46e98bd338453>`_


		External resolvers
		moraneggUnsubmitted Done Inline Actions Also n2T.net (Name-to-Thing) resolves our identifiers works like https://identifiers.org/ with the slight advantage that it resolves the identifier with context as well. moranegg: Also n2T.net (Name-to-Thing) resolves our identifiers works like https://identifiers.org/ with…
		------------------

		The following independent resolvers support resolution of Software
		Heritage persistent identifiers:

		* `Identifiers.org <https://identifiers.org>`_; see:
		`<http://identifiers.org/swh/>`_ (registry identifier `MIR:00000655
		<https://www.ebi.ac.uk/miriam/main/datatypes/MIR:00000655>`_).

		* `Name-to-Thing (N2T) <https://n2t.net/>`_

		Examples:

		* `<https://identifiers.org/swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2>`_
		* `<https://identifiers.org/swh:1:dir:d198bc9d7a6bcf6db04f476d29314f157507d505>`_
		* `<https://identifiers.org/swh:1:rev:309cf2674ee7a0749978cf8265ab91a60aea0f7d>`_
		* `<https://n2t.net/swh:1:rel:22ece559cc7cc2364edc5e5593d63ae8bd229f9f>`_
		* `<https://n2t.net/swh:1:snp:c7c108084bc0bf3d81436bf980b46e98bd338453>`_

		Note that resolution via Identifiers.org does not support contextual
		information, due to `syntactic incompatibilities
		<http://identifiers.org/documentation#custom_requests>`_.