XLSForm in one sentence
An XLSForm is a spreadsheet file (Excel or Google Sheets) describing a questionnaire according to a precise convention, organised into three sheets: survey, choices and
settings. That file is then compiled into XForms, the XML format the collection apps actually read: KoboCollect, ODK Collect or the web engine Enketo.
This page describes the format : its syntax, its sheets, its question types. If your question is really about the ecosystem, who does what between XLSForm, Kobo and ODK and which one you install, that is covered separately in XLSForm, Kobo, ODK: who does what (in French).
The three sheets of an XLSForm
1. survey, the questions
The backbone of the form: one row per question or structural element.
| type | name | label | relevant | constraint |
|---|---|---|---|---|
| select_one yes_no | received_aid | Did you receive the assistance? | ||
| integer | amount_received | Amount received (XOF) | ${received_aid} = 'yes' | . >= 0 |
2. choices, the answer options
The lists used by choice questions (select_one, select_multiple), grouped by list_name.
| list_name | name | label |
|---|---|---|
| yes_no | yes | Yes |
| yes_no | no | No |
3. settings, the form configuration
Title, identifier, version and default language of the questionnaire.
| form_title | form_id | version | default_language |
|---|---|---|---|
| PDM Cash ECHO | pdm_cash_echo_2026 | 202607241 | en |
Common question types
- text : a short free-text answer.
- integer / decimal : a numeric value.
- select_one / select_multiple : single or multiple choice, defined in
choices. - date / dateTime : a date picker.
- geopoint : GPS coordinates captured automatically.
- image / audio : an attachment captured on the device.
- note : displayed text with no answer expected, for instructions and transitions.
- calculate : a value computed from other answers, invisible to the enumerator.
Skip logic and constraints
Two columns with very different jobs, and they are constantly confused:
relevant: controls whether the question appears. If the condition is false, the question is hidden and skipped. This is the skip logic.constraint: controls whether an answer is valid. The question stays on screen, but the answer is refused until the condition is satisfied.
For example: relevant: ${received_aid} = 'yes' only shows « Amount received » when the previous answer was « Yes ». constraint: . >= 0 refuses a negative amount.
Groups and repeats
begin_group / end_group bracket related questions, for example a « food security » module. begin_repeat / end_repeat repeat a block a variable number of times, typically to list household members one by one.
Multiple languages
A single XLSForm can carry several languages: duplicate the columns label as label::English (en), label::Français (fr), and so on. The enumerator picks the language when opening the form, with no second file.
Common mistakes
- Inconsistent variable names : a typo in a
namesilently breaks every reference pointing at it. list_namemisspelled : a choice list that cannot be found makes the question invisible, with no clear error.- Untested cascading skip logic : a complex form with many nested
relevanthas to be tested path by path, not just question by question. - Missing columns : an incomplete
settingssheet (noform_id) sometimes blocks the import silently.
XLSForm glossary
survey- The sheet holding the questions and the structure of the form.
choices- The sheet holding the answer options, grouped by list.
settings- The sheet holding the form's global settings: title, id, language.
relevant- The condition deciding whether a question is shown. This is the skip logic.
constraint- The condition deciding whether an answer is valid.
calculation- The formula used by a
calculate. - XForms
- The compiled XML format, which is what the collection apps actually read.
Frequently asked questions
What exactly is an XLSForm?
An XLSForm is a spreadsheet file (Excel or Google Sheets) describing a questionnaire according to a precise convention: three sheets named survey, choices and settings. The file is then compiled into XForms, the XML format read by collection apps such as KoboCollect or ODK Collect.
What is the difference between relevant and constraint?
relevant controls whether a question is SHOWN, which is the skip logic: if the condition is false, the question is hidden and skipped. constraint controls whether an answer is VALID: the question stays on screen, but the answer is refused until it satisfies the condition.
Can an XLSForm be generated without knowing its syntax?
Yes. Generators such as Opti's XLS Form Builder produce a complete XLSForm from a plain-language description (« a cash PDM for ECHO »), with sections, skip logic and answer options already written in the correct syntax, ready to edit and import.
Does an XLSForm work on both Kobo AND ODK?
Yes, in the overwhelming majority of cases. XLSForm is precisely the format shared between KoboToolbox, ODK and SurveyCTO, which is what makes a questionnaire portable from one platform to another without rewriting.
Generating an XLSForm with Opti'
Opti' writes the XLSForm syntax for you: describe your survey, and Opti Gemba generates a complete file, with sections, skip logic, constraints and languages, ready to import into Kobo or ODK.
You can also skip the file entirely: by connecting your KoboToolbox account to Opti', the questionnaire goes straight to your Kobo server, and the submissions come back into Opti' with no export in between. The steps, API token included, are set out in the Kobo connection guide.
