Developers

Form definition reference

The JSON format for sections, subsections, questions, conditions and approval rules.

A form definition has two parts: the schema (what respondents see) and approval (how responses are scored).

{
  "schema": {
    "sections": [
      {
        "id": "about",
        "title": "About you",
        "required": true,
        "elements": [
          { "kind": "item", "id": "email", "type": "email", "label": "Email", "required": true },
          { "kind": "item", "id": "age", "type": "number", "label": "Age", "integer": true, "min": 16 },
          {
            "kind": "subsection", "id": "refs", "title": "References", "required": false,
            "repeat": { "min": 1, "max": 3, "add_label": "Add a reference" },
            "items": [
              { "kind": "item", "id": "ref_name", "type": "short_text", "label": "Name", "required": true }
            ]
          }
        ]
      }
    ]
  },
  "approval": {
    "enabled": true,
    "threshold_type": "percent",
    "threshold": 60,
    "show_result": true,
    "show_score": false,
    "criteria": [
      { "id": "adult", "item_id": "age", "op": "gte", "value": 18, "points": 1, "required": true }
    ]
  }
}

Sections

Subsections

Same fields as sections, with items instead of elements.

Items (questions)

Common fields: id, type, label, description, placeholder, required, repeat, condition.

Fields that don’t apply to a type are removed when saved.

Conditions

{ "logic": "all", "rules": [{ "field": "authorized", "op": "equals", "value": false }] }

• logic: all (AND) or any (OR).
• op: equals, not_equals, contains, not_contains, gt, gte, lt, lte, between ([min, max]), in / not_in (list), is_empty, is_not_empty.
• field must be an earlier question in the same or an enclosing repeat scope.

Approval

Answer format

Answers are keyed by question id. Repeatable sections/subsections become arrays of objects, repeatable questions arrays of values. See Repeatable sections.