Retrieve Survey JSON Schema
GET {{baseUrl}}/surveys/:surveyId/response-schema
Introduction
This documentation is meant to help explain the purpose and value of the Retrieve the JSON Schema endpoint in the public api. In short, this endpoint provides a standard JSON Schema that can be used for parsing the results from the Retrieve a Survey Response endpoint and the Create Response Export endpoint when exporting in the json format. Finally this endpoint can also be useful for preparing responses for the Create a New Response endpoint.
Example
Note, before reading through this example, it might be helpful to take a quick detour and gain a bit of familiarity around Json Schemas.
For this example we created a simple survey with a single multiple choice question Which type of Ice Cream is your favorite? and 4 options Chocolate, Vanilla, Cookies & Cream, and Strawberry.
Here's an example response that we requested from the Retrieve a Survey Response endpoint:
{
"responseId": "R_240YEnuWbbwZOy1",
"values": {
"startDate": "2020-05-13T19:26:15Z",
"endDate": "2020-05-13T19:26:18Z",
"status": 0,
"ipAddress": "70.103.180.85",
"progress": 100,
"duration": 2,
"finished": 1,
"recordedDate": "2020-05-13T19:26:18.487Z",
"locationLatitude": "40.3941955566",
"locationLongitude": "-111.848297119",
"distributionChannel": "anonymous",
"userLanguage": "EN",
"QID1": 3,
"QID1_DO": [
"1",
"2",
"3",
"4"
]
},
"labels": {
"status": "IP Address",
"finished": "True",
"QID1": "Cookies & Cream",
"QID1_DO": [
"Chocolate",
"Vanilla",
"Cookies & Cream",
"Strawberry"
]
},
"displayedFields": [
"QID1"
],
"displayedValues": {
"QID1": [
1,
2,
3,
4
]
}
}
Now, let's look at the pieces of the schema to understand them a little better. Note: this documentation won't attempt to cover all the aspects of the JSON Schema specification, for more information see https://json-schema.org/.
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"$id": "http://qualtrics.com/API/v3/surveys/SV_ai71yqu2ZLvpadf/response-schema",
"title": "JSON Schema Example (SV_ai71yqu2ZLvpadf) - Survey Response",
"description": "This is a schema for survey responses from SV_ai71yqu2ZLvpadf",
"type": "object",
The schema starts with several standard fields from the Json Schema specification. The value for $schema is explained here and the value for $id is explained here. Then, the schema is given a title and a description. Finally, the schema is defined for a JSON object primitive type.
"required": [
"values",
"displayedFields",
"displayedValues",
"labels",
"responseId"
],
Next, the required field specifies that our JSON object will have the certain required fields. Looking back at our example response, we see that each of these fields is present.
"properties": {
"responseId": {
"type": "string"
},
Inside of the properties object, each field previously mentioned in the required array are given a schema. The simplest of these fields is the responseId field which will just be provided as a string.
"displayedFields": {
"type": "array",
"description": "A list of questions or question rows that were displayed to the survey respondent",
"items": {
"type": "string"
}
},
"displayedValues": {
"type": "object",
"description": "A list of the possible answers shown to the survey respondent for each question or question row",
"additionalProperties": {
"type": "array"
}
},
"labels": {
"type": "object",
"description": "The labels of the answers given by the survey respondent for each question or question row",
"additionalProperties": true
},
The next fields displayedFields, displayedValues, and labels have descriptions built in to the schema. Again, we can see how these schemas translate into a response object by consulting our example.
"values": {
"type": "object",
"description": "The answers given by the survey respondent",
"properties": {
"QID1": {
"description": "Which type of Ice Cream is your favorite?",
"dataType": "question",
"type": "number",
"oneOf": [
{
"label": "Chocolate",
"const": 1
},
{
"label": "Vanilla",
"const": 2
},
{
"label": "Cookies & Cream",
"const": 3
},
{
"label": "Strawberry",
"const": 4
}
],
"exportTag": "Q1",
"questionId": "QID1"
},
"recordedDate": {
"description": "Recorded Date",
"dataType": "metadata",
"type": "string",
"format": "date-time",
"exportTag": "RecordedDate"
},
"duration": {
"description": "Duration (in seconds)",
"dataType": "metadata",
"type": "number",
"exportTag": "Duration (in seconds)"
},
Finally, the values property defines the schema for each value available in the response. I've pulled a couple of the fields from the schema into this documentation but we can see from the example response that there are many more fields in this schema. Here we can see a description for each field as well as a type and several other pieces of information. We can see that the type matches up with the JSON data type for each value as found in the example response. The dataType can be used to know the source for that value and the exportTag is useful for understanding the header columns when using the Create Response Export endpoint with the CSV or TSV formats. Lastly, oneOf enumerates the possible options for values that have a known, finite domain. For this example, a multiple choice question would have a oneOf field since there are only 4 possible values. However, a text entry field that only allows numbers would not have a oneOf field, since the domain can't be enumerated.
Additional Tooling for JSON Schemas
One of the benefits of having a schema is that it can be used to automate some of the parsing and usage of json schemas. One such tool for automating this step is Quicktype. More information about that tool can be found on Github.
HEADERS
| Key | Datatype | Required | Description |
|---|---|---|---|
Accept | string |
RESPONSES
status: OK
{"result":{"$schema":"https://json-schema.org/draft/2019-09/schema","$id":"\u003curi\u003e","title":"\u003cstring\u003e","description":"\u003cstring\u003e","type":"object","properties":{"displayedFields":{"description":"\u003cstring\u003e","type":"array","items":{"type":"string"}},"displayedValues":{"description":"\u003cstring\u003e","type":"object","additionalProperties":{"type":"array"}},"labels":{"description":"\u003cstring\u003e","type":"object","additionalProperties":true},"responseId":{"type":"string"},"values":{"type":"object","description":"\u003cstring\u003e","properties":{"distributionChannel":{"type":"string","description":"\u003cstring\u003e","format":"date-time","questionId":"\u003cstring\u003e","loopNumber":"\u003cinteger\u003e","exportTag":"\u003cstring\u003e","questionExportTag":"\u003cstring\u003e","dataType":"embeddedData","oneOf":[{"label":"\u003cstring\u003e","et29":"dolore Excepteur tempor","Excepteur378":"magna ipsum dolor","mollit_9":"culpa labore ut consectetur"},{"label":"\u003cstring\u003e","reprehenderit_61e":-92717689.08381478}],"items":{"type":"\u003cstring\u003e","oneOf":[{"label":"\u003cstring\u003e","non_3d":2490702,"laboris_fbe":31595945,"eu_e":-59690066.11089797},{"label":"\u003cstring\u003e"}],"properties":{"x":{"type":"number"},"y":{"type":"number"}}}},"duration":{"type":"number","description":"\u003cstring\u003e","format":"date-time","questionId":"\u003cstring\u003e","loopNumber":"\u003cinteger\u003e","exportTag":"\u003cstring\u003e","questionExportTag":"\u003cstring\u003e","dataType":"embeddedData","oneOf":[{"label":"\u003cstring\u003e","sedf7":true,"aute5":"reprehenderit ea dolore et exercitation"},{"label":"\u003cstring\u003e","occaecat6":71796991.001497}],"items":{"type":"\u003cstring\u003e","oneOf":[{"label":"\u003cstring\u003e","consequat2b6":6151572.31789434},{"label":"\u003cstring\u003e","estfd":"dolor in dolor incididunt occaecat","Duis419":true}],"properties":{"x":{"type":"number"},"y":{"type":"number"}}}},"endDate":{"type":"number","description":"\u003cstring\u003e","format":"date-time","questionId":"\u003cstring\u003e","loopNumber":"\u003cinteger\u003e","exportTag":"\u003cstring\u003e","questionExportTag":"\u003cstring\u003e","dataType":"question","oneOf":[{"label":"\u003cstring\u003e"},{"label":"\u003cstring\u003e","sint9":true,"aute_bf3":-95747011,"aliquip5":-99852276.99877797,"sunt_9ff":28836403.60252829,"qui_f27":-912431.4861334264}],"items":{"type":"\u003cstring\u003e","oneOf":[{"label":"\u003cstring\u003e","dolorc9f":36479825},{"label":"\u003cstring\u003e"}],"properties":{"x":{"type":"number"},"y":{"type":"number"}}}},"finished":{"type":"array","description":"\u003cstring\u003e","format":"date-time","questionId":"\u003cstring\u003e","loopNumber":"\u003cinteger\u003e","exportTag":"\u003cstring\u003e","questionExportTag":"\u003cstring\u003e","dataType":"embeddedData","oneOf":[{"label":"\u003cstring\u003e","etb":62020279},{"label":"\u003cstring\u003e","dolor_87":91704699,"officia_c":true}],"items":{"type":"\u003cstring\u003e","oneOf":[{"label":"\u003cstring\u003e"},{"label":"\u003cstring\u003e"}],"properties":{"x":{"type":"number"},"y":{"type":"number"}}}},"locationLatitude":{"type":"string","description":"\u003cstring\u003e","format":"date-time","questionId":"\u003cstring\u003e","loopNumber":"\u003cinteger\u003e","exportTag":"\u003cstring\u003e","questionExportTag":"\u003cstring\u003e","dataType":"metadata","oneOf":[{"label":"\u003cstring\u003e","ametc73":"laboris nulla c","sint8":"reprehenderit labore et"},{"label":"\u003cstring\u003e","Ut_4":false,"eu_e":"veniam Ut pariatur aliqua irure"}],"items":{"type":"\u003cstring\u003e","oneOf":[{"label":"\u003cstring\u003e","in_69":"ad labore elit","voluptate_b":true,"sit_3":88223718,"exaab":-57189896},{"label":"\u003cstring\u003e","voluptatee":true}],"properties":{"x":{"type":"number"},"y":{"type":"number"}}}},"locationLongitude":{"type":"array","description":"\u003cstring\u003e","format":"date-time","questionId":"\u003cstring\u003e","loopNumber":"\u003cinteger\u003e","exportTag":"\u003cstring\u003e","questionExportTag":"\u003cstring\u003e","dataType":"embeddedData","oneOf":[{"label":"\u003cstring\u003e","Excepteur_0b2":"eu in Excepteur sit","eu__7":-23174036},{"label":"\u003cstring\u003e","dolor_92c":62445618.34723669}],"items":{"type":"\u003cstring\u003e","oneOf":[{"label":"\u003cstring\u003e","ex_a":true,"mollit_4":false},{"label":"\u003cstring\u003e"}],"properties":{"x":{"type":"number"},"y":{"type":"number"}}}},"progress":{"type":"string","description":"\u003cstring\u003e","format":"date-time","questionId":"\u003cstring\u003e","loopNumber":"\u003cinteger\u003e","exportTag":"\u003cstring\u003e","questionExportTag":"\u003cstring\u003e","dataType":"metadata","oneOf":[{"label":"\u003cstring\u003e","elit_a":"laborum velit dolore do"},{"label":"\u003cstring\u003e","veniam5":false,"irure_8d":-99936864}],"items":{"type":"\u003cstring\u003e","oneOf":[{"label":"\u003cstring\u003e","sit_4":-12796452.081510171,"sed_5":-57713155.277337916},{"label":"\u003cstring\u003e","non_c6":false}],"properties":{"x":{"type":"number"},"y":{"type":"number"}}}},"recordedDate":{"type":"object","description":"\u003cstring\u003e","format":"date-time","questionId":"\u003cstring\u003e","loopNumber":"\u003cinteger\u003e","exportTag":"\u003cstring\u003e","questionExportTag":"\u003cstring\u003e","dataType":"embeddedData","oneOf":[{"label":"\u003cstring\u003e"},{"label":"\u003cstring\u003e","laboris_299":true}],"items":{"type":"\u003cstring\u003e","oneOf":[{"label":"\u003cstring\u003e","sed_c":59860799,"qui_7":false},{"label":"\u003cstring\u003e","sede":"do amet culpa","ullamco_4c":false}],"properties":{"x":{"type":"number"},"y":{"type":"number"}}}},"startDate":{"type":"string","description":"\u003cstring\u003e","format":"date-time","questionId":"\u003cstring\u003e","loopNumber":"\u003cinteger\u003e","exportTag":"\u003cstring\u003e","questionExportTag":"\u003cstring\u003e","dataType":"question","oneOf":[{"label":"\u003cstring\u003e","ut3":-78155254.43631169,"in_f":true},{"label":"\u003cstring\u003e","adipisicing_6":-16926890.9844428}],"items":{"type":"\u003cstring\u003e","oneOf":[{"label":"\u003cstring\u003e","Ut_1":23456029.440747857},{"label":"\u003cstring\u003e","pariatur_d3":-28378067.027962923}],"properties":{"x":{"type":"number"},"y":{"type":"number"}}}},"status":{"type":"integer","description":"\u003cstring\u003e","format":"date-time","questionId":"\u003cstring\u003e","loopNumber":"\u003cinteger\u003e","exportTag":"\u003cstring\u003e","questionExportTag":"\u003cstring\u003e","dataType":"embeddedData","oneOf":[{"label":"\u003cstring\u003e","Lorem8":90794081,"nulla_56":-43405743,"Ut_15":"in aute veniam mollit incididunt"},{"label":"\u003cstring\u003e","etae9":-23642592}],"items":{"type":"\u003cstring\u003e","oneOf":[{"label":"\u003cstring\u003e","voluptate54":37977913},{"label":"\u003cstring\u003e","elit__c5":91536653}],"properties":{"x":{"type":"number"},"y":{"type":"number"}}}},"userLanguage":{"type":"object","description":"\u003cstring\u003e","format":"date-time","questionId":"\u003cstring\u003e","loopNumber":"\u003cinteger\u003e","exportTag":"\u003cstring\u003e","questionExportTag":"\u003cstring\u003e","dataType":"embeddedData","oneOf":[{"label":"\u003cstring\u003e","consequat_f":"occaecat","culpa_0":true},{"label":"\u003cstring\u003e","reprehenderit97a":true}],"items":{"type":"\u003cstring\u003e","oneOf":[{"label":"\u003cstring\u003e"},{"label":"\u003cstring\u003e"}],"properties":{"x":{"type":"number"},"y":{"type":"number"}}}}},"required":["\u003cstring\u003e","\u003cstring\u003e"]}},"required":["\u003cstring\u003e","\u003cstring\u003e"]},"meta":{"httpStatus":"\u003cstring\u003e","requestId":"\u003cstring\u003e","notice":"\u003cstring\u003e"}}