Form JSON Reference

Version 2.0

The JSON Reference is designed to document the structure of the JSON configuration files that the Qrvey API consumes to produce a Quick Form. This document is focused on the structure and content of the “questions” object.

A Qrvey Quick Form is a web-based data collection page. The user is presented with a series of questions that reflect those that might be shown on manual forms such as a job application, medical history form, or DMV forms. The user can review and edit their responses before submitting the completed form.

 

Document Organization

This document specifically addresses the JSON structure associated with the variety of questions that the developer may include in a Quick Form.

There are essentially three sections to this reference; the JSON overview of the “questions” object, a table that covers the available objects, properties and values, and JSON snippets and result images for each question type and option.

The Appendix presents the overall schema for the JSON file associated with a survey.

 

Questions Object Overview

The questions object has fewer than 10 children. The most prominent child object is data, an array of the various question definitions comprising the survey.

Note: A maximum of 30 possible questions may be asked in the Quick Form. This limit includes required, optional, and conditional questions in aggregate.

 

    "questions": {
   "data": [
       {
        "text": "Sample NUMERIC question",
        "id": "ES4V355J",
        "type": "NUMERIC",
        "question": "main",
        "answers": [
               {
                "answer": "NUMERIC",
                "answerid": "ES4V355Ja0"
               }
                ],
        "allowDecimals": false,
        "hasMinMax": false,
        "min": null,
        "max": null,
        "time": 6,
        "numberType": "General"
       }
        ],
   "totalTime": 10,
   "totalQuestions": 1,
   "results_visibility": "Public",
   "respondent_email": "None",
   "duration": {
        "neverExpires": true,
        "from": "2016-12-09T16:22:52.807Z"
       }
    }
  

Properties and Values for Each Question

Each question object is defined by common properties. The table below provides general information about each property and value. The Required column indicates whether the property is required for the question object. Some properties are required based on the question type and will be documented in the individual question sections.

 

Property

Value

Required

“id”

Any plain text that uniquely identifies the question object. The id value must be unique throughout the JSON file.

Yes

“text”

The question text to be displayed in the survey.

Yes

“type”

The question type. Valid values include: “SINGLE_CHOICE”, “HEADLINE”, “MULTIPLE_CHOICE”, “TEXTFIELD”, “LONGTEXT”, “YES_NO”, “DATE”, “NUMERIC”, “ADDRESS”, “USADDRESS”, “PHONE”, “NAME”, “EMAIL_FORM”

Yes

“answers”

An array object of answer property pairs: “answerid” and “answer”. The “answerid” property value uniquely identifies the answer throughout the JSON file. The “answer” property value is the text to be displayed in the survey.

“question”

Determines whether the question is required to be answered when the survey is taken: Valid values include: “main”, “optional”

Yes

“time”

The expected elapsed time to respond to the question

Yes

“otherfield”

Determines whether the user may provide an additional response to a question. The valid property values are “true” and “false”

No

“hasPaths”

Determines whether additional questions may be presented based on the response to the parent question. The valid property values are “true” and “false”

No

“route”

A child object of the “answers” object, the “route” property identifies a set of questions to be presented if the associated answer is selected during the survey.

Yes, if “hasPaths” is “true”

“content”

Determines the text to be displayed in a HEADLINE question type.

Yes, if the “type” is HEADING

“name”

The text displayed as a header when the “route” option has been chosen.

Yes, if the Route object is used.

“rating”

The property value identifies how many rating options to display in a “RATING” type question.

Yes, if “type” is “RATING”

“maxChar”

The property value determines the maximum length of a response to a “SHORTTEXT” or “LONGTEXT” question type.

Yes, if “type” is “SHORTTEXT” or “LONGTEXT”

"sliderVal"

               

The property value determines the upper value for a SLIDEBAR question type

Yes, if “type” is “SLIDEBAR”

"middleValue”

The property value determines the middle value for a SLIDEBAR question type

Yes, if “type” is “SLIDEBAR”

“activeCat”

The property value determines whether the possible responses are categorized into positive and negative values. The valid values are “true” and “false”.

Yes, if “type” is “EXPRESSION”

“words”

An array object that defines a list of words to choose from in an EXPRESSION” question type.

Yes, if “type” is “EXPRESSION”

“positive”

An array object that defines a list of words considered to be positive responses in an EXPRESSION question type.

Yes, if “type” is “EXPRESSION”

“negative”

An array object that defines a list of words considered to be negative responses in an EXPRESSION question type.

Yes, if “type” is “EXPRESSION”

“multiple”

The property value determines if multiple word selections are possible in an EXPRESSION question type.

Yes, if “type” is “EXPRESSION”

“allowDecimals”

Determines whether the response may contain a decimal point. Valid values are “true” and “false”

Yes, if “type” is “NUMBER”

“hasMinMax”

Determines whether the response is validated to be with an range. Valid values are “true” and “false”.

Yes, if “type” is “NUMBER”

“min”

Determines the minimum response value. If the “hasMinMax” property is true, then a valid number must be supplied, otherwise the value is set to null.

Yes, if “type” is “NUMBER”

“max”

Determines the maximum response value. If the “hasMinMax” property is “true” then a valid number must be supplied, otherwise the value os set to null.

Yes, if “type” is “NUMBER”

“numberType”

Determines the validation imposed on the numeric value entered into a “NUMBER” question type. Valid values include “General”, “Number”, “Currency” and “Percentage”.

Yes, if “type” is “NUMBER”

“imageUrl”

The property value is the full URL path to the image file

Yes, if “type” is “IMAGE”

“imageStoredName”

The property value is the image file name.

No

“imageName”

The property value is the text displayed as a caption for the image.

No

 

 

Question Samples

Following are JSON configuration snippets for each type of question as well as an Image of how the question appears in a survey.

 

“SINGLE_CHOICE”

A typical single choice question presents up to 6 possible answers and allows the user to select one of the answers. The survey architect may also configure the question to 1) make it optional, 2) allow the user to provide a text response, or 3) present additional questions based on the user’s response.

 

Typical SINGLE_CHOICE Question Code Example:

       {
                text: Of these, which is your favorite movie series?,
                type: SINGLE_CHOICE,
                answers: [
                    {
                        answer: Star Wars,
                        answerid: Z41Q21A1
                    },
                    {
                        answer: Lord of the Rings,
                        answerid: Z41Q21A2
                    },
                    {
                        answer: Harry Potter,
                        answerid: Z41Q21A3
                    },
                    {
                        answer: Hunger Games,
                        answerid: Z41Q21A4
                    }
                ],
                id: Z41Q21,
                question: main,
                time: 6
            }
  

 

Sample: Required SINGLE_CHOICE question

 

Optional SINGLE_CHOICE Question Code Example:

        {
                text: Of these, which is your favorite movie series?,
                type: SINGLE_CHOICE,
                answers: [
                    {
                        answer: Star Wars,
                        answerid: Z41Q21A1
                    },
                    {
                        answer: Lord of the Rings,
                        answerid:  Z41Q21A2
                    },
                    {
                        answer: Harry Potter,
                        answerid:  Z41Q21A3
                    },
                    {
                        answer: Hunger Games,
                        answerid:  Z41Q21A4
                    }
                ],
                id:  Z41Q21,
                question: optional,
                time: 6
            }
  

 

Sample: Optional SINGLE_CHOICE question

 

SINGLE_CHOICE Question with User Input Code Example:     

     {
                text: Of these, which is your favorite movie series?,
                type: SINGLE_CHOICE,
                answers: [
                    {
                        answer: Star Wars,
                        answerid: Z41Q21A1
                    },
                    {
                        answer: Lord of the Rings,
                        answerid:  Z41Q21A2
                    },
                    {
                        answer: Harry Potter,
                        answerid:  Z41Q21A3
                    },
                    {
                        answer: Hunger Games,
                        answerid:  Z41Q21A4
                    }
                ],
                id:  Z41Q21,
                question: optional,
                time: 6,
                otherField: true
            }
  

 

Sample: Optional SINGLE_CHOICE question with user input

 

SINGLE_CHOICE Question with Additional Questions Based on Response Example:

           {
                text: Of these, which is your favorite movie series?,
                type: SINGLE_CHOICE,
                answers: [
                    {
                        answer: Star Wars,
                        answerid: Z41Q21A1,
                        route: {
                            name: More Information,
                            questions: {
                                data: [
                                    {
                                        text: Was it the plot or special effects?,
                                        type: SINGLE_CHOICE,
                                        answers: [
                                            {
                                                answer: Plot,
                                                answerid: Z41Q21A1S1
                                            },
                                            {
                                                answer: Special Effects,
                                                answerid: Z41Q21A11S2
                                            }
                                        ],
                                        id: Z41Q21A11S,
                                        question: main,
                                        time: 2
                                    }
                                ]
                            },
                            id: 0
                        }
                    },
                        {
                            answer: Lord of the Rings,
                            answerid: Z41Q21A2
                        },
                        {
                            answer: Harry Potter,
                            answerid: Z41Q21A3
                        },
                        {
                            answer: Hunger Games,
                            answerid: Z41Q21A4
                        }
                        ],
                        id: Z41Q21,
                        question: main,
                time: 6,
                hasPaths: true
                    }
                ]
            }
  

 

Sample: Required SINGLE_CHOICE question with additional question for first response

 

 “MULTIPLE_CHOICE”

A typical MULTIPLE_CHOICE question presents up to 6 possible answers and allows the user to select one or more of the answers. The survey architect may also configure the question to 1) make it optional and 2) allow the user to provide a text response.

Note: The MULTIPLE_CHOICE question type shares the same coding structure as the SINGLE_CHOICE question type. The exception is that additional conditional questions are not permitted. To make a MULTIPLE_CHOICE question optional, set the “question” parameter value to “optional”. To allow the user to provide input, set the “otherfield” parameter value to “true”.

 

Typical MULTIPLE_CHOICE Question Code Example:

        {
                text: Of these, which is your favorite movie series?,
                type: MULTIPLE_CHOICE,
                answers: [
                    {
                        answer: Star Wars,
                        answerid: Z41Q21A1
                    },
                    {
                        answer: Lord of the Rings,
                        answerid: Z41Q21A2
                    },
                    {
                        answer: Harry Potter,
                        answerid: Z41Q21A3
                    },
                    {
                        answer: Hunger Games,
                        answerid: Z41Q21A4
                    }
                ],
                id: Z41Q21,
                question: main,
                time: 6,
                hasPaths: false
            }
  

 

Sample: Required MULTIPLE_CHOICE Question

 

MULTIPLE_CHOICE Question Code with User Input Sample:

         {
                text: Of these, which is your favorite movie series?,
                type: MULTIPLE_CHOICE,
                answers: [
                    {
                        answer: Star Wars,
                        answerid: Z41Q21A1
                    },
                    {
                        answer: Lord of the Rings,
                        answerid: Z41Q21A2
                    },
                    {
                        answer: Harry Potter,
                        answerid: Z41Q21A3
                    },
                    {
                        answer: Hunger Games,
                        answerid: Z41Q21A4
                    }
                ],
                id: Z41Q21,
                question: main,
                time: 6,
                otherField: true,
                hasPaths: false
            }
  

 

Sample: Required MULTIPLE_CHOICE Question with User Input

“HEADLINE”

The HEADLINE “question” allows the survey architect to provide text within a survey. It’s typically used to identify sections of a survey or to provide general instructions. Obviously, it is not a question. There is no user response expected.

 

Typical HEADLINE Question Code Example

      {
                text: HEADLINE,
                type: HEADLINE,
                content: The next set of questions will explore your taste in movies. Click OK to continue.,
                answers: [
                    {
                        answer: HEADLINE
                    }
                ],
                id: 3HT0KYEL,
                question: main,
                time: 0
            }
  

 

Sample: Headline

“TEXTFIELD”

A TEXTFIELD question type allows the user to provide a short, free-form text response to the question. The “maxchar” property should be set to a maximum of 120 characters.

 

Typical TEXTFIELD Question Code Example

        {
                text: Please tell us what we can improve.,
                id: R4KBYFH2,
                type: TEXTFIELD,
                question: main,
                answers: [
                    {
                        answer: TEXTFIELD,
                        answerid: R4KBYFH2a0
                    }
                ],
                maxChar: 120,
                time: 6
            }
  

 

Sample: Required TEXTFIELD Question

“LONGTEXT”

A LONGTEXT question allows the user to provide a more detailed text response to the question. The “maxchar” property should be set to a maximum of 500 characters.

 

Typical LONGTEXT Question Code Example

        {
                text: What can we do to improve this survey?,
                id: X5D50POL,
                type: LONGTEXT,
                question: main,
                answers: [
                    {
                        answer: LONGTEXT,
                        answerid: X5D50POLar0
                    }
                ],
                maxChar: 500,
                time: 6
            }
  

 

Sample: Required LONGTEXT Question

“YES_NO”

A YES_NO question presents the user with two possible responses. Typical “answer” property values might be “yes”, “no”, “true”, ”false”, “on”, “off’ or any word pairs indicating two possible states. The survey architect has the option of defining additional questions based on the user’s response.

 

Typical YES_NO Question Code Example

       {
                text: Was taking this survey quick?,
                id: H6P_ATV6,
                type: YES_NO,
                question: main,
                answers: [
                    {
                        answer: Yes,
                        answerid: H6P_ATV6a0
                    },
                    {
                        answer: No,
                        answerid: H6P_ATV6a1
                    }
                ],
                time: 6
            }
  

 

Sample: Required YES_NO Question

 

YES_NO Question with Additional Questions Code Example

         {
                text: Was taking this survey quick?,
                id: 26V5BV0A,
                type: YES_NO,
                question: main,
                answers: [
                    {
                        answer: Yes,
                        answerid: 26V5BV0Aa0,
                        route: {
                            name: Yes,
                            questions: {
                                data: [
                                    {
                                        text: Was it because there were few questions or the questions were simple?,
                                        id: YCNJHBS_,
                                        type: SINGLE_CHOICE,
                                        question: optional,
                                        answers: [
                                            {
                                                answer: Few Questions,
                                                answerid: YCNJHBS_ar0
                                            },
                                            {
                                                answer: Simple Questions,
                                                answerid: YCNJHBS_ar1
                                            }
                                        ],
                                        time: 6
                                    },
                                    {
                                        text: Would you be willing to participate in other surveys in the future?,
                                        id: 178HQJS9,
                                        type: YES_NO,
                                        question: main,
                                        answers: [
                                            {
                                                answer: Yes,
                                                answerid: 178HQJS9ar0
                                            },
                                            {
                                                answer: No,
                                                answerid: 178HQJS9ar1
                                            }
                                        ],
                                        time: 6
                                    }
                                ]
                            },
                            id: 0
                        }
                    },
                    {
                        answer: No,
                        answerid: 26V5BV0Aa1
                    }
                hasPaths: true
                    }
                ]
            }
  

 

Sample: Yes_No Question with Additional Questions for a “Yes” response

“DATE”

A DATE question will allow the user to enter a date or select a date from a calendar. The response will be validated as a valid date according to the US date format.

 

Typical DATE Question Code Example

         {
                text: What is your date of birth?,
                id: B3APVUNT,
                type: DATE,
                question: main,
                answers: [
                    {
                        answer: DATE,
                        answerid: B3APVUNTa0
                    }
                ],
                time: 6
            }
  

 

Sample: Required DATE Question

 

“NUMERIC”

A NUMERIC question allows the user to enter a numeric value as a response. The response may be re-formatted based on the “numberType” property. Valid values for the “numberType” property include General, Number, Currency, and Percentage.

The survey architect may also define whether decimals are permitted in the response with the “allowDecimals” property.

 

Typical NUMERIC Question Code Example

            {
                text: How many years were you at your last position?,
                id: ES4V355J,
                type: NUMERIC,
                question: main,
                answers: [
                    {
                        answer: NUMERIC,
                        answerid: ES4V355Ja0
                    }
                ],
                allowDecimals: false,
                time: 6,
                numberType: General
            }
  

 

Sample: Required NUMERIC question

 

NUMERIC Question Allowing Decimals Example

        {
                text: What is the value of PI?,
                id: 0SCPCBAM,
                type: NUMERIC,
                question: main,
                answers: [
                    {
                        answer: NUMERIC,
                        answerid: 0SCPCBAMa0
                    }
                ],
                allowDecimals: true,
                time: 6,
                numberType: Number
            }
  

 

Sample: Required NUMERIC question allowing decimals

 

NUMERIC Question with Currency Format Code Example

      {
                text: What is your annual salary?,
                id: FJT8MNJR,
                type: NUMERIC,
                question: main,
                answers: [
                    {
                        answer: NUMERIC,
                        answerid: FJT8MNJRa0
                    }
                ],
                allowDecimals: false,
                time: 6,
                numberType: Currency
            }
  

 

Sample: Required NUMERIC currency question

 

NUMERIC Question with Percentage Format Code Example

         {
                text: What percenatge of your budget is food related?,
                id: 8XM4QBYZ,
                type: NUMERIC,
                question: main,
                answers: [
                    {
                        answer: NUMERIC,
                        answerid: 8XM4QBYZa0
                    }
                ],
                allowDecimals: true,
                time: 6,
                numberType: Percentage
            }
  

 

Sample: Required NUMERIC percentage question

“EMAIL_FORM”

An EMAIL_FORM question allows the user to specify an email address. The response will be verified as a correctly structured email address; however, the email address itself is not verified.

Note: An EMAIL_FORM question may be skipped (optional) if the Quick Form architect sets the “question” property value to “optional”.

 

Typical EMAIL_FORM Question Code Example

                {
                id: 03X6TJLK,
                time: 10,
                text: Please enter your Email Address,
                answers: [
                    {
                        answer: EMAIL_FORM
                    }
                ],
                question: main,
                type: EMAIL_FORM
            }
  

 

Sample: Required EMAIL_FORM question

 

“ADDRESS”

An ADDRESS question allows the user to provide a complete address. Each of the address fields must be completed. A dropdown list of countries is automatically provided in the question.

Note: An ADDRESS question may be skipped (optional) if the Quick Form architect sets the “question” property value to “optional”.

 

Typical ADDRESS Question Code Example

             {
                id: 8_4U1P4F,
                time: 10,
                text: Please enter your Address (non-US Residents),
                answers: [
                    {
                        answer: ADDRESS
                    }
                ],
                question: main,
                type: ADDRESS
            }
  

 

Sample: Required ADDRESS question

”USADDRESS”

A USADDRESS question allows the user to provide a complete United States address. Each of the address fields must be completed. The Zip Code field is validated as numeric. A dropdown list of states is automatically provided in the question. The Country field value is set to “USA”.

Note: A USADDRESS question may be skipped (optional) if the Quick Form architect sets the “question” property value to “optional”.

 

Typical USADDRESS Question Code Example

                {
                id: 7W85MRY9,
                time: 9,
                text: Please enter your Address (US Residents),
                answers: [
                    {
                        answer: USADDRESS
                    }
                ],
                question: main,
                type: USADDRESS
            }
  

Sample: Required USADDRESS question

“PHONE”

A PHONE question allows the user to prove a phone number. The response is validated as a numeric value; however, the number of digits is not validated as being correct. Spaces in the response are automatically removed.

Note: A PHONE question may be skipped (optional) if the Quick Form architect sets the “question” property value to “optional”.

 

Typical PHONE Question Code Example

                {
                id: J32EEQPA,
                time: 9,
                text: Please enter your Phone Number,
                answers: [
                    {
                        answer: PHONE
                    }
                ],
                question: main,
                type: PHONE
            }
  

 

Sample: Required PHONE question

“NAME”

A NAME question allows the user to specify a first and last name. These fields are required to be completed.

Note: A NAME question may be skipped (optional) if the Quick Form architect sets the “question” property value to “optional”.

 

Typical NAME Question Code Example

                {
                id: IQQ7CM_C,
                time: 10,
                text: Please enter your First and Last Name,
                answers: [
                    {
                        answer: Name
                    }
                ],
                question: main,
                type: NAME
            }
  

 

Sample: Required NAME question

 

Appendix: JSON Schema Structure

    {
  
  $schema: http://json-schema.org/draft-04/schema#,
  
  type: object,
  
  properties: {
  
    name: {type: string},
  
    description: {type: string},
  
    customStyle: {type: object,
  
      properties: {
  
        name: {type: string},
  
        style: {type: object,
  
          properties: {
  
            mainFont: {type: string},
  
            imgSize: {type: integer},
  
            questionFont: {type: string},
  
            answerFont: {type: string},
  
            background: {type: string},
  
            textFieldBackground: {type: string},
  
            buttons: {type: string},
  
            main: {type: string}
  
          },
  
          required: [mainFont,imgSize,questionFont,answerFont,
                     background,textFieldBackground,buttons,main]
  
        },
  
        userid: {type: string},
  
        styleid: {type: string},
  
        newChanges: {type: boolean}
  
      },
  
      required: [name,style,userid,styleid,newChanges]
  
    },
  
    introPage: {type: boolean},
  
    tempStyle: {type: object,
  
      properties: {
  
        name: {type: string},
  
        style: {type: object,
  
          properties: {
  
            mainFont: {type: string},
  
            imgSize: {type: integer},
  
            questionFont: {type: string},
  
            answerFont: {type: string},
  
            background: {type: string},
  
            textFieldBackground: {type: string},
  
            buttons: {type: string},
  
            main: {type: string}
  
          },
  
          required: [mainFont,imgSize,questionFont,answerFont,
                     background,textFieldBackground,buttons,main]
  
        },
  
        userid: {type: string},
  
        styleid: {type: string},
  
        newChanges: {type: boolean}
  
      },
  
      required: [name,style,userid,styleid,newChanges]
  
    },
  
    totalTime: {type: integer},
  
    questions: {type: object,
  
      properties: {
  
        data: {type: array,
  
          items: {type: object,
  
            properties: {
  
              text: {type: string},
  
              id: {type: string},
  
              type: {type: string},
  
              question: {type: string},
  
              answers: {type: array,
  
                items: {
  
                  type: object,
  
                  properties: {
  
                    answer: {type: string},
  
                    answerid: {type: string},
  
                    imageUrl: {type: string},
  
                    imageStoredName: {type: string},
  
                    imageName: {type: string},
  
                    route: {type: object,
  
                      properties: {
  
                        name: {type: string},
  
                        id: {type: integer},
  
                        questions: {type: object,
  
                          properties: {
  
                            data: {type: array,
  
                              items: {type: object,
  
                                properties: {
  
                                  text: {type: string},
  
                                  id: {type: string},
  
                                  type: {type: string},
  
                                  question: {type: string},
  
                                  answers: {type: array,
  
                                    items: {type: object,
  
                                      properties: {
  
                                        answer: {type: string},
  
                                        answerid: {type: string}
  
                                      },
  
                                      required: [answer,answerid]
  
                                    }
  
                                  },
  
                                  allowDecimals: {type: boolean},
  
                                  hasMinMax: {type: boolean},
  
                                  min: {type: null},
  
                                  max: {type: null},
  
                                  time: {type: integer},
  
                                  numberType: {type: string}
  
                                },
  
                                required: [text,id,type,question,answers,allowDecimals,
                                           hasMinMax,min,max,time,numberType]
  
                              }
  
                            }
  
                          },
  
                          required: [data]
  
                        }
  
                      },
  
                      required: [name,id,questions]
  
                    }
  
                  },
  
                  required: [answer,answerid,imageUrl,imageStoredName,imageName,route]
  
                }
  
              },
  
              time: {type: integer},
  
              hasPaths: {type: boolean},
  
              otherField: {type: boolean}
  
            },
  
            required: [text,id,type,question,answers,time,hasPaths,otherField]
  
          }
  
        }
  
      },
  
      required: [data]
  
    },
  
    totalQuestions: {type: integer},
  
    thankYouPage: {type: object,
  
      properties: {
  
        title: {type: string},
  
        content: {type: string},
  
        link: {type: string}
  
      },
  
      required: [title,content,link]
  
    }
  
  },
  
  required: [name,description,customStyle,introPage,tempStyle,
             totalTime,questions,totalQuestions,thankYouPage]
  
}