Add documentation for integrity URL

docs/openrosa-form-list.rst

@@ -208,6 +208,7 @@ Elements within ``<mediaFile/>``
 -  ``<filename/>`` The unique un-rooted file path for this media file. This un-rooted path must not start with a drive name or slash and must not contain relative path navigations (for example, ``.`` or ``..``).
 -  ``<hash/>`` The hash value of the media file available for download. The only hash values currently supported are MD5 hashes of the file contents; they are prefixed by ``md5:``. If the hash value identified in the manifest differs from the hash value for a previously-downloaded media file, then the file should be re-fetched from the server.
 -  ``<downloadUrl/>`` A fully qualified URI for downloading the media file to the device. It may be a valid http or https URI of any structure; the server may require authentication; the server may require a secure (https) channel, etc.
+-  ``<integrityUrl/>`` A fully qualified URI for using the :doc:`Integrity API <openrosa-integrity>` for this media file.
 
 ``<mediaFile/>`` attributes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/openrosa-integrity.md

@@ -0,0 +1,44 @@
+# Integrity API
+
+This standard defines how clients can check the integrity of entity lists that are attached to forms as media files.
+
+## Integrity request
+
+Integrity requests can be made with an HTTP `GET` request to the server provided integrity URL with a comma-separated `id` query parameter specifying the ids of entities being checked. For example:
+
+```
+https://example.com/integrity?id=1,2,3
+```
+
+This request will return an integrity document.
+
+### Integrity document
+
+The structure of the integrity document returned by an integrity request is as follows:
+
+```xml
+<?xml version='1.0' encoding='UTF-8' ?>
+<data>
+<entities>
+    <entity id="24b47424-ccf8-4f4b-b4cd-34ff5c71eddd">
+        deleted>true</deleted>
+    </entity>
+    <entity id="9e32d18f-d51a-4826-a8b2-e9b1c6d10b58">
+        <deleted>false</deleted>
+    </entity>
+</entities>
+</data>
+```
+
+This document consists of:
+
+- A top-level `<data/>` tag in the `http://openrosa.org/xforms/xformsIntegrity` namespace enclosing:
+  - zero or more `<entity/>` tags containing a exactly one `<deleted/>` tag
+
+#### Elements with `<entity/>`
+
+- `<deleted/>` should contain `true` if the entity has been deleted on the server, and `false` if not
+
+#### `<entity/>` attributes
+
+- `id`: id of the entity

docs/openrosa.rst

@@ -23,3 +23,4 @@ OpenRosa 1.0 APIs were formally approved by the OpenRosa Working Group in Decemb
   openrosa-authentication
   openrosa-form-submission
   openrosa-form-list
+  openrosa-integrity