airship/deckhand
Code Issues Proposed changes

Merge "docs: Expand on definition of document uniqueness"

Browse Source
This commit is contained in:
Zuul 2018-06-22 01:22:25 +00:00 committed by Gerrit Code Review
commit 1981eaeb99
1 changed files with 18 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
doc/source/documents.rst
View File

@ -52,19 +52,34 @@ and ``data``.
* ``metadata`` - Defines details that Deckhand will inspect and understand. * ``metadata`` - Defines details that Deckhand will inspect and understand.
There are multiple schemas for this section as discussed below. All the 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 various types of metadata include a ``metadata.name`` field which must be
each document ``schema``. unique for each document ``schema``.
* ``data`` - Data to be validated by the schema described by the ``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 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 the ``metadata`` section. The form of this section is considered to be
completely owned by the ``namespace`` in the ``schema``. 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`` #. ``metadata.name``
#. ``schema`` #. ``schema``
#. ``metadata.layeringDefinition.layer`` #. ``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 Below is a fictitious example of a complete document, which illustrates all the
valid fields in the ``metadata`` section: valid fields in the ``metadata`` section: