Skip to content

Step 2: Create a corresponding .json file for an assessment tool

The corresponding <measurement_tool>.json file is used to provide a detailed description of the content of the measurement_tool.tsv file in a human as well as machine actionable way.

Every column of the <measurement_tool>.tsv must be explained in the <measurement_tool>.json file.

Schema used for .json files

Assessment tools usually contain multiple items which may vary in their response style. For now we adopt the reproschema to provide the information about each item. Please note that we do not use the full schema when creating the <measurement_tool>.json file.

Example of one item in <measurement_tool>.json (Toronto Alexithymia Scale - TAS-26)

In the survey the first item of the TAS-26 is presented to the participant via the survey software as follows:

LimeSurvey question

To also make this information accessible to people who want to reuse your data we add a detailed description using reproschema elements. The following example concerns an item where participants had to answer on a discrete rating scale between 1 and 5. According to reproschema this is a singlechoice item. The answer to this item is corresponds to the value in the column tas[tas01] of the toronto_alexithymia_scale.tsv. The json file describes the meaning of all possible values in this column. Note that although the description for a single item is extensive, it will not differ much between the items of the same questionnaire, so you can usually copy the description for the other items and update a few fields to get a description of the full questionnaire.

"tas[tas01]": { 
      "description": "Toronto Alexithymia Scale Item 1", 
      "question": {
        "de": "Wenn ich weine, weiß ich immer warum. ",
        "en": "When I cry I always know why."
      },
      "TermURL": "[Optional] Please fill in if possible. We are currently working on finding a way to provide TermURLs for specific questionnaire items."
      "responseOptions": {
        "valueType": "xsd:integer",
        "multipleChoice":false,
        "minValue": 1,
        "maxValue": 5,
        "choices": [
          {
            "name": {
              "de": "trifft gar nicht zu",
              "en": "Strongly disagree"
            },
            "value": 1
          },
          {
            "name": {
              "de": "trifft eher nicht zu",
              "en": "Disagree"
            },
            "value": 2
          },
          {
            "name": {
              "de": "trifft teilweise zu / teilweise nicht zu",
              "en": "Neither agree nor disagree"
            },
            "value": 3
          },
          {
            "name": {
              "de": "trifft eher zu",
              "en": "Agree"
            },
            "value": 4
          },
          {
            "name": {
              "de": "trifft völlig zu",
              "en": "Strongly agree"
            },
            "value": 5
          }
        ]
      }
    }
participant_id tas[tas01] tas[tas02] tas[tas03] tas[tas04] tas[tas05] tas[tas06] tas[tas07] tas[tas08] tas[tas09] tas[tas10] tas[tas11] tas[tas12] tas[tas13] tas[tas14] tas[tas15] tas[tas16] tas[tas17] tas[tas18] tas[tas19] tas[tas20] tas[tas21] tas[tas22] tas[tas23] tas[tas24] tas[tas25] tas[tas26]
sub-001 trifft völlig zu trifft völlig zu trifft eher nicht zu trifft eher nicht zu trifft eher nicht zu trifft eher nicht zu trifft eher nicht zu trifft gar nicht zu trifft völlig zu trifft eher zu trifft völlig zu trifft eher zu trifft völlig zu trifft gar nicht zu trifft eher nicht zu trifft teilweise zu/teilweise nicht zu trifft gar nicht zu trifft eher nicht zu trifft völlig zu trifft eher zu trifft eher zu trifft eher nicht zu trifft eher nicht zu trifft völlig zu trifft gar nicht zu trifft völlig zu
sub-002 trifft eher nicht zu trifft gar nicht zu trifft eher nicht zu trifft teilweise zu/teilweise nicht zu trifft eher zu trifft eher nicht zu trifft eher zu trifft eher zu trifft eher zu trifft gar nicht zu trifft teilweise zu/teilweise nicht zu trifft teilweise zu/teilweise nicht zu trifft eher zu trifft teilweise zu/teilweise nicht zu trifft eher nicht zu trifft gar nicht zu trifft eher zu trifft gar nicht zu trifft eher nicht zu trifft eher nicht zu trifft eher zu trifft eher nicht zu trifft eher nicht zu trifft eher nicht zu trifft eher nicht zu trifft eher nicht zu

Disclaimer

For now the annotation process is a bit redundant - we are aware of that. We are working on a more convenient and less redundant way for describing questionnaires including their items. This is work in progress, but it is important for us not to lose valuable information about questionnaire data.

JSON templates for different question types

To get started you can use the assessment tool template provide here. It includes a description of the participant_id column required by the BIDS-specification and the template for a single choice item with four response options.

Combine the question templates provided below to insert them item for item to the assessment tool template and create a detailed description of your assessment tool:

Question type Template Comment
multiple choice Question that allows for multiple responses. CAUTION - there are diverging meanings to mutliple choice. Here it is meant that a participant is allowed to indicate more than one response (out of x response options).
single choice Question where only valid option has to be chosen from possible answers. Also valid for dichotomous questions and Likert-Scale.
free text response The content of this column in the <measurement_tool>.tsv MUST NOT include personal information (i.e. information such as work place or position, that makes it possible to re-identify the participant)
continuous response For example, slider responses

Feel free to adapt the provided templates in accordance with the reproschema or let us know if they are not sufficient for you.