complete guide · EN

Building a questionnaire
from scratch, cell by cell.

XLSForm is the standard that turns an ordinary spreadsheet into a full digital form — with skip logic, validation, GPS, photos and multiple languages — ready to run on ODK Collect, KoboToolbox or Enketo. This guide builds a household survey step by step and documents every question type and setting, with examples you can copy and convert with rxform.

1 · Anatomy of an XLSForm

An XLSForm is an .xlsx file (or .xls/.ods) with up to three main sheets:

• survey — the questions, in the order they appear. Minimum columns: type, name and label.
• choices — the option lists for multiple-choice questions. Minimum columns: list_name, name and label.
• settings — title, identifier, version, default language and other form-wide settings (a single data row).

Golden rules for the name column (questions, groups and choices alike):

2 · Your first form

The smallest useful form has three rows on the survey sheet:

The question on row 4 uses the yes_no list, defined on the choices sheet:

And the settings sheet gives the form its identity:

Convert and you are done:

$ rxform household_survey.xlsx
household_survey.xml

3 · Every question type

Text and numbers

• text — free text. For taller boxes use parameters = rows=5.
• integer / decimal — numbers, with the numeric keypad on the device.
• range — a slider; bounds via parameters = start=0 end=10 step=1. With appearance = rating it becomes stars.

Dates and times

Useful appearances for date: month-year, year and no-calendar.

Choices and lists

• select_one LIST — one answer. appearance: minimal (dropdown), likert, quick (auto-advance), columns…
• select_multiple LIST — several answers; stored space-separated, which is why choice names cannot contain spaces.
• rank LIST — the respondent orders the options.
• select_one LIST or_other — appends an “Other” option plus an automatic “Specify other.” question.

Extra columns on the choices sheet are allowed and become choice data — the basis of cascading filters:

Cascading selects (choice_filter)

In the filter, list columns appear by name (state) and earlier answers as ${state}. To shuffle options: parameters = randomize=true (add seed=42 for a reproducible order).

Location

geopoint captures a point (with target accuracy in meters via parameters); geotrace, a line; geoshape, a closed polygon.

Media and files

image with appearance = signature becomes a signature pad; draw, free drawing. max-pixels shrinks photos on the device.

Notes and acknowledgements

• note — displayed text, no answer. Accepts ${references}: “Thank you, ${interviewer}!”. It is the only type that can omit name (rxform generates one).
• acknowledge — requires an explicit “ok” from the respondent.

Invisible fields

calculate computes a value with XPath (functions like if(), concat(), selected(), count(), round()…); hidden holds a value fillable via default or integrations.

Metadata — collected on its own

• start/end — timestamps for opening/finishing the form; today — the date; deviceid, username, phonenumber, email — device/account identification.
• audit — an audit trail of the filling session; with parameters = location-priority=balanced location-min-interval=60 location-max-age=120 it also logs location during the interview.
• start-geopoint — silently captures location on open; background-audio records the interview audio; background-geopoint captures location when the trigger question is answered.

4 · Form logic

All logic uses ${name} to reference earlier answers.

relevant — skipping questions

The question only appears when the expression is true. Combine conditions with and/or; for multi-selects use selected(${services}, 'water').

constraint — validating answers

The dot . is the answer itself. The message shows when the rule fails.

required, default, read_only

• required = yes (or an expression) blocks advancing without an answer.
• default takes a fixed value (42) or a dynamic expression (today(), ${state}) evaluated when the form opens — including ${last-saved#tract} to inherit the last submission’s value.
• read_only = yes shows the field without allowing edits.

trigger — recalculating on change

With trigger, the field is (re)set whenever the referenced question changes — here, clearing children when household_size is edited. If a calculation is present, it runs at that moment (instead of continuously).

5 · Groups, repeats and loops

Groups

• appearance = field-list shows the whole group on one screen.
• table-list — for a run of select_ones sharing a list, renders a matrix (rows × columns).
• A group’s relevant applies to everything inside it.

Repeats

The block repeats once per resident. Without repeat_count the interviewer adds repetitions manually; with an expression (or fixed number) the count is automatic. Inside a repeat, use position(..) for the current index and indexed-repeat() to read values from another repetition.

Loops over a list

Generates one block per option of the services list, substituting %(label)s and %(name)s with each option’s label/name — one question “How do you rate the Water service?”, another “…the Sewage service?”, and so on.

6 · Multiple languages

Just suffix the translatable columns with ::Language (code): it works for label, hint, guidance_hint, constraint_message, required_message, image, audio and video — on both the survey and choices sheets. Set the starting language in settings → default_language = English (en). The app gains a language menu.

Per-question media: the image/audio/video columns attach files (e.g. answer_card.jpg) shipped with the form.

7 · Appearances (appearance)

8 · Parameters (parameters)

The parameters column takes space-separated key=value pairs:

9 · The settings sheet

10 · External data and entities

Big lists in files

The CSV needs name and label columns (or point at others with parameters = value=code label=description); GeoJSON uses id/title and enables appearance = map. The file is uploaded to the server with the form.

Lookups with pulldata()

Looks up the target column in targets.csv for the row where tract = the answer. There is also ${last-saved#field} (the last saved submission’s value) and the entities sheet, which lets a form create and update registries shared across forms (e.g. register households on one visit and find them again on the next) — with save_to on questions and create_if/update_if/label on the sheet.

11 · Common errors — and how rxform warns you

• Misspelled type → [sheet 'survey', row 3, column 'type'] unknown question type 'integr' — did you mean 'integer'?
• Broken reference → '${agge}' does not match… — did you mean 'age'?
• Missing choice list → points at the row and suggests the closest list.
• Unclosed group → points at the begin_group row and asks for the end_group.
• Duplicate sibling names, names with spaces/accents, visible questions without a label, repeated options in a list — all with sheet, row, column and probable cause.

12 · Convert and publish

# converter
$ rxform household_survey.xlsx
household_survey.xml

# conferir erros de autoria é só rodar — a mensagem aponta a célula
$ rxform pesquisa_domiciliar.xlsx --stdout > /dev/null

1. KoboToolbox: upload the .xlsx itself (Kobo converts server-side with pyxform — rxform produces exactly the same XML, so it doubles as instant local validation) or deploy the XML via API.
2. ODK Central: publish the .xlsx or the generated .xml; attach external-list CSVs/GeoJSON.
3. Enketo: published forms automatically get a web link.

guide · rxform — back to home · official xlsform.org reference