From d1b7ce154c409edf26dd98a2dcb14b76628034b1 Mon Sep 17 00:00:00 2001 From: Felipe Monteiro Date: Tue, 19 Jun 2018 18:59:25 -0400 Subject: [PATCH] docs: Expand on definition of document uniqueness This patchset expands on document uniquness in Deckhand which is a bit involved. 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 replacement. But after document rendering, the replacement-parent documents are never returned. Change-Id: I841caa83bef46bf5e155136fbcd7444b672d06f8 --- doc/source/documents.rst | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) 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: