diff --git a/docs/specs/protocol-reference.rst b/docs/specs/protocol-reference.rst --- a/docs/specs/protocol-reference.rst +++ b/docs/specs/protocol-reference.rst @@ -273,6 +273,79 @@ :ref:`metadata deposit specification ` +.. _deposit-metadata-provenance: + +Metadata provenance +------------------- + +To indicate where the metadata is coming from, deposit clients can use a +```` element in ```` whose content is +the object the metadata is coming from, +preferably using the ``https://schema.org/`` namespace. + +For example, when the metadata is coming from Wikidata, then the +```` should be the page of a Q-entity, such as +``https://www.wikidata.org/wiki/Q16988498`` (not the Q-entity +``http://www.wikidata.org/entity/Q16988498`` itself, as the Q-entity **is** the +object described in the metadata) +Or when the metadata is coming from a curated repository like HAL, then +```` should be the HAL project. + +In particular, Software Heritage expects the ```` object +to have a ``https://schema.org/url`` property, so that it can appropriately link +to the original page. + +For example, to deposit metadata on GNU Hello: + +.. code:: xml + + + + + + + + + https://www.wikidata.org/wiki/Q16988498 + + + + + + + +Here is a more complete example of a metadata-only deposit on version 2.9 of GNU Hello, +to show the interaction with other fields, + +.. code:: xml + + + + + + + + + + + https://www.wikidata.org/wiki/Q16988498 + + + + GNU Hello + http://www.wikidata.org/entity/Q16988498 + https://www.gnu.org/software/hello/ + + + http://www.wikidata.org/entity/Q7598 + + + + Schema ------ diff --git a/docs/specs/swh.xsd b/docs/specs/swh.xsd --- a/docs/specs/swh.xsd +++ b/docs/specs/swh.xsd @@ -6,32 +6,41 @@ > - - - - - - - + + + + + + + + + - - - - - - + + + + + + + + + + + + + + + + + + + - - - - - - - - + + - +