Add the JSON Schema Documentation page

README.md

@@ -216,6 +216,8 @@ The configuration file format depends on the version of jenkins-core and install
 Documentation is generated from a live instance, as well as a JSON schema you can use to validate configuration file
 with your favourite YAML tools.
 
+The JSON Schema documentation can be found [here](https://github.com/jenkinsci/configuration-as-code-plugin/blob/master/docs/features/jsonSchema.md).
+
 ## Handling Secrets
 
 Currently, you can provide initial secrets to JCasC that all rely on <key,value>

docs/features/jsonSchema.md

@@ -0,0 +1,72 @@
+# JSON Schema 
+
+| WARNING: This page describes a beta feature which is currently under development. The implementation may change in an incompatible way. Use at your own risk |
+| --- |
+
+Jenkins Configuration as Code plugin sometimes requires users to define pretty complex YAML configuration files.
+At the same time, mistakes in the configuration may lead to the instance instability.
+In order to help maintainers, the plugin can generate an instance-specific JSON schema which can be used for validation of YAML files.
+
+## Current state
+
+Currently there are 2 types of JSON schema being generated by the plugin.
+There is a legacy schema generation logic which has been available since JCasC 1.0, but this feature generates an invalid JSON schema which cannot be used as is without manual patches.
+In order to solve the issue, in the [JCasC Developer Tools project](https://jenkins.io/projects/jcasc/dev-tools/) we are working on a new Schema version which is currently available as a **beta feature**.
+The implementation may change in an incompatible way before the final release.
+
+The documentation below describes the new implementation.
+
+The new JSON Schema is structured to validate the YAML files that are loaded via JCasC.
+The structure and validation of the Schema is done based on the user-installed plugins.
+
+=== Version
+
+The Schema uses JSON draft v07. 
+http://json-schema.org/draft-07/schema#
+
+=== How to use
+
+* The schema will be available at /configuration-as-code/v2Schema
+* Users can use various online JSON validators to check against their YAML/json.
+
+=== Progress
+
+* The new JSON Schema is partially working and is in beta mode.
+* The schema validates any missing  configurator objects and invalid data formats.
+* It is built around the existing executable xml (jelly files) and follows the latest draft version of JSON.
+* The schema does not yet validate against deep nested configurations.
+* We are working towards supporting deep nested YAML files.
+
+== Improvements
+
+* The Old Schema was generated using Jelly files that did not generate a valid JSON Schema.
+* Without a valid schema it is not possible to validate a YAML file rendering the schema unusable.
+* The previous schema included an `"$ref":` for an `object` type, the new draft of the schema makes it mandatory
+  to use `"$id":` hence the new schema uses it instead of ref.
+
+== What the schema does
+
+* The schema validates simple YAML files with root configurators.
+```yaml
+# config truncated
+jenkins:
+  numExecutors: 2
+```
+* In the above example if the data type of numExecutors is entered wrong, the schema will invalidate it.
+
+== What the schema does not do
+
+* It cannot validate nested yml files, with multiple levels of configurators.
+```yaml
+# config truncated
+jenkins:
+  numExecutors: 0
+
+  nodes:
+    - dumb:
+        mode: NORMAL
+        name: "agent1"
+```
+* The above YAML has a deep level of nesting which the JSON Schema currently does not support.
+
+