Merge "docs: Expand on definition of document uniqueness"

doc/source/documents.rst

@@ -52,19 +52,34 @@ and ``data``.
 
 * ``metadata`` - Defines details that Deckhand will inspect and understand.
   There are multiple schemas for this section as discussed below. All the
-  various types of metadata include a `name` field which must be unique for
-  each document ``schema``.
+  various types of metadata include a ``metadata.name`` field which must be
+  unique for each document ``schema``.
 * ``data`` - Data to be validated by the schema described by the ``schema``
   field. Deckhand only interacts with content here as instructed to do so by
   the ``metadata`` section. The form of this section is considered to be
   completely owned by the ``namespace`` in the ``schema``.
 
-Furthermore, documents are uniquely identified by the combination of:
+At the **database** level, documents are uniquely identified by the combination
+of:
 
 #. ``metadata.name``
 #. ``schema``
 #. ``metadata.layeringDefinition.layer``
 
+This means that raw revision documents -- which are persisted in Deckhand's
+database -- require that the combination of all 3 parameters be unique.
+
+However, **post-rendered documents** are only uniquely identified by the
+combination of:
+
+#. ``metadata.name``
+#. ``schema``
+
+Because collisions with respect to the the third parameter --
+``metadata.layeringDefinition.layer`` -- can only occur with
+:ref:`replacement`. But after document rendering, the replacement-parent
+documents are never returned.
+
 Below is a fictitious example of a complete document, which illustrates all the
 valid fields in the ``metadata`` section: