usage article in README.md added

README.md

 # JSON Schema form generator RenderJS gadget
 
+## Usage
+
+It's assumed that a developer is familiar with RenderJS gadget documentation (https://renderjs.nexedi.com/).
+
+Gadget api is similar to any renderjs field api.
+
+```javascript
+gadget.render({
+  key: 'field_identificator',
+  value: [1,2],
+  schema: {
+    type: 'array',
+    items: {
+      type: 'integer'
+    }
+  }
+})
+```
+
+![rendered](doc/array_rendered.png)
+
+If schema_url is specified instead of schema property then schema_url is used for schema download.  
+
+Schema_url parameter should be specified for proper computation of an absolute url. If schema_url is omitted
+then the current gadget url is used as base_url. 
+
+Parent gadget should have declared notification methods to catch validation status.
+
+```javascript
+rJS(window)
+  .allowPublicAcquisition("notifyValid", function (arr, scope) {
+  })
+  .allowPublicAcquisition("notifyInvalid", function (arr, scope) {
+  })
+  .allowPublicAcquisition("notifyChange", function (arr, scope) {
+  });
+```
+
+In parent gadget downloadJSON() can be declared. DownloadJSON() can be used to
+fetch schema from jio storage. Example:
+
+```javascript
+rJS(window)
+  .allowPublicAcquisition("downloadJSON", function (arr) {
+    var g = this,
+      url = arr[0],
+      reference,
+      args;
+    //   return g.jio_getAttachment(id, "data", {format: "json"});
+    if (url.startsWith("urn:jio:reference?")) {
+      reference = decodeURIComponent(url.replace("urn:jio:reference?", ""));
+      args = {
+        query: '(portal_type: "JSON Schema") AND ((reference: "' + reference + '"))',
+        limit: [0, 1],
+        select_list: [],
+        sort_on: [["modification_date", "descending"]]
+      };
+      return g.jio_allDocs(args)
+        .push(function (result) {
+          return g.jio_getAttachment(result.data.rows[0].id, "data", {format: "json"});
+        });
+    }
+  })
+``` 
+
 ## What inside
 
 gadget consists of three parts:

[Jérome Perrin]

This is really minor, but shouldn't this be written as:

  query: Query.objectToSearchText({
    type: "complex",
    operator: "AND",
    query_list: [
      {
        key: "portal_type",
        type: "simple",
        value: "JSON Schema"
      },
      {
        key: "reference",
        type: "simple",
        value: reference
      }
    ]
  }),

to prevent problems where reference contain " or any other characters ?

/cc @romain @tc @vincentB

[Vincent Bechu]

Not sure it's an issue, quote inside reference will be escape by decoreURIcomponent function.

[Jérome Perrin]

in this specific case, maybe it's only a problem for this kind of schemas:

{
  "$schema": "http://json-schema.org/draft-06/schema#", 
  "hehe": {
    "$ref": "\"ahah\""
  }
}

so it will in reality probably never be a problem, but my point here was more that I believe we should prefer "query as object" API over "query as string" every time we are generating queries by code, for similar reasons than the reasons why we don't generate SQL queries as strings.

[Boris Kocherov]

I agree with @jerome it is an issue. i fix it in: nexedi/erp5@fee2cd74 16ad6d13

[Romain Courteaud]

+1

jIO query string should never be generated by concatenating string without escaping them.