Hi @haidarz, thanks for proposing this change. Would you please help me understand how root/item is the best (most consistent) XPath syntax for referencing entire submissions, as opposed to items in a choice list? If you could reference some existing documentation or, as you’ve mentioned, pyxform code, I would very much appreciate it. I’ve done my own research, which I’ve described below, but that lead me to conclude that our use of root/data is correct.
The ODK XForms specification has a section on secondary instances that does provide an example XPath with root/item:
instance('cities')/root/item[country='nl']
However, it’s important to note that the queried XML here is a list of choices, where each choice is an <item>, not entire submissions:
<instance id="cities">
<root>
<item>
<itextId>static_instance-cities-0</itextId>
<country>nl</country>
<name>ams</name>
</item>
<item>
<itextId>static_instance-cities-1</itextId>
<country>usa</country>
<name>den</name>
…
</instance>
The only place I’ve found so far that discusses querying XML of entire submissions is “External XML data” on xlsform.org, which uses count(instance('houses')/house[rooms = current()/../rooms ]) to find the number of houses that have a certain number of rooms. Example XML is not provided there, but it would be called houses.xml and could look like:
<root>
<house>
<id>123</id>
<rooms>2</rooms>
<condition>good</condition>
<occupied>yes</occupied>
</house>
<house>
<id>456</id>
<rooms>3</rooms>
<condition>fair</condition>
<occupied>no</occupied>
</house>
</root>
In this case, <house> is definitely what the “dynamic data attachments” feature would call <data>: it’s an entire submission describing a particular house. We could have offered to let people configure the name instead of hard-coding <data>, but the feature was already complex enough, with UX challenges that you were eager to point out in your first post.
Furthermore, my understanding of the root/item convention is that it came from the XForm specification itself:
| element | description |
|---|---|
<item> |
Child of <select> or <select1> or <odk:rank> that defines an choice option. As in XForms 1.0. |
<itemset> |
Child of <select> or <select1> or <odk:rank> that defines a list of choice options to be obtained elsewhere (from a secondary instance). As in XForms 1.0. |
<value> |
Child of <item> or <itemset> that defines a choice value. As in XForms 1.0. |
It’s true that you can use the “dynamic data attachments” feature to populate choice lists for select questions, but that’s only one of many use cases for the feature. If an <item> by definition exists only within a <select> or a <select1>, then it’s not appropriate for us to call the node enclosing an entire submission <item>. Additionally, if you search https://getodk.github.io/xforms-spec/ for <data, omitting the closing bracket intentionally, you’ll see several examples of <data> being the first child node of <instance>. An illustrative one is the first complete XForm they provide:
<?xml version="1.0"?>
<h:html xmlns="http://www.w3.org/2002/xforms"
…>
<h:head>
<h:title>My Survey</h:title>
<model>
<instance>
<data id="mysurvey" orx:version="2014083101">
<firstname></firstname>
<lastname></lastname>
<age></age>
<orx:meta>
<orx:instanceID/>
</orx:meta>
</data>
</instance>
…
Based on this, I maintain that our use of <data> in the “dynamic data attachments” feature is correct and consistent with ODK specifications and documentation. Of course, I am certainly open to being proven wrong, and I do want to thank you again for contributing to KoBoToolbox—especially going so far as to write code and open a PR.
