XLSForm Validation Checklist

An XLSForm validation checklist checks the workbook structure, question types, choice lists, expressions, media, and field workflow before a form reaches enumerators. Upload validation catches structural problems, but only a device pilot and test submission show whether the form works in real collection conditions.

For a fast first pass, run the browser-based XLSForm quick check, then complete this checklist and test representative submissions.

Use this page as the hub for the existing common XLSForm errors guide, constraint examples, and skip logic guide.

What should you check in the workbook first?

Work through the workbook before uploading it to ODK Central:

• The workbook contains the required survey sheet and uses the expected type, name, and label columns.
• The choices sheet contains every list referenced by select_one and select_multiple questions.
• The settings sheet has a stable form_id, a readable form_title, and a new version when the definition changes.
• Question and choice names contain no spaces and do not collide with another name in the same scope.
• Every begin group, end group, begin repeat, and end repeat row is paired and ordered correctly.
• relevant, constraint, calculation, and choice_filter expressions reference real names and use valid XPath syntax.
• Required questions are actually required by the study protocol and do not block legitimate skip paths.
• Translation columns, media filenames, and appearance values match the files and devices used in the study.

The XLSForm reference explains the core sheets and settings. Use the XLSForm question types reference when a type or widget is uncertain.

What does ODK Central validate during upload?

When Central receives an XLSForm, it converts the spreadsheet to an XForm and checks the conversion. Errors stop the upload. Warnings may require a decision before the draft can be created, depending on the upload path and the issue.

Central accepting the file is only the first gate. A form can convert successfully and still have confusing wording, an incorrect skip path, missing media, or a workflow that is too slow on a phone. The official Central forms guide explains the upload, draft, warning, and testing flow.

How do you debug a failed XLSForm?

Start with the first error and fix one category at a time. Later messages can be side effects of the same broken reference or sheet entry.

Error pattern	What to inspect	Related guide
XPath or variable reference failure	Compare every ${name} reference with the name column, including spelling and underscores	Common XLSForm errors
Duplicate name or form ID	Search the workbook and settings sheet for repeated identifiers	XLSForm common errors
Choice list not found	Match the list name after select_one or select_multiple with choices.list_name	Cascading selects
Invalid question type	Replace invented types such as number or dropdown with supported XLSForm types	Question types
Constraint never fires	Check whether the question is visible and whether the expression evaluates to true or false as intended	Constraint examples
Hidden question appears	Check the relevant expression and the exact value returned by the earlier question	Skip logic
Group or repeat error	Count the opening and closing structural rows and check their nesting	Repeat groups
Attachment or translation problem	Compare the filename, language column, and media reference with the files uploaded to the draft	Add languages in ODK

Do not change several unrelated parts of the form between tests. A small edit and a repeatable test make the cause easier to find.

How should you test an XLSForm in ODK Central?

Use a draft project or a draft form before publishing to field users:

1. Upload the workbook to Central as a draft.
2. Read every warning and decide whether it is expected or needs a fix.
3. Preview the form in a browser for a quick logic check.
4. Download it to the same type of device used in the field.
5. Complete one interview offline, including important skip paths, constraints, repeats, media, and translations.
6. Reconnect and send the finalized submission.
7. Inspect the record in Central and export the test data.
8. Compare the export columns and repeat tables with the analysis plan.
9. Publish only after the study team accepts the form and the field team knows which version to use.

For the production cutover, follow the ODK Central form versioning guide. A version update should have a clear pilot, release time, and enumerator instruction. For the production cutover, follow the ODK Central form versioning guide and the ODK Central form release checklist. A version update should have a clear pilot, release time, and enumerator instruction.

What does validation not prove?

Validation checks syntax and compatibility. It does not prove that respondents understand the questions, that enumerators can follow the protocol, that a GPS reading is useful at the collection site, or that the study's consent and sampling procedures are sound.

Use the ODK Field Data Quality Toolkit to extend the review before, during, and after fieldwork. Its checks cover audit evidence, timing, GPS, identity, submissions, and documentation.

If the form creates or updates shared records, add the ODK Entities and longitudinal workflow to the test plan. Entity creation, access, updates, and offline conflicts need cross-form testing.

Can LooprAI help debug an XLSForm?

LooprAI can inspect an uploaded workbook, explain validation messages, and attempt repairs such as fixing references, question types, or list names. Treat the result as an editable draft. Review the changed rows, run validation again, and complete the Central device test yourself.

The common XLSForm errors guide shows the repair workflow, while How to Build an XLSForm with AI covers form creation from a description.

Validate and fix an XLSForm

Review common XLSForm errors