Form Technical Reference

The Protocol Form is how you can create questions for your tasks. These could be used to accompany any type of task, like reader studies.

Simple Form JSON

{
  "title": "Simple Form",
  "description": "",
  "defaults": {
    "text-field": "",
    "checkbox-field": []
  },
  "fields": [
    {
      "key": "title",
      "type": "paragraph",
      "label": "My Title"
    },
    {
      "key": "text-field",
      "type": "text",
      "label": "My Text Field"
    },
    {
      "key": "checkbox-field",
      "type": "checkbox",
      "label": "My Checkbox Fields",
      "options": [
        {
          "label": "One",
          "value": "1"
        },
        {
          "label": "Two",
          "value": "2"
        }
      ]
    }
  ]
}

Form Properties

Property	Description	Value	Required
title	The title of the form, not currently shown in the viewer.	String	yes
description	The description of the purpose of the from, not currently shown in the viewer.	String	yes
defaults	This is an object that is in the format of the answers we expect to get back from the questions, where the field key is a property and the value is the default (starting) state of the answer. The type of primitive the answer is expected to be is inferred from the value. e.g. "" = String, [] = Array, false = boolean	Object of Key/Value pairs	yes
fields	The collection of questions to be answered. See Field Properties below.	Array of Fields	yes

Note: defaults does not need to include all of the field key's just the ones that you are expecting values for. Most likely you will skip paragraph and instruction types in your defaults object.

Example Field

Screenshot 2025-12-01 at 3.37.04 PM.png

Field Properties

Property	Description	Value	Required
key	unique name to map a question the the entered value. Also used as the var identifier for the [JsonLogic](https://jsonlogic.com/) visibility and validity.	String	yes
type	this identifies what type of field format will be used to answer the question.	'paragraph', 'instruction', 'text', 'text-area', 'select', 'checkbox', 'radio'	yes
label	This is the label used to ask the question.	String	no (but may look weird)
description	Some optional text you may want to display under the label.	String	no
helperText	Optional label to put under the field input, quite often used for example answers	String	no
options	If you have a collection field this where you would make the collection of choices that would be presented.	Array of Value/Label objects \[{"value": "1", "label": "One"}\]	if type is 'select', 'checkbox', or 'radio'
visible	The [JsonLogic](https://jsonlogic.com/) rule to determine if the field is visible	Array of JsonLogic RulesLogic or Boolean	no, not specified assumes visible
requiredWhenVisible	If the field is visible whether or not it is required to have a valid value. If true this will also show a red asterisk indicator next to the question label. (see above image)	Array of JsonLogic RulesLogic or Boolean	no, not specified assumes not required
validation	See Validation Rule Properties below	Array of Validation Rule Objects	no, not specified assumes no validation run

Validation Rule Properties

Property	Description	Value	Required
logic	The JsonLogic rule to determine if the field value is valid	JsonLogic RulesLogic	yes
message	Message to show if the RulesLogic is not met	String	no (but may be hard to understand the validation failure without it)

As you can see from above a key component of the interactivity in the validation and visibility logic used in a form is handled via an array of JsonLogic rules. For both the visible and requiredWhenVisible rules collection if any of the rules are true then the whole set evaluates to true. The validation collection works slightly different in that if any of the logic evaluates to false it will show the message and that field is consider invalid.

Validation and Visibility Sample Form

{
    "title": "Validation and Visibility Sample Form",
    "description": "",
    "defaults": {
        "text-field": "",
        "checkbox-field": []
    },
    "fields": [
        {
            "key": "title",
            "type": "paragraph",
            "label": "My Title"
        },
        {
            "key": "text-field",
            "type": "text",
            "label": "My Text Field"
        },
        {
            "key": "checkbox-field",
            "type": "checkbox",
            "label": "My Checkbox Fields",
            "options": [
                {
                    "label": "One",
                    "value": "1"
                },
                {
                    "label": "Two",
                    "value": "2"
                }
            ]
        },
        {
            "key": "conditional-text",
            "type": "text",
            "label": "Conditional Text Validation",
            "description": "Visible only if checkbox 'One' is selected.",
            "helperText": "Enter either 'One' or 'Two'",
            "visible": [
                {
                    "===": [
                        {
                            "var": "checkbox-field"
                        },
                        "1"
                    ]
                }
            ],
            "requiredWhenVisible": true,
            "validation": [
                {
                    "logic": {
                        "in": [
                            {
                                "var": "conditional-text"
                            },
                            [
                                "One",
                                "Two"
                            ]
                        ]
                    },
                    "message": "Value must be 'One' or 'Two'"
                }
            ]
        }
    ]
}

When adding logic to your form it is always best to use affirmative based logic like shown above in the Validation and Visibility Sample Form with the use of "===" or "in". Using something like "!==" : [var, "2"] does not take into account empty values or other defaults that may be set. Negative logic also becomes a lot more complex to follow when one starts to add logical conjunctions in the mix.

Note: If requiredWhenVisible is false and the value is empty validation does not run. If you have a use case where you want to conditionally allow empty value based on another field then you would have to make requiredWhenVisible a JsonLogic Rule and add and empty check to your validation.

Logical conjunctions like "and", "or" can be used to string more complex logic together based on multiple values or fields. This logic also becomes necessary for when multiple sub-rules are need as only one top level rule can be used.

Conjunction example

{
  "and": [
    {
      "===": [ {"var": "conditional_text"}, "Two"]
    },
    {
      "===": [ {"var": "conditional_dropdown"}, "2"]
    }
  ]
}

Full Text Example Form Look in Viewer

Screenshot 2025-12-01 at 3.41.15 PM.png

Full Test Example Form JSON

{
  "title": "Full Test Example Form",
  "description": "Form to test validation.",
  "defaults": {
    "required_text": "",
    "required_dropdown": "",
    "required_radio": "",
    "required_checkbox": [],
    "conditional_text": "",
    "conditional_dropdown": "",
    "conditional_radio": "",
    "conditional_checkbox": []
  },
  "fields": [
    {
      "key": "instruction",
      "type": "instruction",
      "label": "Instructions",
      "description": "This is an instruction field type."
    },
    {
      "key": "paragraph",
      "type": "paragraph",
      "description": "This is a paragraph field type"
    },
    {
      "key": "required_text",
      "type": "text",
      "label": "Required Text",
      "helperText": "Text is required in the field",
      "requiredWhenVisible": true,
      "visible": true
    },
    {
      "key": "required_dropdown",
      "type": "select",
      "label": "Required Dropdown",
      "requiredWhenVisible": true,
      "visible": null,
      "options": [
        {
          "value": "1",
          "label": "One"
        },
        {
          "value": "2",
          "label": "Two"
        }
      ]
    },
    {
      "key": "ins_select_one",
      "type": "instruction",
      "description": "These instructions are shown when the value of Required Dropdown is 'One'.",
      "visible": [
        {
          "===": [
            {
              "var": "required_dropdown"
            },
            "1"
          ]
        }
      ]
    },
    {
      "key": "ins_select_two",
      "type": "instruction",
      "description": "These instructions are shown when the value of Required Dropdown is 'Two'.",
      "visible": [
        {
          "===": [
            {
              "var": "required_dropdown"
            },
            "2"
          ]
        }
      ]
    },
    {
      "key": "required_radio",
      "type": "radio",
      "label": "Required Radio Buttons",
      "requiredWhenVisible": true,
      "visible": null,
      "options": [
        {
          "value": "1",
          "label": "One"
        },
        {
          "value": "2",
          "label": "Two"
        }
      ]
    },
    {
      "key": "ins_radio_one",
      "type": "instruction",
      "description": "These instructions are shown when the value of Required Radio Buttons is 'One'.",
      "visible": [
        {
          "===": [
            {
              "var": "required_radio"
            },
            "1"
          ]
        }
      ]
    },
    {
      "key": "ins_radio_two",
      "type": "instruction",
      "description": "These instructions are shown when the value of Required Radio Buttons is 'One'.",
      "visible": [
        {
          "===": [
            {
              "var": "required_radio"
            },
            "2"
          ]
        }
      ]
    },
    {
      "key": "required_checkbox",
      "type": "checkbox",
      "label": "Required Checkboxes",
      "requiredWhenVisible": true,
      "visible": null,
      "options": [
        {
          "value": "1",
          "label": "One"
        },
        {
          "value": "2",
          "label": "Two"
        }
      ]
    },
    {
      "key": "ins_checkbox_one",
      "type": "instruction",
      "description": "These instructions are shown when 'One' is checked in the Required Checkboxes field.",
      "visible": [
        {
          "in": [
            "1",
            {
              "var": "required_checkbox"
            }
          ]
        }
      ]
    },
    {
      "key": "ins_checkbox_two",
      "type": "instruction",
      "description": "These instructions are shown when 'Two' is checked in the Required Checkboxes field.",
      "visible": [
        {
          "in": [
            "2",
            {
              "var": "required_checkbox"
            }
          ]
        }
      ]
    },
    {
      "key": "ins_checkbox_all",
      "type": "instruction",
      "description": "These instructions are shown when 'One' and 'Two' are checked in the Required Checkboxes field.",
      "visible": [
        {
          "and": [
            {
              "in": [
                "1",
                {
                  "var": "required_checkbox"
                }
              ]
            },
            {
              "in": [
                "2",
                {
                  "var": "required_checkbox"
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "key": "conditional_text",
      "type": "text",
      "label": "Conditional Text Validation",
      "visible": true,
      "requiredWhenVisible": [{
          "in": [
            "2",
            {
              "var": "required_checkbox"
            }
          ]
      }],
      "validation": [
        {
          "logic": {
            "in": [
              {
                "var": "conditional_text"
              },
              ["One", "Two"]
            ]
          },
          "message": "Value must be 'One' or 'Two'"
        }
      ]
    },
    {
      "key": "conditional_dropdown",
      "type": "select",
      "label": "Conditional Dropdown Validation",
      "visible": [
        {
          "in": [
            {
              "var": "conditional_text"
            },
            ["One", "Two"]
          ]
        }
      ],
      "options": [
        {
          "value": "1",
          "label": "One"
        },
        {
          "value": "2",
          "label": "Two"
        }
      ],
      "validation": [
        {
          "logic": {
            "or": [
              {
                "and": [
                  {
                    "===": [
                      {
                        "var": "conditional_text"
                      },
                      "One"
                    ]
                  },
                  {
                    "===": [
                      {
                        "var": "conditional_dropdown"
                      },
                      "1"
                    ]
                  }
                ]
              },
              {
                "and": [
                  {
                    "===": [
                      {
                        "var": "conditional_text"
                      },
                      "Two"
                    ]
                  },
                  {
                    "===": [
                      {
                        "var": "conditional_dropdown"
                      },
                      "2"
                    ]
                  }
                ]
              }
            ]
          },
          "message": "Value must match that of the Conditional Text Validation field above"
        }
      ]
    },
    {
      "key": "conditional_radio",
      "type": "radio",
      "label": "Conditional Radio Buttons Validation",
      "requiredWhenVisible": false,
      "visible": [
        {
          "in": [
            {
              "var": "conditional_dropdown"
            },
            ["1", "2"]
          ]
        }
      ],
      "options": [
        {
          "value": "1",
          "label": "One"
        },
        {
          "value": "2",
          "label": "Two"
        }
      ],
      "validation": [
        {
          "logic": {
            "or": [
              {
                "and": [
                  {
                    "===": [
                      {
                        "var": "conditional_dropdown"
                      },
                      "1"
                    ]
                  },
                  {
                    "===": [
                      {
                        "var": "conditional_radio"
                      },
                      "1"
                    ]
                  }
                ]
              },
              {
                "and": [
                  {
                    "===": [
                      {
                        "var": "conditional_dropdown"
                      },
                      "2"
                    ]
                  },
                  {
                    "===": [
                      {
                        "var": "conditional_radio"
                      },
                      "2"
                    ]
                  }
                ]
              }
            ]
          },
          "message": "Value must match that of the Conditional Dropdown Validation field above"
        }
      ]
    },
    {
      "key": "conditional_checkbox",
      "type": "checkbox",
      "label": "Conditional Checkbox Validation",
      "requiredWhenVisible": true,
      "visible": [
        {
          "in": [
            {
              "var": "conditional_radio"
            },
            ["1", "2"]
          ]
        }
      ],
      "options": [
        {
          "value": "1",
          "label": "One"
        },
        {
          "value": "2",
          "label": "Two"
        },
        {
          "value": "3",
          "label": "Three"
        }
      ],
      "validation": [
        {
          "logic": {
            "in": [
              "3",
              {
                "var": "conditional_checkbox"
              }
            ]
          },
          "message": "Must include choice Three"
        }
      ]
    }
  ]
}