Changeset View
Changeset View
Standalone View
Standalone View
docs/persistent-identifiers.rst
| Show All 36 Lines | |||||
| Syntactically, persistent identifiers are generated by the ``<identifier>`` | Syntactically, persistent identifiers are generated by the ``<identifier>`` | ||||
| entry point of the grammar: | entry point of the grammar: | ||||
| .. code-block:: bnf | .. code-block:: bnf | ||||
| <identifier> ::= "swh" ":" <scheme_version> ":" <object_type> ":" <object_id> ; | <identifier> ::= "swh" ":" <scheme_version> ":" <object_type> ":" <object_id> ; | ||||
| <scheme_version> ::= "1" ; | <scheme_version> ::= "1" ; | ||||
| <object_type> ::= | <object_type> ::= | ||||
| "snp" (* snapshot *) | "ori" (* origin *) | ||||
ardumont: "ori" (* origin *)
;) | |||||
| | "snp" (* snapshot *) | |||||
| | "rel" (* release *) | | "rel" (* release *) | ||||
| | "rev" (* revision *) | | "rev" (* revision *) | ||||
| | "dir" (* directory *) | | "dir" (* directory *) | ||||
| | "cnt" (* content *) | | "cnt" (* content *) | ||||
| ; | ; | ||||
| <object_id> ::= 40 * <hex_digit> ; (* intrinsic object id, as hex-encoded SHA1 *) | <object_id> ::= 40 * <hex_digit> ; (* intrinsic object id, as hex-encoded SHA1 *) | ||||
| <dec_digit> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | <dec_digit> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | ||||
| <hex_digit> ::= <dec_digit> | "a" | "b" | "c" | "d" | "e" | "f" ; | <hex_digit> ::= <dec_digit> | "a" | "b" | "c" | "d" | "e" | "f" ; | ||||
| Semantics | Semantics | ||||
| --------- | --------- | ||||
| ``:`` is used as separator between the logical parts of identifiers. The | ``:`` is used as separator between the logical parts of identifiers. The | ||||
| ``swh`` prefix makes explicit that these identifiers are related to *SoftWare | ``swh`` prefix makes explicit that these identifiers are related to *SoftWare | ||||
| Heritage*. ``1`` (``<scheme_version>``) is the current version of this | Heritage*. ``1`` (``<scheme_version>``) is the current version of this | ||||
| identifier *scheme*; future editions will use higher version numbers, possibly | identifier *scheme*; future editions will use higher version numbers, possibly | ||||
| breaking backward compatibility (but without breaking the resolvability of | breaking backward compatibility (but without breaking the resolvability of | ||||
| identifiers that conform to previous versions of the scheme). | identifiers that conform to previous versions of the scheme). | ||||
| A persistent identifier points to a single object, whose type is explicitly | A persistent identifier points to a single object, whose type is explicitly | ||||
| captured by ``<object_type>``: | captured by ``<object_type>``: | ||||
| * ``snp`` identifiers points to **snapshots**, | * ``ori`` identifiers point to **origins** | ||||
| * ``snp`` to **snapshots**, | |||||
| * ``rel`` to **releases**, | * ``rel`` to **releases**, | ||||
| * ``rev`` to **revisions**, | * ``rev`` to **revisions**, | ||||
| * ``dir`` to **directories**, | * ``dir`` to **directories**, | ||||
| * ``cnt`` to **contents**. | * ``cnt`` to **contents**. | ||||
| The actual object pointed to is identified by the intrinsic identifier | The actual object pointed to is identified by the intrinsic identifier | ||||
| ``<object_id>``, which is a hex-encoded (using lowercase ASCII characters) SHA1 | ``<object_id>``, which is a hex-encoded (using lowercase ASCII characters) SHA1 | ||||
| computed on the content and metadata of the object itself, as follows: | computed on the content and metadata of the object itself, as follows: | ||||
| * for **origins**, intrinsic identifiers are computed as per | |||||
| :py:func:`swh.model.identifiers.origin_identifier` | |||||
| * for **snapshots**, intrinsic identifiers are computed as per | * for **snapshots**, intrinsic identifiers are computed as per | ||||
| :py:func:`swh.model.identifiers.snapshot_identifier` | :py:func:`swh.model.identifiers.snapshot_identifier` | ||||
| * for **releases**, as per | * for **releases**, as per | ||||
| :py:func:`swh.model.identifiers.release_identifier` | :py:func:`swh.model.identifiers.release_identifier` | ||||
| * for **revisions**, as per | * for **revisions**, as per | ||||
| :py:func:`swh.model.identifiers.revision_identifier` | :py:func:`swh.model.identifiers.revision_identifier` | ||||
| Show All 36 Lines | * ``swh:1:dir:d198bc9d7a6bcf6db04f476d29314f157507d505`` points to a directory | ||||
| at some point on 4 May 2017 | at some point on 4 May 2017 | ||||
| * ``swh:1:rev:309cf2674ee7a0749978cf8265ab91a60aea0f7d`` points to a commit in | * ``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 | ||||
| * ``swh:1:ori:b63a575fe3faab7692c9f38fb09d4bb45651bb0f`` points to the | |||||
| repository https://github.com/torvalds/linux . | |||||
| 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 | ||||
| ▲ Show 20 Lines • Show All 101 Lines • Show Last 20 Lines | |||||
"ori" (* origin *)
;)