improve README.md

README.md

 # JSON Schema form generator RenderJS gadget
 
-## Structure
+## What inside
 
-**Gadget for recursive load schema**
+gadget consists of three parts:
 
-[gadget_erp5_page_slap_load_schema.html](gadget_erp5_page_slap_load_schema.html)
+**first part: Main gadget for form generation**
 
-* **done** remove jquery dependence
-* **done** support in $ref [rfc6901](https://tools.ietf.org/html/rfc6901)
+[jsonform.gadget.html](jsonform.gadget.html)
 
-**Gadget for recursive form generation**
+ * Expand schema - download reference, multiple anyOf andOf optimisation
+ to one level anyOf which transformed in array of schemas. Resulting array
+ of schemas (schema_arr) is used in [gadget_json_generated_form_child.html](jsonform/gadget_json_generated_form_child.html)
+ to generate schema selector. Contains various schema optimisations
+ which reduce user choice according to schema logic.
 
-[gadget_json_generated_form.html](gadget_json_generated_form.html)
+ * Using of parent_gadget.downloadJSON() to resolve "urn:jio:" url schema
+ links - it allows to use gadget inside officejs application and work
+ with schemas saved in jio storage. Relative links are correctly resolved too.
 
-* **done** remove slapos specific code
-* **done** remove jquery dependence
-* **partly done** full support of json schema
-* **done** support in path [rfc6901](https://tools.ietf.org/html/rfc6901)
-* **done** using changeState and mutex
-* separate form design from code for form generation
-* add general using documentation
+ * During expanding new json schema document (generated_schema) is created. It is based on
+ original json schema and its references are substituted by downloaded/resolved
+ schema parts. Gadget downloads and resolves references on demand, this
+ allows to work with circular infinite schemas.
 
-**Gadget for generate slapos parameter form**
+ * json_document validation by modified tv4 library using generated_schema.
 
-[gadget_erp5_page_slap_parameter_form.html](gadget_erp5_page_slap_parameter_form.html)
+ * control of two types of circular references:
 
-It is the previous version of gadget used for form generation.
-It should be changed for it uses the above gadget as children
-for form generation.
+    * Hard Circular Reference (HCR): when all fields in download stack are required and
+    stack is circular. Creation of valid document based on schema which contains HCR
+    is impossible. Gadget reports error and breaks infinite loop if HCR is
+    detected.
 
-In this gadget the below listed specific slapos code should be saved:
+    * Soft Circular Reference (SCR): when all property fields in circular stack
+     have one schema selection. Property fields containing one variant
+     schema rendered immediately. If SCR is found then gadget marks schema
+     as circular and breaks infinite loop. Schema generation continues,
+     next subform is rendered on user request.
 
-* gui for selection of `software type` and `serialized format output`
-* JsonDocument serialization to xml
-* JsonDocument converting to xml
-* downloading schema for user software type choice
-* text representation of form if intialJsonData is not valid for current schema
-* gui for switch to text mode custom JsonDocument input
+**second part: Gadget for recursive form generation**
 
-## JSON schema supported
+[jsonform/gadget_json_generated_form_child.html](jsonform/gadget_json_generated_form_child.html)
 
-Below is the list of JSON Schema validation properties and current supported status:
+ * html5 form render on base of json schema definition.
 
-**array**
+ * recursive gadget declaration for rendering array items and optional properties.
 
-**fixed** *rendering is not supported*
+ * gadget uses tv4 validator for guess: on base of which schema variant
+ json document is valid. Chosen variant is used for form rendering.
 
-* `additionalItems`
-    - rendering is not supported
-* `items`
-    - union is not supported
-* `maxItems`
-    - rendering is not supported
-* `minItems`
-    - **fixed** rendering is not supported
-* `uniqueItems`
-    - rendering is not supported
+ * calculate element by dataPath - field path inside json document.
+ This is used to display validation errors in correct places.
 
-**integer** *(Number uses the same properties so if you need `number`, set your `type` explicitly)*
+**third part: tv4**
 
-*online input limitation should be improved*
+[jsonform/tv4.js](jsonform/tv4.js)
 
-* `exclusiveMaximum`
-* `exclusiveMinimum`
-* *done* `maximum`
-* *done* `minimum`
-* *done* `multipleOf`
+modified version of original tv4.js. Difference from original:
 
-**object**
+* support of draft7 except if-then-else
 
-* `additionalProperties`
-    - **fixed** rendering is not supported
-* `dependencies`
-    - rendering is not supported
-* `maxProperties`
-    - rendering is not supported
-* `minProperties`
-    - rendering is not supported
-* `patternProperties`
-    - **fixed** values can be only `object` types
-    - **done** add buttons for remove existed `patternProperties`
-    - **fixed** can not be mixed with `properties`
-    - **fixed** only regex .* in keys is supported
-* `properties`
-* `required`
+* code which is responsible for references resolving and downloading is removed
+ because tv4 does not work with circular schema.
 
-**string**
+## known limitations
 
-*online input limitation should be improved*
+Render limitations described below are not critical because json document
+is rendered and correctly validated. Errors are alerted in case of document not
+valid.
 
-* **done** `maxLength`
-* **done** `minLength`
-* **done** `pattern`
+**string field rendering**
 
+* `minLength` limiting realized as html5 regexp pattern attribute so it
+ cannot be rendered simultaneously with `pattern` limiting.
 
+**number field rendering**
+
+* `multipleOf` limiting realized as html5 step attribute so `minimum`
+limiting must be divisible by `multipleOf` without reminder for being rendered
+simultaneously with `multipleOf`.
+
+* `exclusiveMaximum` `exclusiveMinimum` limitation does not rendered
+
+**object field rendering**
+
+* `dependencies`, `maxProperties`, `minProperties` rendering is not
+embodied
+
+* schema can contain patternProperties and regular properties. If regular
+ properties match pattern from patternProperties then two schemas need merging
+ which is not realized.
+
+* if schema has variation (anyOf or type is not specified) then schema selector
+is rendered. If json document already contains value in field which is related to
+specific schema variation then to change field type the field should be deleted and
+readded. In this case user has no hint that schema has more than one variation.
+
+**array field rendering**
+
+* change items order currently unavailable
+
+* `additionalItems` partial support
+
+* `maxItems`, `uniqueItems` rendering is not supported
+
+**json schema limitation**
+
+* modified tv4 validator support draft7 schema, except if-then-else.
+
+**reference resolver**
+
+* id/$id is not used for change base url