airship
/
deckhand
Code Issues Proposed changes

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
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.
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: