[validation] Add validation codes DXXX for validation failures

This patchset basically adds validation error codes (D001, D002)
for validation failures to align with UCP standard. The codes
are as follows:

* D001 - Indicates document sanity-check validation failure pre- or
  post-rendering.
* D002 - Indicates document post-rendering validation failure.

Change-Id: I01a99ec25c214629209ade5181debc39794c5561

deckhand/common/validation_message.py

@@ -12,6 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# Indicates document sanity-check validation failure pre- or post-rendering.
+DOCUMENT_SANITY_CHECK_FAILURE = 'D001'
+# Indicates document post-rendering validation failure.
+DOCUMENT_POST_RENDERING_FAILURE = 'D002'
+
 
 class ValidationMessage(object):
     """ValidationMessage per UCP convention:

deckhand/control/revision_documents.py

@@ -18,7 +18,7 @@ from oslo_utils import excutils
 import six
 
 from deckhand.common import utils
-from deckhand.common.validation_message import ValidationMessage
+from deckhand.common import validation_message as vm
 from deckhand.control import base as api_base
 from deckhand.control import common
 from deckhand.control.views import document as document_view
@@ -198,9 +198,9 @@ class RenderedDocumentsResource(api_base.BaseResource):
             for validation in validations:
                 if validation['status'] == 'failure':
                     error_list.extend([
-                        ValidationMessage(
-                            error=True,
+                        vm.ValidationMessage(
                             message=error['message'],
+                            name=vm.DOCUMENT_POST_RENDERING_FAILURE,
                             doc_schema=error['schema'],
                             doc_name=error['name'],
                             doc_layer=error['layer'],

deckhand/engine/document_validation.py

@@ -25,7 +25,7 @@ import six
 
 from deckhand.common import document as document_wrapper
 from deckhand.common import utils
-from deckhand.common.validation_message import ValidationMessage
+from deckhand.common import validation_message as vm
 from deckhand.engine.secrets_manager import SecretsSubstitution
 from deckhand import errors
 from deckhand import types
@@ -156,11 +156,13 @@ class GenericValidator(BaseValidator):
                     document.name, error_messages)
                 raise errors.InvalidDocumentFormat(
                     error_list=[
-                        ValidationMessage(message=message,
-                                          doc_schema=document.schema,
-                                          doc_name=document.name,
-                                          doc_layer=document.layer,
-                                          diagnostic=self._diagnostic)
+                        vm.ValidationMessage(
+                            message=message,
+                            name=vm.DOCUMENT_SANITY_CHECK_FAILURE,
+                            doc_schema=document.schema,
+                            doc_name=document.name,
+                            doc_layer=document.layer,
+                            diagnostic=self._diagnostic)
                         for message in error_messages
                     ],
                     reason='Validation'

deckhand/tests/functional/gabbits/schema-validation/schema-validation-success.yaml

@@ -157,7 +157,7 @@ tests:
       $.[0].details.messageList[0].error: true
       $.[0].details.messageList[0].kind: ValidationMessage
       $.[0].details.messageList[0].level: Error
-      $.[0].details.messageList[0].name: Deckhand validation error
+      $.[0].details.messageList[0].name: D002
       $.[0].kind: Status
       $.[0].message: The provided documents failed schema validation.
       $.[0].reason: Validation

deckhand/tests/unit/control/test_errors.py

@@ -139,7 +139,8 @@ class TestValidationMessageFormatting(test_base.BaseControllerTest):
                         'kind': 'ValidationMessage',
                         'level': 'Error',
                         'message': mock.ANY,
-                        'name': 'Deckhand validation error'
+                        # Indicates sanity-check failure pre-rendering.
+                        'name': 'D001'
                     },
                     {
                         'diagnostic': mock.ANY,
@@ -152,7 +153,7 @@ class TestValidationMessageFormatting(test_base.BaseControllerTest):
                         'kind': 'ValidationMessage',
                         'level': 'Error',
                         'message': mock.ANY,
-                        'name': 'Deckhand validation error'
+                        'name': 'D001'
                     }
                 ]
             },
@@ -216,7 +217,8 @@ class TestValidationMessageFormatting(test_base.BaseControllerTest):
                         'kind': 'ValidationMessage',
                         'level': 'Error',
                         'message': mock.ANY,
-                        'name': 'Deckhand validation error'
+                        # Indicates sanity-check failure post-rendering.
+                        'name': 'D001'
                     }
                 ]
             },

docs/source/validation.rst

@@ -41,7 +41,7 @@ Here is a list of internal validations:
 * ``deckhand-document-schema-validation`` - All concrete documents in the
   revision successfully pass their JSON schema validations. Will cause
   this to report an error.
-* ``deckhand-policy-validation`` - All required policy documents are in-place,
+* ``deckhand-policy-validation`` (TODO) - All required policy documents are in-place,
   and existing documents conform to those policies.  E.g. if a 3rd party
   document specifies a ``layer`` that is not present in the layering policy,
   that will cause this validation to report an error.
@@ -56,6 +56,19 @@ can reference to verify whether a Deckhand bucket is in a valid configuration.
 For more information, refer to the ``DataSchema`` section in
 :ref:`document-types`.
 
+Validation Codes
+^^^^^^^^^^^^^^^^
+
+* D001 - Indicates document sanity-check validation failure pre- or
+  post-rendering. This means that the document structure is fundamentally
+  broken.
+* D002 - Indicates document post-rendering validation failure. This means
+  that after a document has rendered, the document may fail validation.
+  For example, if a ``DataSchema`` document for a given revision indicates
+  that ``.data.a`` is a required field but a layering action during rendering
+  deletes ``.data.a``, then post-rendering validation will necessarily
+  fail. This implies a conflict in the set of document requirements.
+
 Schema Validations
 ------------------