diff --git a/docs/conf.py b/docs/conf.py
index dab41171..5a0b8f31 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,10 +1,8 @@
 import os
 
 import django
 
 os.environ.setdefault("DJANGO_SETTINGS_MODULE", "swh.deposit.settings.development")
 django.setup()
 
 from swh.docs.sphinx.conf import *  # NoQA
-
-extensions = ["sphinx.ext.autosectionlabel"]
diff --git a/docs/endpoints/collection.rst b/docs/endpoints/collection.rst
index 53219258..10326d76 100644
--- a/docs/endpoints/collection.rst
+++ b/docs/endpoints/collection.rst
@@ -1,73 +1,74 @@
+.. _API-create-deposit:
 Create deposit
 ^^^^^^^^^^^^^^^
 
 .. http:post:: /1/<collection-name>/
 
     Create deposit in a collection.
 
     The client sends a deposit request to a specific collection with:
 
     * an archive holding the software source code (binary upload)
     * an envelop with metadata describing information regarding a deposit (atom
       entry deposit)
 
       Also known as: COL-IRI
 
     :param text <name><pass>: the client's credentials
     :param text Content-Type: accepted mimetype
     :param int Content-Length: tarball size
     :param text Content-MD5: md5 checksum hex encoded of the tarball
     :param text Content-Disposition: attachment; filename=[filename]; the filename
       parameter must be text (ascii)
     :param text Content-Disposition: for the metadata file set name parameter
       to 'atom'.
     :param bool In-progress: true if not final; false when final request.
     :statuscode 201: success for deposit on POST
     :statuscode 401: Unauthorized
     :statuscode 404: access to an unknown collection
     :statuscode 415: unsupported media type
 
 Sample request
 ~~~~~~~~~~~~~~~
 .. code:: shell
 
         curl -i -u hal:<pass> \
             -F "file=@../deposit.json;type=application/zip;filename=payload" \
             -F "atom=@../atom-entry.xml;type=application/atom+xml;charset=UTF-8" \
             -H 'In-Progress: false' \
             -H 'Slug: some-external-id' \
             -XPOST https://deposit.softwareheritage.org/1/hal/
 
 Sample response
 ~~~~~~~~~~~~~~~
 
 .. code:: shell
 
     HTTP/1.0 201 Created
     Date: Tue, 26 Sep 2017 10:32:35 GMT
     Server: WSGIServer/0.2 CPython/3.5.3
     Vary: Accept, Cookie
     Allow: GET, POST, PUT, DELETE, HEAD, OPTIONS
     Location: /1/hal/10/metadata/
     X-Frame-Options: SAMEORIGIN
     Content-Type: application/xml
 
     <entry xmlns="http://www.w3.org/2005/Atom"
            xmlns:sword="http://purl.org/net/sword/"
            xmlns:dcterms="http://purl.org/dc/terms/">
         <deposit_id>10</deposit_id>
         <deposit_date>Sept. 26, 2017, 10:32 a.m.</deposit_date>
         <deposit_archive>None</deposit_archive>
         <deposit_status>deposited</deposit_status>
 
         <!-- Edit-IRI -->
         <link rel="edit" href="/1/hal/10/metadata/" />
         <!-- EM-IRI -->
         <link rel="edit-media" href="/1/hal/10/media/"/>
         <!-- SE-IRI -->
         <link rel="http://purl.org/net/sword/terms/add" href="/1/hal/10/metadata/" />
         <!-- State-IRI -->
         <link rel="alternate" href="/1/<collection-name>/10/status/"/>
 
         <sword:packaging>http://purl.org/net/sword/package/SimpleZip</sword:packaging>
     </entry>
diff --git a/docs/metadata.rst b/docs/metadata.rst
index f8e1cda2..7b07f724 100644
--- a/docs/metadata.rst
+++ b/docs/metadata.rst
@@ -1,185 +1,187 @@
 .. _deposit-metadata:
 
 Deposit metadata
 ================
 
 When making a software deposit into the SWH archive, one can add
 information describing the software artifact and the software project.
 
 
+.. _metadata-requirements:
+
 Metadata requirements
 ---------------------
 
 - **the schema/vocabulary** used *MUST* be specified with a persistent url
   (DublinCore, DOAP, CodeMeta, etc.)
 
   .. code:: xml
 
       <entry xmlns="http://www.w3.org/2005/Atom">
       or
       <entry xmlns="http://www.w3.org/2005/Atom"
 	     xmlns:dcterms="http://purl.org/dc/terms/">
       or
       <entry xmlns="http://www.w3.org/2005/Atom"
 	     xmlns:codemeta="https://doi.org/10.5063/SCHEMA/CODEMETA-2.0">
 
 - **the name** of the software deposit *MUST* be provided [atom:title,
    codemeta:name, dcterms:title]
 
 - **the authors** of the software deposit *MUST* be provided
 
 - **the url** representing the location of the source *MAY* be provided under
   the url tag. The url will be used for creating an origin object in the
   archive.
 
   .. code:: xml
 
       <codemeta:url>www.url-example.com</codemeta:url>
 
 - **the external\_identifier** *MAY* be provided as an identifier
 
 - **the external\_identifier** *SHOULD* match the Slug external-identifier in
   the header
 
 - **the description** of the software deposit *SHOULD* be provided
   [codemeta:description]: short or long description of the software
 
 - **the license/s** of the software
   deposit *SHOULD* be provided [codemeta:license]
 
 - other metadata *MAY* be added with terms defined by the schema in use.
 
 Examples
 --------
 
 Using only Atom
 ~~~~~~~~~~~~~~~
 
 .. code:: xml
 
     <?xml version="1.0"?>
         <entry xmlns="http://www.w3.org/2005/Atom">
             <title>Awesome Compiler</title>
             <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
             <external_identifier>1785io25c695</external_identifier>
             <updated>2017-10-07T15:17:08Z</updated>
             <author>some awesome author</author>
     </entry>
 
 Using Atom with CodeMeta
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code:: xml
 
     <?xml version="1.0"?>
         <entry xmlns="http://www.w3.org/2005/Atom"
                  xmlns:codemeta="https://doi.org/10.5063/SCHEMA/CODEMETA-2.0">
             <title>Awesome Compiler</title>
             <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
             <external_identifier>1785io25c695</external_identifier>
             <codemeta:id>1785io25c695</codemeta:id>
             <codemeta:url>origin url</codemeta:url>
             <codemeta:identifier>other identifier, DOI, ARK</codemeta:identifier>
             <codemeta:applicationCategory>Domain</codemeta:applicationCategory>
 
             <codemeta:description>description</codemeta:description>
             <codemeta:keywords>key-word 1</codemeta:keywords>
             <codemeta:keywords>key-word 2</codemeta:keywords>
             <codemeta:dateCreated>creation date</codemeta:dateCreated>
             <codemeta:datePublished>publication date</codemeta:datePublished>
             <codemeta:releaseNotes>comment</codemeta:releaseNotes>
             <codemeta:referencePublication>
               <codemeta:name> article name</codemeta:name>
               <codemeta:identifier> article id </codemeta:identifier>
             </codemeta:referencePublication>
             <codemeta:isPartOf>
                 <codemeta:type> Collaboration/Projet </codemeta:type>
                 <codemeta:name> project name</codemeta:name>
                 <codemeta:identifier> id </codemeta:identifier>
             </codemeta:isPartOf>
             <codemeta:relatedLink>see also </codemeta:relatedLink>
             <codemeta:funding>Sponsor A  </codemeta:funding>
             <codemeta:funding>Sponsor B</codemeta:funding>
             <codemeta:operatingSystem>Platform/OS </codemeta:operatingSystem>
             <codemeta:softwareRequirements>dependencies </codemeta:softwareRequirements>
             <codemeta:softwareVersion>Version</codemeta:softwareVersion>
             <codemeta:developmentStatus>active </codemeta:developmentStatus>
             <codemeta:license>
                 <codemeta:name>license</codemeta:name>
                 <codemeta:url>url spdx</codemeta:url>
             </codemeta:license>
             <codemeta:runtimePlatform>.Net Framework 3.0 </codemeta:runtimePlatform>
             <codemeta:runtimePlatform>Python2.3</codemeta:runtimePlatform>
             <codemeta:author>
                 <codemeta:name> author1 </codemeta:name>
                 <codemeta:affiliation> Inria </codemeta:affiliation>
                 <codemeta:affiliation> UPMC </codemeta:affiliation>
             </codemeta:author>
             <codemeta:author>
                 <codemeta:name> author2 </codemeta:name>
                 <codemeta:affiliation> Inria </codemeta:affiliation>
                 <codemeta:affiliation> UPMC </codemeta:affiliation>
             </codemeta:author>
             <codemeta:codeRepository>http://code.com</codemeta:codeRepository>
             <codemeta:programmingLanguage>language 1</codemeta:programmingLanguage>
             <codemeta:programmingLanguage>language 2</codemeta:programmingLanguage>
             <codemeta:issueTracker>http://issuetracker.com</codemeta:issueTracker>
         </entry>
 
 Using Atom with DublinCore and CodeMeta (multi-schema entry)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code:: xml
 
     <?xml version="1.0"?>
     <entry xmlns="http://www.w3.org/2005/Atom"
            xmlns:dcterms="http://purl.org/dc/terms/"
            xmlns:codemeta="https://doi.org/10.5063/SCHEMA/CODEMETA-2.0">
         <title>Awesome Compiler</title>
         <client>hal</client>
         <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
         <external_identifier>%s</external_identifier>
         <dcterms:identifier>hal-01587361</dcterms:identifier>
         <dcterms:identifier>doi:10.5281/zenodo.438684</dcterms:identifier>
         <dcterms:title xml:lang="en">The assignment problem</dcterms:title>
         <dcterms:title xml:lang="fr">AffectationRO</dcterms:title>
         <dcterms:creator>author</dcterms:creator>
         <dcterms:subject>[INFO] Computer Science [cs]</dcterms:subject>
         <dcterms:subject>[INFO.INFO-RO] Computer Science [cs]/Operations Research [cs.RO]</dcterms:subject>
         <dcterms:type>SOFTWARE</dcterms:type>
         <dcterms:abstract xml:lang="en">Project in OR: The assignment problemA java implementation for the assignment problem first release</dcterms:abstract>
         <dcterms:abstract xml:lang="fr">description fr</dcterms:abstract>
         <dcterms:created>2015-06-01</dcterms:created>
         <dcterms:available>2017-10-19</dcterms:available>
         <dcterms:language>en</dcterms:language>
 
 
         <codemeta:url>origin url</codemeta:url>
 
         <codemeta:softwareVersion>1.0.0</codemeta:softwareVersion>
         <codemeta:keywords>key word</codemeta:keywords>
         <codemeta:releaseNotes>Comment</codemeta:releaseNotes>
         <codemeta:referencePublication>Rfrence interne </codemeta:referencePublication>
 
         <codemeta:relatedLink>link  </codemeta:relatedLink>
         <codemeta:funding>Sponsor  </codemeta:funding>
 
         <codemeta:operatingSystem>Platform/OS </codemeta:operatingSystem>
         <codemeta:softwareRequirements>dependencies </codemeta:softwareRequirements>
         <codemeta:developmentStatus>Ended </codemeta:developmentStatus>
         <codemeta:license>
             <codemeta:name>license</codemeta:name>
             <codemeta:url>url spdx</codemeta:url>
         </codemeta:license>
 
         <codemeta:codeRepository>http://code.com</codemeta:codeRepository>
         <codemeta:programmingLanguage>language 1</codemeta:programmingLanguage>
         <codemeta:programmingLanguage>language 2</codemeta:programmingLanguage>
     </entry>
 
 Note
 ----
 We aim on harmonizing the metadata from different origins and thus
 metadata will be translated to the `CodeMeta
 v.2 <https://doi.org/10.5063/SCHEMA/CODEMETA-2.0>`__ vocabulary if
 possible.
diff --git a/docs/specs/spec-meta-deposit.rst b/docs/specs/spec-meta-deposit.rst
index c3c2c01e..80e4fe66 100644
--- a/docs/specs/spec-meta-deposit.rst
+++ b/docs/specs/spec-meta-deposit.rst
@@ -1,140 +1,141 @@
 The metadata-deposit
 ====================
 
 Goal
 ----
-A client wishes to deposit only metadata about an origin or object in the
-Software Heritage archive.
+
+A client wishes to deposit only metadata about an origin or object already
+present in the Software Heritage archive.
 
 The metadata-deposit is a special deposit where no content is
 provided and the data transferred to Software Heritage is only
 the metadata about an object in the archive.
 
 Requirements
 ------------
 
-1. :ref:`Create a metadata-only deposit through a POST request<Create deposit>`
+1. Create a metadata-only deposit through a :ref:`POST request<API-create-deposit>`
 2. It is composed of ONLY one xml metadata file
-3. It MUST comply with :ref:`the metadata requirements<Metadata Requirements>`
+3. It MUST comply with :ref:`the metadata requirements<metadata-requirements>`
 4. It MUST reference an **object** or an **origin** in a deposit tag
 5. The reference SHOULD exist in the SWH archive
 6. The **object** reference MUST be a SWHID on one of the following artifact types:
- - origin
- - snapshot
- - release
- - revision
- - directory
- - content
+   - origin
+   - snapshot
+   - release
+   - revision
+   - directory
+   - content
 7. The SWHID MAY be a `core identifier`_ with or without `qualifiers`_
 8. The SWHID MUST NOT reference a fragment of code with the classifier `lines`
 
 .. _core identifier: https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html#core-identifiers
 .. _qualifiers: https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html#qualifiers
 
 A complete metadata example
 ---------------------------
 The reference element is included in the metadata xml atomEntry under the
 swh namespace:
 
 .. code:: xml
 
   <?xml version="1.0"?>
   <entry xmlns="http://www.w3.org/2005/Atom"
            xmlns:codemeta="https://doi.org/10.5063/SCHEMA/CODEMETA-2.0"
            xmlns:swh="https://www.softwareheritage.org/schema/2018/deposit">
       <author>
         <name>HAL</name>
         <email>hal@ccsd.cnrs.fr</email>
       </author>
       <client>hal</client>
       <external_identifier>hal-01243573</external_identifier>
       <codemeta:name>The assignment problem</codemeta:name>
       <codemeta:url>https://hal.archives-ouvertes.fr/hal-01243573</codemeta:url>
       <codemeta:identifier>other identifier, DOI, ARK</codemeta:identifier>
       <codemeta:applicationCategory>Domain</codemeta:applicationCategory>
       <codemeta:description>description</codemeta:description>
       <codemeta:author>
         <codemeta:name> author1 </codemeta:name>
         <codemeta:affiliation> Inria </codemeta:affiliation>
         <codemeta:affiliation> UPMC </codemeta:affiliation>
       </codemeta:author>
       <codemeta:author>
         <codemeta:name> author2 </codemeta:name>
         <codemeta:affiliation> Inria </codemeta:affiliation>
         <codemeta:affiliation> UPMC </codemeta:affiliation>
       </codemeta:author>
       <swh:deposit>
         <swh:reference>
           <swh:origin url='https://github.com/user/repo'/>
         </swh:reference>
       </swh:deposit>
   </entry>
 
 References
 ^^^^^^^^^^
 
 The metadata reference can be either on:
 - an origin
 - a graph object (core SWHID with or without qualifiers)
 
 Origins
 =======
 
 The metadata may be on an origin, identified by the origin's URL:
 
 .. code:: xml
 
   <swh:deposit>
     <swh:reference>
       <swh:origin url="https://github.com/user/repo" />
     </swh:reference>
   </swh:deposit>
 
 Graph objects
 =============
 
 It may also reference an object in the `SWH graph <data-model>`: contents,
 directories, revisions, releases, and snapshots:
 
 .. code:: xml
 
   <swh:deposit>
     <swh:reference>
       <swh:object swhid="swh:1:dir:31b5c8cc985d190b5a7ef4878128ebfdc2358f49" />
     </swh:reference>
   </swh:deposit>
 
 .. code:: xml
 
   <swh:deposit>
     <swh:reference>
       <swh:object swhid="swh:1:dir:31b5c8cc985d190b5a7ef4878128ebfdc2358f49;
                          origin=https://hal.archives-ouvertes.fr/hal-01243573;
                          visit=swh:1:snp:4fc1e36fca86b2070204bedd51106014a614f321;
                          anchor=swh:1:rev:9c5de20cfb54682370a398fcc733e829903c8cba;
                          path=/moranegg-AffectationRO-df7f68b/"
       />
     </swh:reference>
   </swh:deposit>
 
 
 The value of the ``swhid`` attribute must be a `SWHID <persistent-identifiers>`,
 with any context qualifiers in this list:
 
 * ``origin``
 * ``visit``
 * ``anchor``
 * ``path``
 
 and they should be provided whenever relevant, especially ``origin``.
 
 Other qualifiers are not allowed (for example, ``line`` isn't because SWH
 cannot store metadata at a finer level than entire contents).
 
 
 Loading procedure
 ------------------
 
 In this case, the metadata-deposit will be injected as a metadata entry of
 the relevant object, with the information about the contributor of the deposit.
 Contrary to the complete and sparse deposit, there will be no object creation.