How does a form JSON look like?
Forms in GIS Cloud are essential for structuring both data collection and data editing. They can be used in the field through the Mobile Data Collection app, or in the office via Map Editor. Forms help maintain data quality and streamline workflows by offering a user-friendly, survey-style interface.
Benefits of Using Forms
Forms help ensure high data quality by allowing you to define rules and constraints. For example, you can:
- Mark fields as required
- Ensure unique values
- Use autocomplete or autofill functions
- Set up basic automations
You can also group fields, add descriptions, and set field dependencies – making certain fields only appear based on values entered in previous fields. These tools make the form intuitive for beginners while significantly speeding up work for professionals, especially when dealing with long or complex surveys.
Creating and Editing Forms
Forms can be built through the user interface in both the MDC Portal and Map Editor (read more in their respective guides linked here). In Map Editor, you also have the option to view and edit the form as JSON, which is the underlying structure behind the form.
Using the JSON editor allows for:
- Defining advanced automations not possible through the UI
- Speeding up repetitive tasks
- Automating form creation or assigning forms to layers
Example Form Template
Below is an example JSON form that demonstrates how form fields are structured both within and outside of groups. It includes at least one of each available field type, allowing you to see the differences in field-specific options – for example, some fields support a description, while others may not; some allow for an autofill button, and others don’t. This template is especially useful if you’re building a form from scratch in JSON, or if you want to understand how the UI-generated forms are represented in JSON format.
{
"name": "Sample map - form name",
"title": "This is the optional display name for the form",
"description": "",
"items": [
{
"type": "text",
"uuid": "639e8ccc-acd5-472c-ab24-566efe767594",
"name": "Example text field 1",
"persistent": true,
"required": false,
"readOnly": false,
"title": "Example text field 1 label (labels are always optional)",
"description": "This is an example text field that includes the following options: Persistent, Multiline.",
"multiline": true
},
{
"type": "text",
"uuid": "4d8459fa-33e8-436a-b04e-ff27fa653941",
"name": "Example text field 2",
"persistent": false,
"required": true,
"readOnly": false,
"autofill": {
"query": "nearest",
"source": {
"layer": "auto"
},
"result": "<street_name>"
},
"title": "",
"description": "This is an example text field that includes the following options: Required, Autofill (from the same layer, from the field street_name), Single line."
},
{
"type": "text",
"uuid": "ea375fe9-bb6b-40a4-8bf2-ff1c5e31341c",
"name": "Example text field 3",
"persistent": false,
"required": false,
"readOnly": false,
"valid": {
"all": [
{
"value": {
"type": "unique"
}
},
{
"value": {
"type": "unique-among",
"among": [
"4d8459fa-33e8-436a-b04e-ff27fa653941"
],
"scope": [
"form"
]
}
}
]
},
"title": "",
"description": "This is an example text field that includes the following options: Unique value (additional options are Values for this field must be unique, This field's value should be different from Example text field 2, and Unique for this feature)"
},
{
"type": "text",
"uuid": "99a3de29-815a-46e6-941d-cb1e2d4902ed",
"name": "Example text field 4",
"persistent": false,
"required": false,
"readOnly": false,
"autofill": {
"query": "nearest",
"source": {
"layer": "1234567"
},
"result": "<street_name> <house_number>"
},
"title": "",
"description": "This is an example text field that includes the following options: Autofill (from another layer (layer ID is 1234567), from the fields street_name and house_number), and Dependency (at least one of the following rules should be met: (1) Example text field 1 should have a value (ie. not null), or (2) Example text field 2 should be equal to Main Street).",
"active": {
"any": [
{
"item": {
"name": "639e8ccc-acd5-472c-ab24-566efe767594",
"hasValue": true
}
},
{
"item": {
"name": "4d8459fa-33e8-436a-b04e-ff27fa653941",
"value": {
"equals": "Main Street"
}
}
}
]
}
},
{
"type": "text",
"uuid": "f5fa28db-d1c9-44fd-99c6-9aacb57e7881",
"name": "Example text field 5",
"persistent": false,
"required": false,
"readOnly": false,
"value": "Input default value here",
"title": "",
"description": "This is an example text field that includes the following options: Default value"
},
{
"type": "group",
"uuid": "415971ae-7825-499b-8dec-5a42dd979a45",
"name": "Standard items",
"title": "",
"description": "This group includes standard items where the user usually needs to add some input - depending on the field options you set up (eg. required, persistent, read only etc.). All items can have dependencies.",
"active": true,
"items": [
{
"type": "text",
"uuid": "209418ca-c4a4-42f3-a4d7-fc0acb682b20",
"name": "Text field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Text field label",
"description": "This is a default text field (no options selected) with a description.\nIn addition, you can choose the following options for this field: Persistent, Required, Read only, Autofill, Unique value, Default value, and a choice between Single line (default option) or Multiline. "
},
{
"type": "numeric",
"uuid": "871246ff-c971-4391-b22b-593d3df49003",
"name": "Number field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Number field label",
"description": "This is a default number field (no options selected) with a description.\nIn addition, you can choose the following options for this field: Persistent, Required, Read only, Unique value and Default value."
},
{
"type": "datetime",
"uuid": "5ca0c721-ef3e-42b6-9c5a-1199ef6d05b5",
"name": "Date and time field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Date and time field label",
"description": "Both date and time are collected. You can alternatively choose to collect just date or just time. No other options are selected.\nIn addition, you can choose the following options for this field: Persistent, Required, Read only and Unique value.",
"mode": "datetime"
},
{
"type": "select",
"uuid": "7d6eaad2-88b1-4700-822d-664ebf5c6090",
"name": "Select list field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Select list field label",
"description": "This field is a select list. It displays as a dropdown, where the user can only select one of the options. Values in a select list can be grouped, they can have dependencies, and you can choose which value is set as the default - all optional settings.\nIn addition, you can choose the following options for this field: Persistent, Required, Read only and Unique value.",
"options": [
{
"title": "Value label 1",
"value": "Value 1"
},
{
"title": "Value label 2",
"value": "Value 2"
},
{
"title": "Value label 3",
"value": "Value 3"
},
{
"title": "Select lists can also include groups. This is the group name.",
"items": [
{
"title": "Value label 4 - this value is set as default!",
"value": "Value 4"
},
{
"title": "Value label 5",
"value": "Value 5"
},
{
"title": "Value label 6 - this value has dependencies!",
"value": "Value 6",
"active": {
"any": [
{
"item": {
"name": "871246ff-c971-4391-b22b-593d3df49003",
"value": {
"moreThan": 5
}
}
},
{
"item": {
"name": "871246ff-c971-4391-b22b-593d3df49003",
"value": {
"lessThanOrEqual": 10
}
}
}
]
}
}
]
}
],
"value": "Value 4"
},
{
"type": "radio",
"uuid": "6b469f72-37e0-46da-af3b-bf4ff00da403",
"name": "Radio buttons field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Radio buttons field label",
"description": "This is a radio button field. All values from this field are displayed (if the field is active), but only one value can be selected. \nIn addition, you can choose the following options for this field: Persistent, Required, Read only and Unique value. Values can also be set as default.",
"options": [
{
"title": "Value label 1",
"value": "Value 1"
},
{
"title": "Value label 2",
"value": "Value 2"
},
{
"title": "Value label 3",
"value": "Value 3"
}
]
},
{
"type": "checkbox",
"uuid": "238ab25d-7008-4379-ac89-5c14bc43f7d9",
"name": "Checkboxes field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Checkboxes field label",
"description": "This is a checkbox field. All values from this field are displayed (if the field is active), and multiple values can be selected at the same time. \nIn addition, you can choose the following options for this field: Persistent, Required, Read only and Unique value. Values can also be set as default.",
"options": [
{
"title": "Value label 1",
"value": "Value 1"
},
{
"title": "Value label 2",
"value": "Value 2"
},
{
"title": "Value label 3",
"value": "Value 3"
}
]
},
{
"type": "signature",
"uuid": "83e47755-ab86-4c1a-9893-70c8b75fa8ae",
"name": "Signature field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Signature field label",
"description": "This is a signature field. It allows you to collect a signature as an image. \nIn addition, you can choose the following options for this field: Persistent, Required and Read only.",
"agreement": "Input signature agreement text here. This will be displayed on the screen when the person is signing; and the database table will include a field with this text recorded for reference."
},
{
"type": "hidden",
"uuid": "2a691abe-db18-42ad-b69f-86eb54e7403c",
"name": "Hidden field name",
"persistent": false,
"required": false,
"readOnly": false,
"value": "This is a hidden field - this means that it will be recorded as an attribute field, but the user will not see this field in the mobile app. Input the value you want to add to the hidden field here.",
"title": "Hidden field label"
}
]
},
{
"type": "group",
"uuid": "e342902c-c7a0-4508-ae91-e95c550f09d2",
"name": "Media",
"title": "",
"description": "This group includes media items - additional modifications to items can be done thorugh field options (eg. required, persistent, unique or default value (only available for QR/Barcode field), read only, etc.). All items can have dependencies.",
"active": true,
"items": [
{
"type": "photos",
"uuid": "454a8301-fea1-436c-8152-984872d6a86e",
"name": "Photo field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Photo field label",
"description": "This is a default photo field with a description.\nIn addition, you can choose the following options for this field: Persistent, Required, Read only."
},
{
"type": "videos",
"uuid": "c149d873-5f3f-48da-b895-7f4b43578d67",
"name": "Video field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Video field label",
"description": "This is a default video field with a description.\nIn addition, you can choose the following options for this field: Persistent, Required, Read only."
},
{
"type": "recording",
"uuid": "8077edac-0c8c-4477-8f6d-c42fcbbe1256",
"name": "Audio recording field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Audio recording field label",
"description": "This is a default audio recording field with a description.\nIn addition, you can choose the following options for this field: Persistent, Required, Read only."
},
{
"type": "qr",
"uuid": "ebe0d9b4-aee8-49fe-9850-61136793f556",
"name": "QR/Barcode field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "QR/Barcode field label",
"description": "This is a default QR/Barcode field with a description.\nIn addition, you can choose the following options for this field: Persistent, Required, Read only, Unique value, and Default value."
}
]
},
{
"type": "group",
"uuid": "17fb9a2c-1771-4a97-abdf-939d150ae364",
"name": "Device and user",
"title": "",
"description": "This group contains form fields whose values are automatically collected. These fields will be visible on the in the database table, but the fields themselves are not visible to the person filling out the form in the field (they are visible if editing through Map Editor). ",
"active": true,
"items": [
{
"type": "mdcUsername",
"uuid": "59d9a448-1bfa-4b46-a4e9-cfff2515fbf2",
"name": "User name field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "User name field label"
},
{
"type": "mdcDeviceId",
"uuid": "e5c03ff5-60d2-4850-b81f-79c5dc02a507",
"name": "Device ID field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Device ID field label"
},
{
"type": "mdcDeviceModel",
"uuid": "1e02952b-b01d-4d9b-a0af-54292e7e1305",
"name": "Device Model field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Device Model field label"
},
{
"type": "mdcDeviceVersion",
"uuid": "31487b18-d520-4a85-98a5-8ffa0b64a6cb",
"name": "Device Version field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Device Version field label"
},
{
"type": "mdcDevicePlatform",
"uuid": "46c4872d-0e2b-4d55-af66-2e51fb785d5a",
"name": "Device Platform field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Device Platform field label"
},
{
"type": "mdcAppVersion",
"uuid": "ed818e51-46be-4f1d-9ace-001efd2fae23",
"name": "Mobile App Version field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Mobile App Version field label"
}
]
},
{
"type": "group",
"uuid": "de47f9a4-6821-409b-afec-355acc3b5ae5",
"name": "Location",
"title": "",
"description": "This group contains form fields whose values are automatically collected. These fields will be visible on the in the database table, but the fields themselves are not visible to the person filling out the form in the field (they are visible if editing through Map Editor). ",
"active": true,
"items": [
{
"type": "mdcLocationLat",
"uuid": "27f0f2a2-4653-4e69-88ed-5988d0fa33ac",
"name": "Latitude field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Latitude field label"
},
{
"type": "mdcLocationLon",
"uuid": "4dd35b89-1e04-4ac1-b021-3146d57521ed",
"name": "Longitude field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Longitude field label"
},
{
"type": "mdcLocationAlt",
"uuid": "96eced94-3b1c-47da-9de5-1b9ef27303d6",
"name": "Altitude field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Altitude field label"
},
{
"type": "mdcLocationSpeed",
"uuid": "58705a89-37eb-4dce-a647-5a6e9d084938",
"name": "Speed field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Speed field label"
},
{
"type": "mdcLocationHeading",
"uuid": "f2a1075a-cb65-41a3-9ad5-4f29ff713bee",
"name": "GPS Heading field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "GPS Heading field label"
},
{
"type": "mdcCompassHeading",
"uuid": "fc0d479f-94a4-49a4-b723-db251142d279",
"name": "Compass Heading field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Compass Heading field label"
},
{
"type": "mdcLocationAcc",
"uuid": "1ab10581-3bb5-4bfd-b9aa-9ed5f525631c",
"name": "Accuracy field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Accuracy field label"
},
{
"type": "mdcLocationAltAcc",
"uuid": "f877265c-9f9e-4f2d-8de5-1e99710d6424",
"name": "Altitude Accuracy field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Altitude Accuracy field label"
},
{
"type": "mdcLocationTime",
"uuid": "365d01c9-dfec-4fde-9edd-cdef7e539a97",
"name": "Time field name",
"persistent": false,
"required": false,
"readOnly": false,
"title": "Time field label"
}
]
}
]
}Want to Learn More?
Check out the guides below to explore: