airship
/
deckhand
Code Issues Proposed changes

Merge "docs: Expand on definition of document uniqueness"

This commit is contained in:
Zuul 2018-06-22 01:22:25 +00:00 committed by Gerrit Code Review
parent bb36db23ce d1b7ce154c
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.
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: