Understand Response Data Schemas
The schema endpoint is used to get a description of what you get from the data endpoint. In Confirmit you add questions to your survey; these questions are called "variables" in the schema. A variable has a variableType property ie. singleChoice, multiChoice, text, and it has properties describing its location and appearance.
Serveral datapoints can be linked to a variable. We call these datapoints fields. Sometimes a field is implicit, but for some variable types fields will be declared explicitly via their Fields property.
A schema consists of levels. The top-level is called the "response"-level and contains all the "normal" variables. In Confirmit we can add loops to the top-level of a survey. A loop is a container of questions that are repeated for each iteration code of the loop. A loop can contain nested loops. In the schema, the loops are linked by the Children property on the level.
General schema
GET https://<host>/v1/surveys/p1231234/responses/schema HTTP/1.1
Accept: application/json
Authorization: Bearer <access_token>{
"defaultConfirmitLanguageId": 9, (1)
"languages": [{"confirmitLanguageId" : 9}, {"confirmitLanguageId" : 20}], (2)
"root": { (3)
"name": "response",
"keys": [], (4)
"variables": [],
"children": []
}
}| 1 | This property contains the id of the default language for the survey. |
| 2 | The languages property contains a list of the languages supported by the survey. Each variable has title and text properties which are collections of texts identified by a languageId property. In this example is 9 = English and 20 = Norwegian. |
| 3 | The root property contains the top level in the schema. |
| 4 | The keys property contains a list of the variables that are the unique keys on that level. |
Hierarchical schema
{
"defaultConfirmitLanguageId": 9,
"languages": [{"confirmitLanguageId" : 9}],
"root": {
"name": "response",
"keys": [
{
"name": "responseid", (1)
"variableType": "numeric",
"isSystemVariable": "true"
}
],
"variables": [ {"name": "gender"}, {"name": "city"}, {"name": "email"} ],
"children": [
{
"name": "cars",
"keys": [
{
"name": "cars", (2)
"variableType": "singleChoice",
"options": [ (3)
{
"code": "bmw",
},
{
"code": "ford",
}
],
"variables": [ {"name": "yearsOwned"}, {"name": "happyWithCar"} ], (4)
}
],
}
]
}
}| 1 | ResponseId is the unique system variable identifying a response. |
| 2 | The key variable of a loop has the name of the loop. |
| 3 | A "singleChoice" variable has an options property that contains the possible codes that can be chosen for this variable. For a loop key variable we call these options loop-iterations. |
| 4 | The variables on a loop level has a value for each iteration code of the loop. |
SingleChoice variables
A SingleChoice variable can have a value datapoint or an object datapoint. A SingleChoice variable with an object datapoint will have the isCompound property set to "true". We call these variables compound variables.
{
"name": "gender", (1)
"titles": [
{
"languageId": 9,
"text": "Gender"
}
],
"texts": [
{
"languageId": 9,
"text": "State your gender"
}
],
"variableType": "singleChoice",
"options": [
{
"code": "male",
"texts": [
{
"languageId": 9,
"text": "Male"
}
]
},
{
"code": "female",
"texts": [
{
"languageId": 9,
"text": "Female"
}
]
}
]
}| 1 | The datapoint for this variable will be "gender". Ex. "gender": "male". |
{
"name": "cars",
"isCompound": "true", (1)
"titles": [
{
"languageId": 9,
"text": "Cars"
}
],
"texts": [
{
"languageId": 9,
"text": "How do you like these cars?"
}
],
"variableType": "singleChoice",
"fields": [ (2)
{
"code": "bwm",
"texts": [
{
"languageId": 9,
"text": "BMW"
}
]
},
{
"code": "vw",
"texts": [
{
"languageId": 9,
"text": "Volkswagen"
}
]
},
{
"code": "ford",
"texts": [
{
"languageId": 9,
"text": "Ford"
}
]
}
],
"options": [
{
"code": "ng",
"texts": [
{
"languageId": 9,
"text": "Not good"
}
]
},
{
"code": "vg",
"texts": [
{
"languageId": 9,
"text": "Very good"
}
]
}
]
}| 1 | Note the isCompound property indicating that this is a compound variable. |
| 2 | A compound variable will have a fields property. The datapoint for a compound variable will be an object where each code in the fields collection will be a property of the object. Each of these property can have one of the codes in the options collection as value. Exc "cars": { "bmw": "vg", "vw": "ng", "ford": "vg"} |
MultiChoice variables
A MultiChoice variable has an object datapoint. The datapoint has a true property listing the selected codes for this variable.
{
"name": "cars", (1)
"titles": [
{
"languageId": 9,
"text": "Cars"
}
],
"texts": [
{
"languageId": 9,
"text": "Which of these cars have you tried?"
}
],
"variableType": "multiChoice",
"options": [
{
"code": "bwm",
"texts": [
{
"languageId": 9,
"text": "BMW"
}
]
},
{
"code": "vw",
"texts": [
{
"languageId": 9,
"text": "Volkswagen"
}
]
},
{
"code": "ford",
"texts": [
{
"languageId": 9,
"text": "Ford"
}
]
}
],
}| 1 | The datapoint for this variable will be "cars" and it will contain the selected codes for this variable. Ex "cars": { "true": ["vw", "ford"] }. |
Numeric variables
Numeric variables will have a value datapoint, for example "age": 34.
{
"name": "age",
"titles": [
{
"languageId": 9,
"text": "Age"
}
],
"texts": [
{
"languageId": 9,
"text": "How old are you?"
}
],
"variableType": "numeric",
"precision": 3, (1)
"scale": 0 (2)
}| 1 | Number of digits in this number. |
| 2 | Number of digits to the right of the decimal point in this number. |
Date variables
Date variables will have a value datapoint, for example "dateofbirth": "1995-02-13".
{
"name": "dateofbirth",
"titles": [
{
"languageId": 9,
"text": "Date of Birth"
}
],
"texts": [
{
"languageId": 9,
"text": "When were you born?"
}
],
"variableType": "date"
}Text variables
Text variables will have a value datapoint, for example "comment": "Very good!".
{
"name": "comment",
"titles": [
{
"languageId": 9,
"text": "Comment"
}
],
"texts": [
{
"languageId": 9,
"text": "Any comments to add?"
}
],
"variableType": "text",
"length": 34 (1)
}| 1 | A Text variable can have a length property. If specified, it states how many characters can be stored in this datapoint. If not specified, unlimited text can be stored. |
System variables
The "response" level of the schema will contain a set of variables that have the isSystemVariable property set to "true". We call these varibles System Variables.
{
"name": "interview_start",
"titles": [
{
"languageId": 9,
"text": "Interview Start"
},
{
"languageId": 20,
"text": "Intervju Start"
}
],
"variableType": "dateTime",
"isSystemVariable": true, (1)
}| 1 | The property indicating that this is a system variable. |
These are the system variables currently in the schema:
-
responseid - The unique id of a response.
-
respid - The unique id of the respondent who took the survey.
-
interview_start - The date and time of the start of the interview.
-
interview_end - The date and time of the end of the interview.
-
status - The status of the interview. Completed, Incomplete, Error, QuotaFull, Screened.
-
lastchannel - The last channel the respondent used to answer the survey. Web, Telephone, +.
-
lastdevicetype - The last type of device the respondent used to answer the survey. Desktop, Touch, +.
-
lastrenderingmode - The last rendering mode the respondent used to answer the survey. Desktop, Touch, +.
-
last_touched - Timestamp of when the respondent last answered the survey.
-
first_question_on_last_page_displayed - The dropout question.
Filtered schemas
It is possible to get a schema with a limited variable set. We have two query parameters that can be used to limit the variables:
-
variables - a comma-delimited list of variable ids.
-
variableTemplateId - the numeric id of a Variable Template created in Survey Designer.
GET https://<host>/v1/surveys/p1231234/responses/schema?variables=q1,q2,q3 HTTP/1.1
Accept: application/json
Authorization: Bearer <access_token>{
"root": {
"name": "response",
"keys": [ {"name": "responseid"}],
"variables": [{"name": "q1"}],
"children": [
{
"name": "l1",
"keys": [ {"name": "l1"}],
"variables": [{"name": "q2"}]
},
{
"name": "l2",
"keys": [ {"name": "l2"}],
"variables": [{"name": "q3"}]
}
]
}
}GET https://<host>/v1/surveys/p1231234/responses/schema?variabelTemplateId=73 HTTP/1.1
Accept: application/json
Authorization: Bearer <access_token>{
"root": {
"name": "response",
"keys": [ {"name": "responseid"}],
"children": [
{
"name": "l1",
"keys": [ {"name": "l1"}],
"children": [
{
"name": "l3",
"keys": [ {"name": "l3"}],
"variables": [{"name": "q4"},{"name": "q5"},{"name": "q6"}]
}
]
}
]
}
}Background and Hidden variables
Variables can have the isBackground or isHidden properties set to "true". Most variableTypes can be set as Background or Hidden.
Background variables are variables where the value is taken from the respondent record of the respondent taking the survey. Hidden variables are not visible to the respondent, but rather used to collect data via scripting or similar during the interview.
{
"name": "country",
"isBackground": "true"
},
{
"name": "browser_value",
"isHidden": "true"
}Compound variables
Variables of type "numeric", "text" and "singleChoice" can also have the isCompound property set to "true". In Confirmit these are called "Numeric lists", "Open text lists" and "Grids", respectively. Common for these variables is the inclusion of the fields property and that the datapoint is an object.
{
"name": "car_comment",
"isCompound": "true",
"variableType": "text",
"fields": [{"code": "bwm"},{"code": "ford"},+++],
"length": 1014
},
{
"name": "car_weight",
"isCompound": "true",
"variableType": "numeric",
"fields": [{"code": "bwm"},{"code": "ford"},+++],
"precision": 7,
"scale": 2
},
{
"name": "cars_like",
"isCompound": "true",
"variableType": "singleChoie",
"fields": [{"code": "bwm"},{"code": "ford"},+++],
"options": [{"code": "yes"},{"code": "no"},+++]
}Other specify
All variables with an options or a fields property can have related "Other" properties. The Other properties are specified on an option or a field, and allow the respondent to add textual input when that option or field is selected/answered.
{
"name": "single", (1)
"variableType": "singleChoice",
"options": [
{"code": "bwm"},
{"code": "ford", "hasOtherField": "true"}
]
},
{
"name": "multi", (2)
"variableType": "multiChoice",
"options": [
{"code": "bwm"},
{"code": "ford", "hasOtherField": "true"}
]
},
{
"name": "opentextlist", (3)
"isCompound": "true",
"variableType": "text",
"fields": [
{"code": "bwm", "hasOtherField": "true"},
{"code": "ford", "hasOtherField": "true"}
]
},
{
"name": "grid", (4)
"isCompound": "true",
"variableType": "singleChoice",
"fields": [
{"code": "bwm"},
{"code": "ford"}],
"options": [
{"code": "yes", "hasOtherField": "true"},
{"code": "no", "hasOtherField": "true"}
]
}| 1 | This variable will have two value datapoints. "single": "ford" and "single.ford$Other": "I like Ford." |
| 2 | This variable will have one object datapoint with two properties. "multi": {"true": ["bmw", "ford"], "ford$Other": "I like Ford."} |
| 3 | Several fields can have an Other property on a compound variable. "opentextlist": {"bmw": "Good car", "bmw$Other": "I like it", "ford": "Not so good", "ford$Other": "I don’t like it."} |
| 4 | Several options can have an Other property on a compound singleChoice variable. "grid": {"bmw": "yes", "bmw$Other": "I like it", "ford": "no", "ford$Other": "I don’t like it."} |