Authoring data collection forms in Excel for mobile surveys. XLSForm converts Excel files to XForms for ODK, KoBoToolbox, and similar platforms. Use for field surveys, data collection, conditional forms, GPS tracking, and offline data gathering.
/plugin marketplace add mberg/claude-skills/plugin install mberg-observable-plot@mberg/claude-skillsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
examples.mdreference/TABLE_OF_CONTENTS.mdreference/appearances.mdreference/best-practices.mdreference/calculations.mdreference/cascading-selects.mdreference/choices-sheet.mdreference/common-errors.mdreference/constraints.mdreference/creating-xlsforms.mdreference/external-data.mdreference/multilingual.mdreference/question-types.mdreference/settings-sheet.mdreference/skip-logic.mdreference/survey-sheet.mdreference/xpath-expressions.mdscripts/convert_to_xform.pyscripts/create_xlsform.pyscripts/validate_xlsform.pyXLSForm is a simple, human-friendly form standard that lets you design data collection forms in Excel. Your forms convert to XForm (XML) and work with mobile platforms like ODK Collect, KoBoToolbox, SurveyCTO, and Enketo. Perfect for surveys, GPS tracking, offline data gathering, and complex conditional logic.
relevant column shows/hides questions based on previous answers.calculate question type and calculation column compute derived values.Survey Sheet:
| type | name | label |
|---|---|---|
| text | respondent_name | What is your name? |
| integer | age | How old are you? |
| select_one yes_no | consent | Do you agree? |
| calculate | timestamp | now() |
Choices Sheet:
| list_name | name | label |
|---|---|---|
| yes_no | yes | Yes |
| yes_no | no | No |
This creates a 3-question form with a hidden timestamp calculation.
| Aspect | Limit | Note |
|---|---|---|
| Question name | 255 chars | Alphanumeric + underscore only |
| Label/hint | No hard limit | Practical: keep under 500 chars |
| Choices per list | No hard limit | ~100+ works well |
| Calculation expression | ~2000 chars | Complex expressions may slow form |
| Form size | No hard limit | Very large forms (500+ questions) may be slow |
| Languages | Unlimited | Use label::language, hint::language syntax |
Detailed documentation organized by topic:
Form Structure:
Questions & Types:
Logic & Calculations:
relevantcalculate type and calculation columnconstraint columnAdvanced Features:
Best Practices & Troubleshooting:
Navigation:
See examples.md for 6 complete, working XLSForms:
When asked to create an XLSForm, output a properly structured Excel file (.xlsx):
Required worksheets:
Format:
scripts/create_xlsform.py to generate .xlsx from CSVExample output structure:
# survey worksheet
| type | name | label | hint |
|------|------|-------|------|
| ... | ... | ... | ... |
# choices worksheet
| list_name | name | label |
|-----------|------|-------|
| ... | ... | ... |
# settings worksheet (optional)
| form_title | form_id | version |
|------------|---------|---------|
| ... | ... | ... |
See creating-xlsforms.md for detailed instructions on generating forms.
python scripts/validate_xlsform.py form.xlsx to check structurerelevant column with XPath expressions${age} >= 18, selected(${previous_answer}, 'option')calculate question type for hidden computed valuescalculation column for visible computed fieldspython scripts/validate_xlsform.py form.xlsx # Check Excel structure
python scripts/convert_to_xform.py form.xlsx # Convert and validate XForm output
Form Design:
Performance:
Validation:
validate_xlsform.py before conversionconstraint_message to tell users why an answer is invalidMultilingual Forms:
label::English and label::French syntaxSee best-practices.md for detailed patterns and recommendations.
Parse errors when converting?
validate_xlsform.py first—it catches structural issues earlyname fields are alphanumeric + underscore onlyForm displays wrong on mobile?
appearance column to customize widgetsCalculations not working?
${variable_name} syntax inside expressionsChoice lists not showing?
list_name in survey matches list_name in choices sheet (case-sensitive)validate_xlsform.py to verify all referencesSee common-errors.md for a comprehensive troubleshooting guide.
XLSForm syntax evolves but maintains backward compatibility. Most forms work across versions 4.0–7.1+. Check TABLE_OF_CONTENTS.md for version-specific features.
validate_xlsform.py to check structureUse when working with Payload CMS projects (payload.config.ts, collections, fields, hooks, access control, Payload API). Use when debugging validation errors, security issues, relationship queries, transactions, or hook behavior.