We have now updated the XLSForm model based on feedback to simplify the entities sheet and to make it clearer on the survey sheet which save_to belongs to which Entity. Our current plan is for XLSForm to allow any number of rows on the entities sheet as long as the list_name column value is unique across them. In other words, a submission will be able to create or update many Entities and the only way to write to multiple Entities in the same list will be to use a repeat.
This means we will remove the undocumented repeat column from the entities sheet. @Lindsay_Stevens_Au is working on the pyxform implementation and we are hoping it will be available with or shortly after the Collect v2026.1.0 release.
Updated spec
The entities sheet MAY include multiple Entity declaration rows, provided that no two rows reference the same list_name.
If the entities sheet has more than one Entity declaration, then each save_to value on the survey sheet MUST be prefixed with a list_name followed by #, where the prefix matches a list_name in the entities sheet.
Example:
households#hhid
participants#first_name
The portion after # is the Entity property name. It is not valid to have save_tos with different list prefixes directly in the same group or repeat. See more in the XForms spec and the pyxform issue.
Sample form
entities sheet for a form that creates Entities in the households and participants lists:
| list_name | label |
|---|---|
| households | ${hhid} |
| participants | concat(${first_name}, " ", ${last_name}, "(", ${hhid}, ")") |
survey sheet:
| type | name | label | save_to | calculation |
|---|---|---|---|---|
| text | hhid | Household ID | households#hhid | |
| geopoint | hh_location | Household location | households#geometry | |
| begin_repeat | member | Member | ||
| text | first_name | Member first name | participants#first_name | |
| text | last_name | Member last name | participants#last_name | |
| calculate | member_hh | participants#hhid | ${hhid} | |
| calculate | hh_link | participants#hh | ../../meta/entity/@id | |
| calculate | member_id | ../meta/entity/@id | ||
| end_repeat | member |
For now, we have decided not to do any automatic relationship discovery. We are starting design work on a way to state from Central that certain properties represent links between Entities and will share those proposals shortly. This will be important for performance.
We also intend to provide a way from XLSForm to more easily reference an Entity's id, likely something like <list name>#__id (households#__id) instead of ../meta/entity/@id which will be even harder to write since pyxform will decide where to put the meta/entity block.