From bbfe719349634ae566f4107a38839060da3ae9d0 Mon Sep 17 00:00:00 2001 From: Felipe Monteiro Date: Thu, 30 Nov 2017 20:18:38 +0000 Subject: [PATCH] [docs] Document schemas used for document validation This PS adds documentation for all the document schemas that are used for ``deckhand-schema-validation`` validations. This will help users to know what their schemas need to look like for Deckhand to accept them. The documentation like most of it is generated automically via sphinx. A docstring was provided under each module schema variable and included inside __all__ because according to docs [0]: "For modules, __all__ will be respected when looking for members; the order of the members will also be the order in __all__." [0] http://www.sphinx-doc.org/en/stable/ext/autodoc.html#directive-automodule Change-Id: I224f3980dcf877bab400aa505728a332e67709cc --- AUTHORS | 1 + deckhand/engine/schema/base_schema.py | 11 ++++++++ .../schema/v1_0/certificate_key_schema.py | 15 ++++++++++ .../engine/schema/v1_0/certificate_schema.py | 15 ++++++++++ .../engine/schema/v1_0/data_schema_schema.py | 15 ++++++++++ .../engine/schema/v1_0/document_schema.py | 18 ++++++++++++ .../schema/v1_0/layering_policy_schema.py | 15 ++++++++++ .../engine/schema/v1_0/passphrase_schema.py | 15 ++++++++++ .../schema/v1_0/validation_policy_schema.py | 16 +++++++++++ doc/source/validation.rst | 28 +++++++++++++++++++ 10 files changed, 149 insertions(+) diff --git a/AUTHORS b/AUTHORS index e963a4fb..32272823 100644 --- a/AUTHORS +++ b/AUTHORS @@ -9,3 +9,4 @@ Mike Kochetov Pete Birley Scott Hussey Tin Lam +portdirect diff --git a/deckhand/engine/schema/base_schema.py b/deckhand/engine/schema/base_schema.py index 8f28ad0c..787e724b 100644 --- a/deckhand/engine/schema/base_schema.py +++ b/deckhand/engine/schema/base_schema.py @@ -34,3 +34,14 @@ schema = { 'additionalProperties': False, 'required': ['schema', 'metadata'] } +"""Base JSON schema against which all Deckhand documents are validated. + +.. literalinclude:: ../../deckhand/engine/schema/base_schema.py + :language: python + :lines: 15-36 + +This schema is used to sanity-check all documents that are passed to Deckhand. +Failure to pass this schema results in a critical error. +""" + +__all__ = ['schema'] diff --git a/deckhand/engine/schema/v1_0/certificate_key_schema.py b/deckhand/engine/schema/v1_0/certificate_key_schema.py index 93abd0a1..be3b95ce 100644 --- a/deckhand/engine/schema/v1_0/certificate_key_schema.py +++ b/deckhand/engine/schema/v1_0/certificate_key_schema.py @@ -47,3 +47,18 @@ schema = { 'additionalProperties': False, 'required': ['schema', 'metadata', 'data'] } +"""JSON schema against which all documents with ``deckhand/CertificateKey/v1`` +``schema`` are validated. + +.. literalinclude:: ../../deckhand/engine/schema/v1_0/certificate_key_schema.py + :language: python + :lines: 15-49 + +This schema is used to sanity-check all CertificateKey documents that are +passed to Deckhand. This schema is only enforced after validation for +:py:data:`~deckhand.engine.schema.base_schema` has passed. Failure to pass +this schema will result in an error entry being created for the validation +with name ``deckhand-schema-validation`` corresponding to the created revision. +""" + +__all__ = ['schema'] diff --git a/deckhand/engine/schema/v1_0/certificate_schema.py b/deckhand/engine/schema/v1_0/certificate_schema.py index 25f63a66..ef26c11f 100644 --- a/deckhand/engine/schema/v1_0/certificate_schema.py +++ b/deckhand/engine/schema/v1_0/certificate_schema.py @@ -47,3 +47,18 @@ schema = { 'additionalProperties': False, 'required': ['schema', 'metadata', 'data'] } +"""JSON schema against which all documents with ``deckhand/Certificate/v1`` +``schema`` are validated. + +.. literalinclude:: ../../deckhand/engine/schema/v1_0/certificate_schema.py + :language: python + :lines: 15-49 + +This schema is used to sanity-check all Certificate documents that are +passed to Deckhand. This schema is only enforced after validation for +:py:data:`~deckhand.engine.schema.base_schema` has passed. Failure to pass +this schema will result in an error entry being created for the validation +with name ``deckhand-schema-validation`` corresponding to the created revision. +""" + +__all__ = ['schema'] diff --git a/deckhand/engine/schema/v1_0/data_schema_schema.py b/deckhand/engine/schema/v1_0/data_schema_schema.py index 1b67c177..66a6dfa1 100644 --- a/deckhand/engine/schema/v1_0/data_schema_schema.py +++ b/deckhand/engine/schema/v1_0/data_schema_schema.py @@ -60,3 +60,18 @@ schema = { 'additionalProperties': False, 'required': ['schema', 'metadata', 'data'] } +"""JSON schema against which all documents with ``deckhand/DataSchema/v1`` +``schema`` are validated. + +.. literalinclude:: ../../deckhand/engine/schema/v1_0/data_schema_schema.py + :language: python + :lines: 15-62 + +This schema is used to sanity-check all DataSchema documents that are +passed to Deckhand. This schema is only enforced after validation for +:py:data:`~deckhand.engine.schema.base_schema` has passed. Failure to pass +this schema will result in an error entry being created for the validation +with name ``deckhand-schema-validation`` corresponding to the created revision. +""" + +__all__ = ['schema'] diff --git a/deckhand/engine/schema/v1_0/document_schema.py b/deckhand/engine/schema/v1_0/document_schema.py index eaf16d4e..a287ffe6 100644 --- a/deckhand/engine/schema/v1_0/document_schema.py +++ b/deckhand/engine/schema/v1_0/document_schema.py @@ -100,3 +100,21 @@ schema = { 'additionalProperties': False, 'required': ['schema', 'metadata', 'data'] } +"""JSON schema against which all documents with ``metadata/Document/v1`` +``metadata.schema`` are validated. + +.. literalinclude:: ../../deckhand/engine/schema/v1_0/document_schema.py + :language: python + :lines: 15-102 + +This schema is used to sanity-check all "metadata/Document" documents that are +passed to Deckhand. This validation comes into play when a new schema is +registered under the ``data`` section of a ``deckhand/DataSchema/v1`` document. + +This schema is only enforced after validation for +:py:data:`~deckhand.engine.schema.base_schema` has passed. Failure to pass +this schema will result in an error entry being created for the validation +with name ``deckhand-schema-validation`` corresponding to the created revision. +""" + +__all__ = ['schema'] diff --git a/deckhand/engine/schema/v1_0/layering_policy_schema.py b/deckhand/engine/schema/v1_0/layering_policy_schema.py index ace8e863..c6020eeb 100644 --- a/deckhand/engine/schema/v1_0/layering_policy_schema.py +++ b/deckhand/engine/schema/v1_0/layering_policy_schema.py @@ -50,3 +50,18 @@ schema = { 'additionalProperties': False, 'required': ['schema', 'metadata', 'data'] } +"""JSON schema against which all documents with ``deckhand/LayeringPolicy/v1`` +``schema`` are validated. + +.. literalinclude:: ../../deckhand/engine/schema/v1_0/layering_policy_schema.py + :language: python + :lines: 15-52 + +This schema is used to sanity-check all LayeringPolicy documents that are +passed to Deckhand. This schema is only enforced after validation for +:py:data:`~deckhand.engine.schema.base_schema` has passed. Failure to pass +this schema will result in an error entry being created for the validation +with name ``deckhand-schema-validation`` corresponding to the created revision. +""" + +__all__ = ['schema'] diff --git a/deckhand/engine/schema/v1_0/passphrase_schema.py b/deckhand/engine/schema/v1_0/passphrase_schema.py index e9e7b211..98dc553b 100644 --- a/deckhand/engine/schema/v1_0/passphrase_schema.py +++ b/deckhand/engine/schema/v1_0/passphrase_schema.py @@ -47,3 +47,18 @@ schema = { 'additionalProperties': False, 'required': ['schema', 'metadata', 'data'] } +"""JSON schema against which all documents with ``deckhand/Passphrase/v1`` +``schema`` are validated. + +.. literalinclude:: ../../deckhand/engine/schema/v1_0/passphrase_schema.py + :language: python + :lines: 15-49 + +This schema is used to sanity-check all Passphrase documents that are +passed to Deckhand. This schema is only enforced after validation for +:py:data:`~deckhand.engine.schema.base_schema` has passed. Failure to pass +this schema will result in an error entry being created for the validation +with name ``deckhand-schema-validation`` corresponding to the created revision. +""" + +__all__ = ['schema'] diff --git a/deckhand/engine/schema/v1_0/validation_policy_schema.py b/deckhand/engine/schema/v1_0/validation_policy_schema.py index 8416bc2a..7c2a0995 100644 --- a/deckhand/engine/schema/v1_0/validation_policy_schema.py +++ b/deckhand/engine/schema/v1_0/validation_policy_schema.py @@ -62,3 +62,19 @@ schema = { 'additionalProperties': False, 'required': ['schema', 'metadata', 'data'] } +"""JSON schema against which all documents with +``deckhand/ValidationPolicy/v1`` ``schema`` are validated. + +.. literalinclude:: + ../../deckhand/engine/schema/v1_0/validation_policy_schema.py + :language: python + :lines: 15-64 + +This schema is used to sanity-check all ValidationPolicy documents that are +passed to Deckhand. This schema is only enforced after validation for +:py:data:`~deckhand.engine.schema.base_schema` has passed. Failure to pass +this schema will result in an error entry being created for the validation +with name ``deckhand-schema-validation`` corresponding to the created revision. +""" + +__all__ = ['schema'] diff --git a/doc/source/validation.rst b/doc/source/validation.rst index 04fb694a..a7f50004 100644 --- a/doc/source/validation.rst +++ b/doc/source/validation.rst @@ -112,3 +112,31 @@ Validation Module .. autoclass:: deckhand.engine.document_validation.DocumentValidation :members: :private-members: + +.. _schemas: + +Validation Schemas +================== + +Below are the schemas deckhand uses to validate documents. + +.. automodule:: deckhand.engine.schema.base_schema + :members: schema + +.. automodule:: deckhand.engine.schema.v1_0.certificate_key_schema + :members: schema + +.. automodule:: deckhand.engine.schema.v1_0.certificate_schema + :members: schema + +.. automodule:: deckhand.engine.schema.v1_0.data_schema_schema + :members: schema + +.. automodule:: deckhand.engine.schema.v1_0.layering_policy_schema + :members: schema + +.. automodule:: deckhand.engine.schema.v1_0.passphrase_schema + :members: schema + +.. automodule:: deckhand.engine.schema.v1_0.validation_policy_schema + :members: schema