Form spec proposal: declare that submissions of a form should generate entities

We are starting development on adding an Entity concept to ODK Central! This will help users automate and organize workflows that involve visits over time.

An Entity represents a person, place or thing that Forms can be about and will be managed in Datasets by Central. Read more about the concepts and where we hope to go at Entity-based data collection.

Form definitions will be able to declare that they create Entities in a specific Dataset. Eventually they will also be able to update and archive entities but initially we are focusing on creation only.

This specification will be used by servers to generate entities when processing submissions. Initially, we will implement this in Central only. This means that Entity creation will require submitting to Central and then downloading back to clients. Eventually, Collect will use this spec to create offline Entities. Currently we expect that Enketo will always require a server round trip to use Entities.

Our proposed form specification is in this Google Doc. Please feel free to comment in this thread or directly inline. You can also take a look at a sample XLSForm. You may also find it helpful to see how this will be exposed from Central.

All of the proposed changes are additive and backwards-compatible: old versions of Collect, Enketo, Central and other compatible tools will happily ignore these additions and work as they do today.

Some questions to consider:

  • We've used the column name save_to for specifying the Entity Property name in XLSForm. Alternatives: entity_property, entity_prop. We are interested in feedback there.
  • We've used a node that is relevant or non-relevant for specifying the verb (create, update, archive) in XForms. We could also use an attribute with a boolean value. I believe this is a matter of aesthetic preference only but would be interested in feedback.
1 Like

We are getting ready to ship this functionality in Collect, Central and pyxform! Please take a look at the latest specification if this interests you.

We've changed this to saveto in the XForm spec for consistency with other bind attribute names (e.g. readonly). We're keeping save_to in XLSForm.

We've decided to use an attribute with a boolean value instead.

These initial releases are experimental and we will continue to consider changes if there's a strong reason for them.


The specification is now published as an extension to the ODK XForms spec. It has been implemented in Central and Collect for several months so we are now considering it stable. User documentation is here.