Introduction

xyField surveys are defined using a JSON-based schema. This configuration file controls everything about a survey: the project metadata, the fields (questions) shown to the user, and the conditional logic that governs form behavior.

Root Structure

The root of the JSON object defines global settings for the survey.

Property	Type	Required	Description
project_title	string	Yes	Human-readable name of the survey project
survey_id	string	Yes	Unique identifier for the survey
geometry_type	string	Yes	The spatial geometry used for data collection (e.g. "point")
gps_accuracy_threshold	number	No	Maximum acceptable GPS accuracy in meters
capture_altitude	boolean	No	Whether to capture the device altitude with the geometry
version	string	Yes	Schema version in semver format (e.g. "1.0.0")
description	string	No	A brief description of the survey's purpose
locale	object	Yes	Language and localization settings (see below)
pages	array	No	Sections that split the form into pages (see Pages)
fields	array	Yes	The list of questions/inputs in the survey
conditionals	object	No	Skip logic and auto-assignment rules

{
  "project_title": "Land Use Survey",
  "survey_id": "10001",
  "geometry_type": "point",
  "version": "1.0.0",
  "description": "A survey for mapping land use across the district",
  "locale": { ... },
  "pages": [ ... ],
  "fields": [ ... ],
  "conditionals": { ... }
}

Locale Configuration

The locale object handles language support for the survey.

Property	Type	Description
default	string	The default language code used when no preference is set
supported	array	List of all language codes the survey supports

"locale": {
  "default": "en_US",
  "supported": ["en_US", "es_ES", "fr_FR"]
}

Supported locale codes follow the language_REGION format (e.g. en_US for English – United States, fr_FR for French – France).

Pages (Sections)

The optional pages array splits a long form into sections. Each field joins a section by setting its section property to a page id. Pages appear in the order they are listed.

Property	Type	Required	Description
id	string	Yes	Unique identifier that fields reference in their section property
label	string	Yes	Section title shown to the user

"pages": [
  { "id": "section_location", "label": "Location & Identification" },
  { "id": "section_owner", "label": "Owner Information" }
],
"fields": [
  { "key": "street_address", "section": "section_location", ... },
  { "key": "owner_name", "section": "section_owner", ... }
]

When a survey defines pages, every field should have a section that matches one of the page ids.