Add documentation for integrity URL

README.md

@@ -20,6 +20,12 @@ Please [file an issue](https://github.com/getodk/docs/issues) if you can't find
 
 We highly recommend you use a virtual environment like [`virtualenv`](https://virtualenv.pypa.io/en/stable/). If you need to use different versions of Python, we recommend [`pyenv`](https://github.com/pyenv/pyenv).
 
+You can also use Docker to build and view the docs:
+
+```bash
+make autobuild-docker
+```
+
 ### Cloning the repo
 
 Clone the docs repo and make sure all the requirements are installed:

docs/conf.py

@@ -45,7 +45,8 @@
     'openapi',
     'sphinxext.opengraph',
     'notfound.extension',
-    'sphinx_sitemap'
+    'sphinx_sitemap',
+    'myst_parser'
 ]
 
 # If using Apple Silicon, set env variable (assumes brew install of enchant)
@@ -148,4 +149,4 @@
     'incl/form-examples/regex-middle-initial/',
     'incl/form-examples/sum-to-count-responses/',
     'search/'
-]
+]

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. This is optional, but must be present if the media file has the ``type`` attribute with the value ``entityList``.
 
 ``<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

requirements.txt

@@ -13,3 +13,4 @@ pyyaml
 sphinxext-opengraph
 sphinx-notfound-page
 sphinx-sitemap
+myst-parser