QuestionForm Data

Description

The QuestionForm data format describes a "question" for a HIT, or for a Qualification test. It contains data to be used in answering the question, and a set of one or more form fields, which are rendered as a web form for a Worker to fill out and submit. Data can include text, bulleted lists, and images. Form fields can be multiple choice or text fields.

A QuestionForm is a string value that consists of XML data. The XML data must conform to the QuestionForm schema. See WSDL and Schema Locations for the location of this schema. For more information about using XML data as parameter or return value, see Using XML Parameter Values.

Note:

The "answer specification" for a question influences how the Worker sees the question at the Mechanical Turk web site. It also tells Mechanical Turk to perform some validation of the data submitted via the web form. Neither the requested display nor validation of the answers are guaranteed by the Mechanical Turk Service. When your application retrieves the answer data, it should check that the data sufficiently answers the question.

The QuestionForm data structure is used as a parameter for the following operations:

The QuestionForm data structure is a value in a HIT data structure, and a value in a QualificationType data structure.

All elements in a QuestionForm belong to a namespace whose name is identical to the URL of the QuestionForm schema document for the version of the API you are using.

The Structure of a QuestionForm

The top-most element of a QuestionForm data structure is a QuestionForm element. The element contains an optional Overview element, and one or more Question elements.

The Overview element describes instructions and information presented separately from the set of questions. It can contain any kind of informational content, as described below. If omitted, no overview text will be displayed above the questions.

Each Question element can contain the following elements:

Name Description Type Value
QuestionIdentifier

An identifier for the question. This identifier is used to associate the Worker's answers with the question in the answer data.

Required

An alphanumeric string

DisplayName

A name for the question, displayed as a prominent heading. It is optional.

Optional

A string

IsRequired

This is true if the Worker must provide an answer for this question to successfully submit the form. If not specified, the default is false.

Optional

A Boolean value, either true or false

QuestionContent

The instructions and data specific to this question, such as the text of the question. It can contain any kind of informational content, as described below.

Required

A content structure, as described below

AnswerSpecification

A structure describing the field type and possible values for the answer to this question. This controls how the form field is rendered, and describes which values are valid answers for this question.

Required

An answer specification structure, as described below

The Structure of Content

The Overview element and the QuestionContent elements of a QuestionForm can contain information of several kinds. Each kind of information is specified with a corresponding element. These elements can appear in any number, in any order. The content elements are rendered in the order they appear in the containing element, much like HTML elements in a web page.

The following kinds of information can be included in content: Title, Text, List, and Binary.

Title

A Title element specifies a string to be rendered as a title or heading. 

<Title>The Next Move</Title>

Text

A Text element specifies a block of text to be rendered as a paragraph. Only plain text is allowed. HTML is not allowed. If HTML characters (such as angle brackets) are included in the data, they will be displayed as is in the web form. 

<Text>What is the best next move for "X" in this game of Tic-Tac-Toe?</Text>

List

A List element displays a bulleted list of items. Items are specified using one or more ListItem elements inside the List, each of which can contain text. 

<List>
  <ListItem>It must be a valid move.</ListItem>
  <ListItem>"X" cannot resign.</ListItem>
</List>

Binary

A Binary element specifies non-textual data of some kind. It contains a MimeType element, a DataURL element, and a AltText element.

MimeType element specifies the type of the data, using Type and SubType elements. Currently, only the image type is supported. SubType specifies the format of the image, such as gif. Other types may be supported in a future version of the service.

The data itself is specified with a DataURL element, which contains a valid HTTP URL that refers to the data.

Finally, a AltText element specifies what text should appear if the data cannot be rendered in the browser. 

<Binary>
  <MimeType>
    <Type>image</Type>
    <SubType>gif</SubType>
  </MimeType>
  <DataURL>http://tictactoe.amazon.com/game/01523/board.gif</DataURL>
  <AltText>The game board, with "X" to move.</AltText>
</Binary>

The Answer Specification

The AnswerSpecification element describes the format and possible values for answers to a question. It contains either a FreeTextAnswer element, which describes a text field, or a SelectionAnswer element, which describes a multiple choice field.

FreeTextAnswer

A FreeTextAnswer describes a text field, and constraints on its possible values. It contains an optional Constraints element, an optional DefaultText element, and an optional NumberOfLinesSuggestion element.

Note:

A Qualification test that is to be graded automatically using an answer key cannot have any free-text questions. An answer key can only match multiple-choice questions, and cannot match free-text fields.

The optional Constraints element describes constraints on the possible values that are accepted in the text field. The mechanism presenting the question to the Worker (such as the Mechanical Turk web site) may use these constraints to render the question and validate the answer, though this is not guaranteed.

If the Constraints element contains an IsNumeric element, then the value the Worker enters must be a number. IsNumeric is an empty element with two optional attributes: minValue specifies a minimum number value, and maxValue specifies a maximum.

If the Constraints element contains a Length element, then the value the Worker enters must be of a length within the given range. Length is an empty element with two optional attributes: minLength specifies a minimum number of characters, and maxLength specifies a maximum.

If no constraints are specified, any value is accepted for the field.

An optional DefaultText element specifies a default value for the field. This value appears in the form when it is rendered, and is accepted as the answer if the Worker does not change it. The default is an empty value.

An optional NumberOfLinesSuggestion element specifies how tall the form field should be, if possible. The field may or may not be rendered as a text box with this many lines, depending on the device the Worker is using to see the form. The default is a one-line text box. 

<FreeTextAnswer>
  <Constraints>
    <Length minLength="2" maxLength="2" />
  </Constraints>
  <DefaultText>C1</DefaultText>
</FreeTextAnswer>

SelectionAnswer

A SelectionAnswer describes a multiple-choice question. The Worker can select zero, one or multiple items from a set list as the answer to the question. SelectionAnswer contains optional MinSelectionCount and MaxSelectionCount elements to restrict the number of options that make up a valid answer, an optional StyleSuggestion element to recommend a particular kind of multiple-choice display, and a Selections element that lists the options.

Optional MinSelectionCount and MaxSelectionCount elements specify a minimum number of selections, and a maximum number of selections, respectively. MinSelectionCount can be from 0 up to the number of selections, and defaults to 1. MaxSelectionCount can be from 1 up to the number of selections, and defaults to 1.

An optional StyleSuggestion element specifies what style of multiple-choice form field to use when displaying the question to the Worker. The styles radiobutton and dropdown can be used if MaxSelectionCount is 1 (the default), as they restrict the user to selecting zero or one items from the list. The styles checkbox, list, combobox, and multichooser allow for multiple selections, though they can also be restricted using MaxSelectionCount. The field may or may not use the suggested style, depending on the device the Worker is using to see the form.

The Selections element contains one or more Selection elements, one for each possible answer in the set. A Selection element contains an SelectionIdentifier, a unique alphanumeric string that will be in the answer data if this selection is chosen, and either a Text element or a Binary element containing the content of the option. Text specifies a string, and Binary specifies binary data. See the explanation of content, above, for more information on the Binary element.

A Selections element may optionally contain an OtherSelection element, which specifies a text field to display below the selection list, allowing the Worker to enter an alternate answer that does not appear in the list of selections. The contents of OtherSelection are similar to FreeTextAnswer, described above.

Note:

A Qualification test that is to be graded automatically using an answer key cannot have an OtherSelection field for a multiple choice question. An answer key can only match multiple-choice questions, and cannot match free-text fields. 
<SelectionAnswer>
  <StyleSuggestion>radiobutton</StyleSuggestion>
  <Selections>
    <Selection>
      <SelectionIdentifier>C1</SelectionIdentifier>
      <Text>C1 (northeast)</Text>
    </Selection>
    <Selection>
      <SelectionIdentifier>C2</SelectionIdentifier>
      <Text>C2 (east)</Text>
    </Selection>
    <Selection>
      <SelectionIdentifier>A3</SelectionIdentifier>
      <Text>A3 (southwest)</Text>
    </Selection>
    <Selection>
      <SelectionIdentifier>C3</SelectionIdentifier>
      <Text>C3 (southeast)</Text>
    </Selection>
  </Selections>  
</SelectionAnswer>

Example

The following is an example of a complete QuestionForm data structure. Remember that to pass this structure in as a parameter to an operation, XML characters must be escaped as character entities. 

<QuestionForm xmlns="[the QuestionForm schema URL]">
  <Overview>
    <Title>Game 01523, "X" to play</Title>
    <Text>
      You are helping to decide the next move in a game of Tic-Tac-Toe.  The board looks like this:
    </Text>
    <Binary>
      <MimeType>
        <Type>image</Type>
        <SubType>gif</SubType>
      </MimeType>
      <DataURL>http://tictactoe.amazon.com/game/01523/board.gif</DataURL>
      <AltText>The game board, with "X" to move.</AltText>
    </Binary>
    <Text>
      Player "X" has the next move.
    </Text>
  </Overview>
  <Question>
    <QuestionIdentifier>nextmove</QuestionIdentifier>
    <DisplayName>The Next Move</DisplayName>
    <IsRequired>true</IsRequired>
    <QuestionContent>
      <Text>
        What are the coordinates of the best move for player "X" in this game?
      </Text>
    </QuestionContent>
    <AnswerSpecification>
      <FreeTextAnswer>
        <Constraints>
          <Length minLength="2" maxLength="2" />
        </Constraints>
        <DefaultText>C1</DefaultText>
      </FreeTextAnswer>
    </AnswerSpecification>
  </Question>
  <Question>
    <QuestionIdentifier>likelytowin</QuestionIdentifier>
    <DisplayName>The Next Move</DisplayName>
    <IsRequired>true</IsRequired>
    <QuestionContent>
      <Text>
        How likely is it that player "X" will win this game?
      </Text>
    </QuestionContent>
    <AnswerSpecification>
      <SelectionAnswer>
        <StyleSuggestion>radiobutton</StyleSuggestion>
        <Selections>
          <Selection>
            <SelectionIdentifier>notlikely</SelectionIdentifier>
            <Text>Not likely</Text>
          </Selection>
          <Selection>
            <SelectionIdentifier>unsure</SelectionIdentifier>
            <Text>It could go either way</Text>
          </Selection>
          <Selection>
            <SelectionIdentifier>likely</SelectionIdentifier>
            <Text>Likely</Text>
          </Selection>
        </Selections>
      </SelectionAnswer>
    </AnswerSpecification>
  </Question>
</QuestionForm>