XLSForm Mapping - MQUAD Platform

MQUAD is XLSForm-compatible. Every logic feature described in this section maps to a standard XLSForm column, and importing/exporting an XLSForm file preserves them. This page documents the mapping and clearly separates standard XLSForm behaviour from MQUAD-specific extensions.

Column mapping

MQUAD feature	XLSForm column	Sheet	Example
Validation	`constraint`	survey	`. >= 18`
Validation message	`constraint_message`	survey	`Age must be at least 18`
Skip logic	`relevant`	survey	`${age} >= 18`
Default value	`default`	survey	`#country#res_num`
Calculation	`calculation`	survey	`${q1} + ${q2}`
Required	`required`	survey	`yes` / `true`
Choice filtering	`choice_filter`	survey	see below
Extra accepted choices	`additional_values`	survey	`98, 9997`

Example survey sheet

type	name	label	required	relevant	constraint	constraint_message	calculation	default
`date`	`dob`	Date of birth	yes
`calculate`	`age`	Age					`age(${dob}, ${interview_date})`
`integer`	`adult_income`	Monthly income		`${age} >= 18`	`. >= 0`	Income cannot be negative
`text`	`psu_id`	PSU Identifier						`#country#res_num`
`select_one`	`satisfaction`	Satisfaction	yes

Import behaviour

When importing an XLSForm file, MQUAD automatically:

Expands regex shortcuts — regex=email becomes the full regex(., '^...$') expression.
Corrects common syntax — bare & becomes and, bare | becomes or, bare comparisons like >=10 gain the . prefix.
Validates field references — every ${name} is checked against existing questions.
Detects circular dependencies — chains like Q1 → Q3 → Q4 → Q1 are flagged and blocked.
Preserves extra columns — non-standard columns are kept through the round-trip.

Standard XLSForm behaviour

The following are standard XLSForm/ODK columns and behave as defined by the XLSForm specification:

relevant — XPath expression controlling visibility (skip logic).
constraint — XPath expression that must evaluate true for the answer to be accepted.
constraint_message — the message shown when the constraint fails.
calculation — XPath expression producing a value for calculate-type questions.
default — initial value expression.
required — whether an answer is mandatory.
choice_filter — filters the choices of a select question based on another question's value.

These columns use standard XPath/ODK expression syntax: and/or/not(), comparison operators, . for the current value, and standard ODK functions like selected(), count-selected(), concat(), today(), now(), if(), regex(), int(), number(), and so on.

MQUAD-specific extensions

The following are MQUAD extensions — they work inside MQUAD but are not guaranteed to work in other ODK tools:

`additional_values`

An MQUAD extension column on the survey sheet for select_one / select_multiple questions. Lists comma-separated extra accepted values beyond the defined choices (e.g. 98, 9997 for "Don't know" / "Refused"). Values are deduplicated against the choice list at render time.

Regex shortcuts

Designer-only shortcuts (Email Format, 10-Digit Mobile, Numbers Only, Money (1 decimal), Letters Only, Letters & Numbers) that expand to full regex(., '...') expressions. On import, a regex=email style shortcut expands automatically.

MQUAD calculation functions

The frozen calculation functions are MQUAD extensions. They are not part of the standard ODK function set:

Function	Standard ODK?
`date-diff`, `date-add`, `date-subtract`	MQUAD extension
`day`, `month`, `year`, `day-of-week`	MQUAD extension
`time-diff`	MQUAD extension
`age`, `age-months`, `age-days`	MQUAD extension
`gestational-weeks`, `gestational-days`, `gestational-total-days`	MQUAD extension
`bmi`	MQUAD extension

Standard ODK functions (selected, count-selected, concat, if, today, now, days-between, duration, regex, int, number, and the numeric sum/min/max/round/abs/pow, string string-length/contains/ starts-with/ends-with/replace/join/string, coalesce, uuid, random, once, selected-at, count) map to their standard counterparts.

A form that uses only standard columns and functions can round-trip through other XLSForm tools. A form that uses MQUAD extension functions will still work in MQUAD but the extension functions may not be recognized elsewhere — plan accordingly if you need to share the form.

`format-date` format strings

MQUAD accepts %Y %y %m %d %b %B %H %M %S placeholders (e.g. '%d/%m/%Y'). This is an ODK-style format; other tools may differ in the details.

Choice constraints (per-choice)

Beyond choice_filter, MQUAD supports a per-choice constraint column in the choices sheet. Each choice whose constraint evaluates false is hidden:

list_name	name	label	constraint
`score_level`	high	High	`score >= 26`

The two mechanisms compose: choice_filter filters by extra-column values first, then each choice's constraint is evaluated. A choice is shown only when both pass. See the Survey Designer page for the full details.

Notes on round-tripping

MQUAD stores skip logic in the internal format ${age} >= 18 and ${married} = 'yes'. When you export to XLSForm, relevant is written in standard XPath form, so the file works in other tools.
The default column uses MQUAD's #reference grammar on the survey sheet. This is MQUAD's own default-value syntax (the standard ODK default grammar differs); MQUAD preserves the # references it understands.
calculate type rows export with their calculation in the calculation column.
calendar_grid questions are stored with their configuration in the calculation column using a __calendar__: JSON prefix — an MQUAD-specific encoding preserved through round-trips.