Question File (.qsf)

The question file contains information related to CAPI (Computer-Assisted Personal Interviewing) data entry applications. Such information includes question text to appear on the screen with each field and help screens to appear when the operator presses the help (F2) key on desktop or the ? icon on mobile.

File Format

Most users do not need to understand the internal format of the .qsf file, but for advanced users who wish to use their own tools to read or generate question files the following section describes the file format.

You should avoid editing the question text file by hand, since small changes to the content or indentation can easily render the file unreadable by CSPro.

The .qsf file is in YAML format with UTF-8 encoding.

At the top-level the .qsf contains a mapping (associative array) with the following keys:

fileType: always set to "Question Text"
version: version of CSPro that created the question text file; for example "CSPro 8.0"
languages: list of languages used in the question text file
styles: list of styles used in the question text file
questions: list of questions, with one entry for each field or block in the data entry application that contains non-blank question or help text

Languages

Each language is a mapping with two keys, name and label, which contain the name and label defined in the languages dialog available from the CAPI menu.

languages:
 - name: EN
  label: English
 - name: FR
  label: French

Styles

The list of styles is used to populate the styles dropdown in the question text editor which can be customized using the Edit Styles dialog available from the CAPI menu.

Styles are implemented using CSS (Cascading Style Sheets) classes. Since the question text itself is in HTML format, styles are applied to the question text using CSS classes just as one would in a standard HTML web page. Each style in the list of styles in the question text file is implemented using a CSS class that describes the style using standard CSS style rules.

Each style in the question text file is a mapping with three keys:

name: name displayed in the style dropdown and in the Edit Styles dialog
className: CSS class name used for the style in the HTML question text
css: CSS style definition

styles:
 - name: Normal
  className: normal
  css: |
   font-family: Arial;font-size: 16px;
 - name: Instruction
  className: instruction
  css: |
   font-family: Arial;font-size: 14px;color: #0000FF;

If you were defining the above classes in a CSS file rather in CSPro you would have:

.normal { font-family: Arial;font-size: 16px; }
.instruction { font-family: Arial;font-size: 14px;color: #0000FF; }

If in the question text editor in CSPro you set the style for a block of text, the editor will modify the HTML to apply the selected style; e.g.:

<p>A question with <span class="instruction">a style applied to this part</span>.</p>

Any HTML that does not have a class specified will have the normal style applied. This is done by applying the normal class to the body element of the HTML document.

Note: Prior to version 7.6, the format of the question text file was Rich Text Format (RTF). Opening an older data entry application in version 7.6 onwards will automatically convert the QSF file from RTF to HTML—though you must edit the QSF file to force the conversion. The original RTF will be retained as xxx.qsf.backup. Data entry applications with question text created or edited in version 7.6 can no longer be opened in older versions of CSPro.

Questions

The bulk of the question text is made up of a list of questions where each question is a mapping with a name and a list of conditions.

The name is the fully qualified name of the dictionary item that the question text is displayed for. This is name of the dictionary and the name of the item separated by period; e.g., SIMPLECAPI_DICT.AGE. For question text that is applied to blocks, the name is simply the name of the block with no dictionary name or period.

The conditions correspond to the entries in the conditions grid that appears underneath the question text editor. Even questions that have no conditions defined in the conditions grid still contain a condition in the .qsf file, although in such cases the condition logic is empty. Each condition has three keys: logic, questionText, and helpText. The logic is the CSPro expression from the conditions grid. The questionText and helpText are mappings from language code (the codes from the languages section described above) to the HTML for the question or help text.

questions:
  - name: SIMPLECAPI_DICT.RELATIONSHIP
    conditions:
      - logic: headKnown = 0
        questionText:
          EN: |
            <p><span class="name">~~PersonName()~~:</span> Are you the head of household? If not, what is your relationship to the head?</p>
          FR: |
            <p><span class="name">~~PersonName()~~:</span> Êtes-vous le chef de ménage? Sinon, quel est votre lien de parenté avec le chef?</p>

        helpText:
          EN: |
          FR: |

      - logic: headKnown = 1
        questionText:
          EN: |
            <p><span class="name">~~PersonName()~~:</span> What is your relationship to ~~headText~~?</p>
          FR: |
            <p><span class="name">~~PersonName()~~:</span> Quel est votre lien de parenté avec ~~headText~~?</p>

        helpText:
          EN: |
          FR: |

See also: HTML Question Text