Survey Service (Port 8001)

The survey-service is the authoring engine for MQUAD. It manages survey definitions, versioning, and the transformation between logical schemas and XLSForm files.

Database

Database: survey_db

Table	Purpose
`surveys`	Core survey metadata and current status
`survey_versions`	Immutable snapshots of survey schemas
`survey_templates`	Pre-defined survey structures for reuse

API Endpoints

Method	Path	Purpose
GET	`/api/v1/surveys`	List surveys
POST	`/api/v1/surveys`	Create a new survey
GET	`/api/v1/surveys/{id}`	Get survey details and schema
POST	`/api/v1/surveys/{id}/publish`	Create a new immutable version
POST	`/api/v1/surveys/import-xlsform`	Upload .xlsx and convert to schema
GET	`/api/v1/surveys/{id}/export-xlsform`	Generate .xlsx from schema
GET	`/api/v1/templates`	List available templates

XLSForm Integration

The service includes a robust XLSForm parser (pyxform) integration:

Import: Converts XLSForm rows into a structured JSON schema used by the form-service.
Export: Generates standard ODK-compliant XLSForm files for use in ODK Collect.

Choices Sheet Parsing

The parser supports the standard XLSForm choices sheet with MQUAD extensions:

Standard columns: list_name, name, label, media_file

MQUAD extension columns:

Column	Type	Description
`constraint`	string	Per-choice visibility expression (XPath). Choice is hidden when expression evaluates to false.

Extra columns: Any column beyond the standard set (e.g., state, district, region) is preserved as choice metadata. These extra columns are available as variables in choice_filter expressions on survey questions, enabling cascading selects based on choice attributes.

Constraint normalization during import:

regex_shortcuts.expand_regex_shortcut() — Expands regex=email style shortcuts to full regex expressions.
constraint_normalizer.normalize_constraint() — Auto-corrects common syntax: bare & becomes and, bare | becomes or, standalone comparisons like >=10 gain the . prefix.

The normalized constraint is stored in ChoiceSchema.constraint and serialized into the survey schema JSON.

Supported Question Types

Verified question types supported by the schema validator:

text, integer, decimal, range
select_one, select_multiple (choice-based)
date, time, datetime
image, audio, video, file
geopoint, geoshape, geotrace
barcode, signature
calculate, hidden, note
calendar_grid (Advanced matrix type)
acknowledge, trigger

Versioning Logic

A survey is created in Draft status.
Updates modify the draft schema in the surveys table.
Upon Publish, the current draft is copied to the survey_versions table with an incremented version number.
The survey status changes to Published.
Once published, the version becomes immutable and can be assigned to multiple projects.