metadata reference

docs/deposit/howto/prepare.rst

@@ -6,7 +6,6 @@ Prepare your metadata and artifacts
 A deposit is constituted of a metadata file and optionally one or more software
 artefacts.
 
-
 The metadata file
 -----------------
 
@@ -42,14 +41,9 @@ swh:deposit
 This namespace is specific to our implementation of the SWORD v2 protocol, it's used
 to describe what kind of deposit the you are doing:
 
-- a first code deposit for an ``ORIGIN_URL`` not yet archived by SWH
-- a new code deposit (i.e. another version of the software) for an existing
-  ``ORIGIN_URL``
-- a metadata-only deposit for a ``SWHID`` or an ``ORIGIN_URL``
-
 .. tab-set::
 
-  .. tab-item:: Initial code deposit ``create_origin``
+  .. tab-item:: Initial deposit
 
     .. code-block:: xml
 
@@ -59,7 +53,7 @@ to describe what kind of deposit the you are doing:
          </swh:create_origin>
       </swh:deposit>
 
-  .. tab-item:: New version code deposit ``add_to_origin``
+  .. tab-item:: New version deposit
 
     .. code-block:: xml
 
@@ -69,7 +63,7 @@ to describe what kind of deposit the you are doing:
          </swh:add_to_origin>
       </swh:deposit>
 
-  .. tab-item:: Metadata-only deposit ``reference``
+  .. tab-item:: Metadata-only deposit
 
     .. code-block:: xml
 

docs/deposit/references/metadata.rst

@@ -90,6 +90,115 @@ Or, equivalently:
 Note that in both these examples, ``codemeta:name`` is used even though
 the property is actually ``http://schema.org/name``.
 
+swh:deposit
+~~~~~~~~~~~
+
+This namespace is specific to our implementation of the SWORD v2 protocol, it's used
+to describe what kind of deposit the you are doing.
+
+A first code deposit for an ``ORIGIN_URL`` not yet archived by SWH using
+``<swh:create_origin>``:
+
+.. code-block:: xml
+
+   <swh:deposit>
+      <swh:create_origin>
+         <swh:origin url="ORIGIN_URL" />
+      </swh:create_origin>
+   </swh:deposit>
+
+A new code deposit (i.e. another version of the software) for an existing
+``ORIGIN_URL``:
+
+.. code-block:: xml
+
+   <swh:deposit>
+      <swh:add_to_origin>
+         <swh:origin url="ORIGIN_URL" />
+      </swh:add_to_origin>
+   </swh:deposit>
+
+A metadata-only deposit for a ``SWHID`` or an ``ORIGIN_URL`` using ``<swh:reference>``:
+
+.. code-block:: xml
+
+   <swh:deposit>
+      <swh:reference>
+         <swh:object swhid="SWHID_CONTEXT" />
+         <!-- or -->
+         <swh:object swhid="SWHID" />
+         <!-- or -->
+         <swh:origin url="ORIGIN_URL" />
+      </swh:reference>
+   </swh:deposit>
+
+To indicate where the metadata is coming from, deposit clients can use a
+``<swhdeposit:metadata-provenance>`` element in ``<swhdeposit:deposit>`` whose content
+is the object the metadata is coming from, preferably using the ``http://schema.org/``
+namespace.
+
+For example, when the metadata is coming from Wikidata, then the
+``<swhdeposit:metadata-provenance>`` 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
+``<swhdeposit:metadata-provenance>`` should be the HAL project.
+
+In particular, Software Heritage expects the ``<swhdeposit:metadata-provenance>`` object
+to have a ``http://schema.org/url`` property, so that it can appropriately link
+to the original page.
+
+For example, to deposit metadata on GNU Hello:
+
+.. code:: xml
+
+   <?xml version="1.0"?>
+   <entry xmlns="http://www.w3.org/2005/Atom"
+          xmlns:schema="http://schema.org/">
+
+     <!-- ... -->
+
+     <swh:deposit>
+       <swh:metadata-provenance>
+         <schema:url>https://www.wikidata.org/wiki/Q16988498</schema:url>
+       </swh:metadata-provenance>
+     </swh:deposit>
+
+     <!-- ... -->
+
+   </entry>
+
+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
+
+   <?xml version="1.0"?>
+   <entry xmlns="http://www.w3.org/2005/Atom"
+          xmlns:swh="https://www.softwareheritage.org/schema/2018/deposit"
+          xmlns:schema="http://schema.org/"
+          xmlns:codemeta="https://doi.org/10.5063/SCHEMA/CODEMETA-2.0">
+
+     <swh:deposit>
+       <swh:reference>
+         <swh:object swhid="swh:1:dir:9b6f93b12a500f560796c8dffa383c7f4470a12f;origin=https://ftp.gnu.org/gnu/hello/;visit=swh:1:snp:1abd6aa1901ba0aa7f5b7db059250230957f8434;anchor=swh:1:rev:3d41fbdb693ba46fdebe098782be4867038503e2" />
+       </swh:reference>
+
+       <swh:metadata-provenance>
+         <schema:url>https://www.wikidata.org/wiki/Q16988498</schema:url>
+       </swh:metadata-provenance>
+     </swh:deposit>
+
+     <codemeta:name>GNU Hello</codemeta:name>
+     <codemeta:id>http://www.wikidata.org/entity/Q16988498</codemeta:id>
+     <codemeta:url>https://www.gnu.org/software/hello/</codemeta:url>
+
+     <!-- is part of the GNU project -->
+     <codemeta:isPartOf>http://www.wikidata.org/entity/Q7598</codemeta:isPartOf>
+
+   </entry>
+
 Properties
 ----------
 
@@ -122,7 +231,6 @@ here for clarity.
    * - codemeta:license
      - The license(s) of the software
 
-
 See the `full CodeMeta terms list <https://codemeta.github.io/terms/>`_ for a complete
 reference of the available properties.