diff --git a/doc/source/documents.rst b/doc/source/documents.rst index 8cbee7af..ef442cef 100644 --- a/doc/source/documents.rst +++ b/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: