feat: added documentation for schema validation (#240)

Author: Sebastiaan Verbeek

README.md

@@ -33,15 +33,17 @@ export ENV_DIR=$PWD/../otomi-values CLOUD=google CLUSTER=demo
 
 ### 1. Validating changes
 
-You can check wether resulting manifests violate any of our output checks:
+You can check whether resulting manifests violate any of our output checks:
 
 ```bash
 otomi validate-templates
 ```
 
-This will check wether any CRs are matching their CRDs, but also check for k8s manifest best practices using [kubeval](https://www.kubeval.com).
+This will check whether any CRs are matching their CRDs, but also check for k8s manifest best practices using [kubeval](https://www.kubeval.com).
 
-We are also integrating another solution based on [conftest](https://www.conftest.dev). It allows to create OPA policies that are used both for statical analysis (at build time), as well as by [gatekeeper](https://github.com/open-policy-agent/gatekeeper) (at run time) to check wether manifests are conformant.
+We are also integrating another solution based on [conftest](https://www.conftest.dev). It allows to create OPA policies that are used both for statical analysis (at build time), as well as by [gatekeeper](https://github.com/open-policy-agent/gatekeeper) (at run time) to check whether manifests are conformant.
+
+There is in-built meta-schema validation for editing `otomi-values`-files. Refer to [meta-schema documentation](./docs/meta-schema-validation.md).
 
 ### 2. Diffing changes
 

docs/meta-schema-validation.md

@@ -0,0 +1,59 @@
+# Meta-schema validation
+
+We validate `values-schema.yaml` using JSON Schema. Refer to `values-schema.yaml` for the supported `$schema`, it should always be on top of the file for easy reference.
+
+## Guidelines for describing strings
+
+By having accurate and consistent descriptions (refer to `description` keys in `values-schema.yaml`), we can provide a better experience in configuring `otomi-values`. Refer to the [Kubernetes API documentation](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#validation) on conventions for description writing.
+
+### Examples
+
+Excellent:
+
+```
+
+oauth2-proxy:
+   type: object
+   additionalProperties: false
+   properties:
+      config:
+      type: object
+         properties:
+      cookieSecret:
+         type: string
+         description: Cookie secret must be 128 bit base64 encoded string.
+         pattern: ^(?:[A-Za-z0-9+/]{4})\\\*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?\$
+
+```
+
+Seeing a small improvement:
+
+```
+
+armAuth:
+   type: object
+   additionalProperties: false
+   description: A service Principal secret
+   properties:
+   secretJSON:
+      description: A service Principal secret JSON key (base64 encoded)
+      type: string
+
+```
+
+This could be modified to:
+
+```
+
+armAuth:
+   type: object
+   additionalProperties: false
+   description: A service Principal secret
+   properties:
+   secretJSON:
+      description: Must be a service Principal secret JSON key (base64 encoded)
+      type: string
+
+```
+
+etc.

values-schema.yaml

@@ -850,7 +850,7 @@ properties:
               - subnetPrefix
           armAuth:
             additionalProperties: false
-            description: A service Principal secret ey An explanation about the purpose of this instance.
+            description: A service Principal secret
             properties:
               secretJSON:
                 description: A service Principal secret JSON key (base64 encoded)