airship/deckhand
Code Issues Proposed changes

docs: Expand on definition of document uniqueness

Browse Source 
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
This commit is contained in:
Felipe Monteiro 2018-06-19 18:59:25 -04:00
parent 2ac59980e7
commit d1b7ce154c
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: