type name label hint required

relevant appearance default constraint constraint_message calculation

trigger choice_filter parameters repeat_count note image
audio video
list_name name label
form_title form_id version
20250502121009
 instance_name default_languastyle
0502121009
list_name label
 Getting started with XLSForms

- The XLSForm standard lets you create powerful forms for the ODK ecosystem.
- A form is defined using 4 sheets:
- The survey sheet defines the questions and logic for your form. It is required.
- The choices sheet defines choices to use in select questions.
- The settings sheet defines form metadata and configuration.
- The entities sheet is used to create entities from form values for use in longitudinal workflows, case ma

- The template sheets contain the most common columns. See the Translations and Additional columns she
- Hover over column names to see a note about how they can be used.
- Columns colored in green on the survey and choices sheets can be translated.

💡 Use File > Make a copy to make a copy of this template that you can edit
💡 Using a consistent column order makes it easier to copy and paste between different form definitions.
💡 Consider hiding columns you don't need instead of deleting them.

Resources
📖 ODK form design docs
🧵 XLSForm tutorial
💬 Forum for support
💡 Have ideas for improving this template? Share them here!

Credits
Styling ideas from yxf script
Inspiration from CartONG's XLSform cheat sheet

Changelog
12/5/2024 Add counter appearance
7/8/2024 Add masked appearance
7/1/2024 Add table-list, hidden-answer and printer appearances
2/13/2024 no-calendar appearance does not work for Enketo
1/29/2024 Add entity_id and update_if to "Additional columns", add table-list to appearances, add grid theme
11/2/2023 Add decimal and text numbers for thousands-sep appearance; add filters on types, appearances a
### Add Make a copy tip to readme
### v2023.1 release
 Last update License
12/5/2024 CC BY-SA

udinal workflows, case management, and more.

d Additional columns sheets for other columns.

ent form definitions.

earances, add grid theme reference

on types, appearances and additional columns sheets (thanks @wroos!)
Types

The survey sheet's 'type' column determines how the user will be prompted or what will be computed by the
💡 See the Appearances sheet to learn how to modify how a question is displayed to users

💡 The parameters column is sometimes used to configure aspects of a question type that are not appearance

Field type Description

text Prompt the user for a text response
integer Prompt the user for an integer response
decimal Prompt the user for a decimal response

note Show the user some text

Record the result of an expression specified in the
calculate
calculation column
select_one list_name Prompt the user to select one choice out of a list
Prompt the user to select multiple choices out of a
select_multiple list_name
list
Prompt the user to select one choice out of a list of
select_one_from_file file.extension
choices from a file
Prompt the user to select multiple choices out of a
select_multiple_from_file file.extens
list of choices from a file
Indicate the start of a group of questions that are
begin_repeat
repeated
Indicate the end of a group of questions that are
end_repeat
repeated
begin_group Indicate the start of a group of questions

end_group Indicate the end of a group of questions

geopoint Prompt the user to record a single point (a location)

geotrace Prompt the user to record a line of points

Prompt the user to record a polygon of points (first
geoshape
and last point are identical)
Record the highest-accuracy point within 20 seconds
start-geopoint
of creating the blank filled form
Prompt the user to select a value in an integer or
range
decimal range defined in the parameters column
image Prompt the user for an image

barcode Prompt the user to scan a barcode

audio Prompt the user to record or select audio

Record audio in the background while filling out the
background-audio
form
video Prompt the user to record or select a video

file Prompt the user to attach a file

date Prompt the user for a date response

time Prompt the user for a time response

datetime Prompt the user for a date and time response

rank Prompt the user to rank a list of choices

Attach a CSV to the form for querying. Specify its
csv-external
name without extension in the name column
acknowledge Prompt the user to acknowledge a statement

start Record the time when the blank filled form is created
Record the time the last time that the filled form is
end
finalized
today Record the date when the blank filled form is created
Record the install's unique ID (reset on uninstall or
deviceid
cache clear)
username Record the username

phonenumber Record the phone number stored in app settings

email Record the email stored in app settings

Log user's actions while filling out the form as an

audit
attached CSV
 what will be computed by the form 📋 Form with all question types
ed to users

n type that are not appearance-related

Collect mobile for Enketo web formParameters

Yes Yes
Yes Yes
Yes Yes

Yes Yes

Yes Yes

Yes Yes randomize, seed

Yes Yes randomize, seed

Yes Yes randomize, seed, value, label

Yes Yes randomize, seed, value, label

Yes Yes

Yes Yes

Yes Yes

Yes Yes
capture-accuracy, warning-
Yes Yes accuracy, allow-mock-
accuracy
Yes Yes

Yes Yes

Yes Yes

Yes Yes start, end, step

Yes Yes max-pixels

Yes No
quality (normal, low, voice-
Yes Yes only, external; defaults to
normal)
Yes No quality (normal, low, voice-only)

Yes Yes

Yes Yes
Yes Yes

Yes Yes

Yes Yes

Yes Yes

Yes Yes

Yes Yes

Yes Yes

Yes Yes

Yes Yes

Yes Yes

Yes Yes

Yes No

Yes No
location-priority, location-min-
interval, location-max-age,
Yes No
track-changes, track-changes-
reasons, identify-user
Appearances

Appearances configure how a question will be displayed to the user on their device
💡 Most appearances for the same question type can be combined by using a space-separated list

Appearance na Description
numbers Restrict input to numeric symbols but save the value as text
multiline Show a text area that is multiple lines tall
url Show a button to launch the website represented by this field
Add the Android app ID of a custom application after the ex:
ex:
prefix to launch that application
Automatically add locale-dependent thousands separators
thousands-sep
on screen but not in submissions
bearing Prompt the user to capture the device-reported compass direc
vertical Show a vertical range slider instead of the default horizontal s
no-ticks Hide tick marks for a range slider (can combine with vertical)
picker Show values in a range as a list of options that can be picked
rating Show values in a range as star ratings
new Only show the option to capture new media, not to select exis
new-front Only show the option to capture a new picture from front (sel
draw Prompt the user to draw an image
annotate Prompt the user to annotate (draw on) an image
signature Prompt the user to sign their signature
no-calendar Show date picker as spinners rather than a calendar
month-year Show date picker for month and year only
year Show date picker for year only
ethiopian Show date picker using the Ethiopian calendar
coptic Show date picker using the Coptic calendar
islamic Show date picker using the Islamic calendar
bikram-sambat Show date picker using the Bikram Sambat (Nepali) calendar
myanmar Show date picker using the Myanmar calendar
persian Show date picker using the Persian calendar
placement-map Show a map that the user can manually place and adjust a loc
Show a map that the user can capture device location on
maps
(but not manually adjust)
hide-input Show a larger map and hide geo input fields by default
minimal Show a text prompt that when tapped shows all choices
search Allow the user to search the list of available choices
quick Advance to the next screen immediately after a choice is sele
columns-pack Show available choices with as may as possible on one line
Show available choices in 2, 3, 4 or 5 columns depending on
columns
screen size
columns-n Show available choices in the specified number (n) of column
no-buttons Show available choices without radio buttons / check boxes
Show available choices mapped to the svg file specified in
image-map
the image column
likert Show available choices horizontally as a likert scale
Show available choices on a map using each choice's
map
geometry column
field-list Show all questions in the field list on the same screen
label Show only option labels to define the top row of a select grid
list-nolabel Show only radio buttons or checkboxes to define the inside of
list Show horizontal radio buttons or checkboxes with their labels
table-list Shortcut for building a grid of list and list-nolabel questions wit
hidden-answer Hides the scanned barcode value
printer Send the value of the question to the printer app for preview
masked Show asterisks (*) instead of what the user is entering
counter Show buttons for incrementing and decrementing
on their device
using a space-separated list

Type(s) used with Collect mobile formEnketo web forms

text Yes depends on browser
No (text boxes grow
text Yes
vertically as needed)
text Yes Yes
text integer decimal image
Yes No
audio video file
integer, decimal, text
Yes Yes
numbers
decimal Yes No
range Yes Yes
range Yes Yes
range Yes Yes
range Yes Yes
image audio video Yes depends on browser
image Yes depends on browser
image Yes Yes
image Yes Yes
image Yes Yes
date datetime Yes No
date Yes depends on browser
date Yes some desktop browsers
date Yes No
date Yes No
date Yes No
date Yes No
date Yes No
date Yes No
geopoint Yes Yes
geopoint Yes Yes
geopoint geotrace geoshap N/A Yes
all selects Yes Yes
all selects Yes Yes (select one only)
select_one select_one_from_ Yes No
all selects Yes Yes
all selects Yes Yes
all selects Yes Yes
all selects Yes Yes
all selects Yes Yes
select_one select_one_from_ Yes Yes
select_one select_one_from_ Yes No
Yes (only applies in
begin_group begin_repeat Yes
pages mode)
all selects Yes Yes
all selects Yes Yes
all selects Yes Yes
begin_group Yes Yes
barcode Yes No
text Yes No
text Yes No
integer Yes No
Relevance

Relevance determines whether a question will be displayed to a user or not. It lets you define branching or sk
💡 Apply relevance to groups or repeats to skip or show multiple questions at once
💡 You can use relevance on a note to provide additional guidance or to confirm a value that could possibly be
💡 You can meet almost any requirement with available functions

Example relevance expression

${q1} != ''
${age} < 18
${random_value} < 0.5
(${computed_months} >= 6 and $
{computed_months} < 24) or (${months} >= 6
and ${months} < 24)
selected(${q1}, 'nurse')
selected(${q1}, -88) or selected(${q2}, -88) or
selected(${q3}, -88)
${q1} < 12.5 or selected(${q2}, 'y')
not(selected(${q2}, 'b'))
string-length(${q1}) > 3

false()
on will be displayed to a user or not. It lets you define branching or skip logic in your forms.
o skip or show multiple questions at once
ovide additional guidance or to confirm a value that could possibly be out of range
with available functions

Description
This question will appear if q1 was not blank
This question will only appear if previously-entered age was less than 18
If ${random_value} is a calculate with calculation once(random()), this question will be
shown half the times that this form is launched
Conditions can be combined using and, or
This question will only appear if 'nurse' was selected in q1
This question will appear if -88 was selected in any of q1, q2 and q3
This question will appear if q1's value was less than 12.5 or if 'y' was selected in q2
This question will appear if 'b' was not selected in q2
This question will appear if the answer to q1 had more than 3 characters
This question will never appear. This can be useful when creating a form that is
intended to be customized for different environments. Questions or sections that are
optional can be marked as non-relevant in the template.
Constraints

Constraints limit the answers allowed in a field.

💡 Constraints are not evaluated if the answer is blank. To require answers, make the question required.
💡 You can meet almost any requirement with available functions

Example constraint expression

. <= 10
. > 10.51 and . < 18.39
string-length(.) > 5
. >= today()
. >= date('2015-08-01')
count-selected(.) <= 3
not(selected(., 'none') and count-selected(.) > 1)

if(selected(., 'none'), count-selected(.) = 1, true())

if(selected(., 'none'), count-selected(.) = 1, count-selected(.) = 2)

regex(., '^[A-Za-z]{0,6}$')

regex(.,'^[A-Z]{3}+_+[A-Z]{3}+_+[0-9]{4}+_+[0-9]{3,4}$')

regex(., '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[a-zA-Z]{2,4}$')

regex(.,'^\(?[0-9]{3}\)?-?[0-9]{3}-?[0-9]{4}$')

. = 9999 or (selected(${q1}, 'yes') and . <= 0) or (selected(${q1}, 'no') and .

ire answers, make the question required.

Description
Answer must be a number less or equal to 10
Answer must be a number between 10.51 and 18.39, excluding those values
Answer must be longer than 5 characters
Answer must be a date today or later
Answer must be a date August 1st 2015 or later
Answer to this multi select question can only include 0, 1, 2 or 3 choices but no more
Answer to this multi select question may not include both 'none' and other selections
Another way of expressing the same concept as above: if the 'none' choice is selected, the total
number of choices selected must be 1. Otherwise, any number of selections is allowed. Replace
true() with another expression to specify a requirement when 'none' is not selected
Answer to this multi select question can either be 'none' or exactly two choices not including 'none'
Answer to this text question may have up to 6 letters
Answer must respect a specific structure (for example this one allows the following :
CAR_PRC_2015_048)

Answer to this text question must have an email address structure (note: this is not exact but filters out obviously-wrong inputs)

Answer to this text question must have a North American phone number structure
The answer 9999 is always accepted to represent 'unknown'. Otherwise, this question's answer
depends on ${q1}'s answer: if ${q1} was 'yes', then this answer must be a negative number. If ${q1}
was 'no', this answer must be a positive number.
Translations

XLSForms can be translated into multiple languages.

💡 The text on navigation buttons and other system elements are translated as part of the application that sho
💡 Form titles can't be translated.
💡 We recommend that you design your form in one language, test it extensively, and then translate it.
💡 You can specify a default language in the settings sheet.
⚠️There is no fallback language. Specify a translation for every column used in the form. Otherwise, a dash (
⚠️If you use the choices sheet, make sure that all of its text and media columns have translations for all lang

Add new language

Duplicate all columns that have user-facing text or media to add new language.
These are highlighted in the survey and choices sheets:

label
hint
guidance_hint
constraint_message
required_message
image
audio
video

language name and code

For each language that you need, add the language name and the language code after a :: separator.
You must do this for every column with text or media. Find language codes.
The language name is what data collectors will see. We generally recommend using the language name in th

label::Español (es)
hint::Español (es)

Example with English and Spanish translations

survey
type name label::English (enlabel::Español (

choices
list_name name label::English (enlabel::Español (
as part of the application that shows your form, not as part of the form definition.

vely, and then translate it.

d in the form. Otherwise, a dash (-) will be shown for text that is not translated to the current language.
mns have translations for all languages.

e code after a :: separator.

nd using the language name in the language itself.

hint::English (ehint::Español (e image::English ( image::Español (es)

image::English image::Español (es)

ent language.
List lookups

You can look up values from lists specified in the choices sheet, entity lists, attached CSVs, attached geoJSON
💡 Choice filters, used to filter lists of items for use in selects, are the same as filter expressions
💡 These queries use a subset of the XPath language. ${} expressions get translated to XPath to access fields

instance('list_name')/root/item[filter expression]/desired_property

list_name The name of the list to get value(s) from

filter expression An expression for filtering the items in the list. You can filter the list down to one single it
property The property you want to access for items that match the filter

Common type of lookup

The most common type of query looks a single item up based on one property and gives back another prope

instance('list_name')/root/item[match_property = ${q1}]/desired_property

list_name The name of the list to get value(s) from

match_property The property used to look up an item
${q1} A value used to look up the item (e.g., a unique id)
desired_property The property whose value is returned

Example query
instance('crops')/root/item[name = ${crop}]/average_yield
instance('days')/root/item[number = ${day_number}]/blood_pressure_needed

instance('data_collectors')/root/item[name = ${data_collector_id}]/visits_com

instance('houses')/root/item[name = ${hhid}]/geometry

count(instance('participants')/root/item[answered = 'no']/label)

sum(instance('patients')/root/item[birth_year > 1978][gender = 'female']/chil

instance('children')/root/item[household = ${hhid}][number = position(..)]/fi

💡 You can use these expressions with repeats, too. For example, if ${repeat} is a repeat in your form, you ca
${repeat}[filter expression]/desired_field to access a field in a repeat instance or

💡 If you are looking values up in an attached CSV, you can also use the pulldata
pulldata(list_name, desired_property, match_property, ${q1})

The pulldata expression above is equivalent to:

instance('list_name')/root/item[match_property = ${q1}]/desired_property
ity lists, attached CSVs, attached geoJSON files and attached XML files by using the instance function.
e same as filter expressions
ns get translated to XPath to access fields in the form

You can filter the list down to one single item or multiple. Filter expressions can use functions and any other logic.
match the filter

ne property and gives back another property's value

ed_property

Description
In a list of crops, use a previously-entered crop name to look up that crop's
average yield.
In a list of days, use a previously-entered day number to look up whether or
not blood pressure needs to be entered that day.
In a list of data collector, use a previously-entered data collector id to look
up how many visits the data collector completed.
In a list of houses, use a previously-entered household id to look up the
geometry (location) of that house.
Filter a list of participants to only those who have not answered yet. Count
the number of matches.
Filter a list of patients to only those with birth year greater than 1978, then
filter that list to females only, then get the child count for each of them. The
full expression computes the sum of all children of females born after 1978.
Get the first name of the Nth child in a household with id ${hhid} where N
is the position of the current repeat in the list of all repeat instances.

${repeat} is a repeat in your form, you can write

eld in a repeat instance or sum(${repeat}[filter expression]/desired_field) to get the sum of all repeat instances t

the pulldata function. In Collect, this may have better performance for lists with many tens of thousands of elements.

red_property
e function.

ns and any other logic.

he sum of all repeat instances that match the filter.

ns of thousands of elements.
Additional columns

The default survey, choices, settings and entities sheets include the most common columns. You may find it useful to add s

survey
sheet

save_to

guidance_hint

required_message

read_only

instance::my_attribute
bind::my_attribute
body::my_attribute
choices
sheet
image
audio
video

geometry

settings
sheet
public_key
submission_url

allow_choice_duplicate

entities
sheet
create_if
entity_id
update_if
lumns

s, settings and entities sheets include the most common columns. You may find it useful to add some of the columns described below.

Collect mobile for

When using Entities, used to specify the Entity property to save the form field's
Yes
value to
Used to display additional information to data collectors in a way that is less visible
Yes
than hints
A custom message to replace the generic message when a required value is not fille Yes

An expression used to determine whether the question's value can be edited or not Yes

A custom instance attribute which will be included along with its value in submitted d Yes
A custom bind attribute. Generally used when an application has a special custom fe Yes
A custom body attribute. Generally used when an application has a special custom f Yes

An image to show with this choice Yes

An audio file to show with this choice Yes
A video file to show with this choice Yes
A special column that represents a choice's point, trace or shape to be displayed
Yes
on a map with the map appearance

Public key for encrypting form instances when your server is not trusted Yes
Specify a URL to make submissions to regardless of how the app is configured Yes
Add with 'yes' value if you want a single list on the choices sheet to have multiple
Yes
choices with the same name

A condition that a filled form must meet for an entity to be created from it Yes
The id of the entity that should be updated by filling this form Yes
A condition that a filled form must meet for an entity to be updated from it (with entity Yes
columns described below.

Enketo web formTranslatable

Yes N/A

Yes Yes

Yes Yes
Static values only
N/A
(yes/no)
Yes N/A
Yes N/A
Yes N/A

Yes Yes
Yes Yes
Yes Yes

No N/A

Yes N/A
No N/A

Yes N/A

Yes N/A
Yes N/A
Yes N/A