The QuestionForm data format describes
one or more "questions" for a HIT, or for a
Qualification test. It contains instructions and data to be
used in answering the questions, and a set of one or more form
fields, which are rendered as a web form for a Worker to fill
out and submit.
Tip: | For information about creating HITs that use your own web site in a frame instead of questions, see the ExternalQuestion data structure. |
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 a 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 value for the
following operations:
CreateHIT
CreateQualificationType
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 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.
<QuestionForm xmlns="[the QuestionForm schema URL]"> <Overview>[...]</Overview> <Question>[...]</Question> <Question>[...]</Question>[...]</QuestionForm>
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 | Optional |
A Boolean value, either |
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 |
For example:
<Question>
<QuestionIdentifier>my_question_id</QuestionIdentifier>
<DisplayName>My Question</DisplayName>
<IsRequired>true</IsRequired>
<QuestionContent>
[...]
</QuestionContent>
<AnswerSpecification>
[...]
</AnswerSpecification>
</Question>
The Overview element and the
QuestionContent elements of a
QuestionForm can contain information of
several kinds. For example, you might include a paragraph of
text and an image in your HIT's overview.
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.
The following kinds of information can be included in content:
Title, a text heading
Text, a paragraph of text
List, a bulleted list
Binary, either a static image, an audio clip, or a video clip
Application, either a Java applet or a Flash movie
FormattedContent, text with detailed formatting information specified using XHTML tags
A Title element specifies a string to
be rendered as a title or heading.
<Title>The Next Move</Title>
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>
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>
A Binary element specifies non-textual
data of some kind, such as an image, audio or video. 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. The supported types
are image,
audio, and
video. SubType
specifies the format of the item, such as
gif.
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>
An Application element specifies an
embedded application, such as a Java applet or a Flash movie.
It contains either a JavaApplet element
or a Flash element.
You can specify zero or more parameters to pass to your Java
applet or Flash application when it is opened in the web page.
For a HIT, in addition to the parameters you specify,
Mechanical Turk will include two parameters specific to the
HIT: a hitId parameter, equal to the ID of the
HIT, and assignmentId, equal to the ID of the
assignment if the Worker has accepted the HIT, or equal to
ASSIGNMENT_ID_NOT_AVAILABLE if the Worker is only
previewing the HIT.
JavaApplet includes the following elements:
AppletPath, the URL path to
the directory that contains Java classes for the
applet.
AppletFilename, the name of
the class file containing the applet code, which is located
in the path specified by
AppletPath
Width and
Height, the size of the bounding box
for the applet
zero or more
ApplicationParameter elements, each
containing a Name and a
Value, as parameters to be passed to
the applet when it starts up
Flash includes the following elements:
FlashMovieURL, the URL of the
Flash movie file
Width and
Height, the size of the bounding box
for the Flash movie
zero or more
ApplicationParameter elements, each
containing a Name and a
Value, as parameters to be passed to
the Flash movie when it starts up
<Application>
<JavaApplet>
<AppletPath>http://tictactoe.amazon.com/applets/</AppletPath>
<AppletFilename>GameViewer.class</AppletFilename>
<Width>400</Width>
<Height>300</Height>
<ApplicationParameter>
<Name>game_id<Name>
<Value>01523</Value>
</ApplicationParameter>
</JavaApplet>
</Application>
For finer control over the display of your HIT information,
you can specify a FormattedContent
element. Formatted content is a block of text with formatting
information specified using XHTML tags. For example, you can
use XHTML tags to specify that certain words appear in a
boldface font, or to include a table in your HIT information.
Only a limited subset of XHTML is supported. For more information on the creating and validating XHTML formatted content, see Formatted Content: XHTML.
The value of the FormattedContent
element must be specified as an XML CDATA block. CDATA tells the
web service that the XHTML elements are not part of the
QuestionForm data schema. For example,
the following describes a paragraph of formatted text:
<FormattedContent><![CDATA[ <p>This is a paragraph with <b>bold text,</b> <i>italic text,</i> and <b><i>bold italic text</i></b>.</p> ]]></FormattedContent>
The AnswerSpecification element describes
the format and possible values for answers to a question. It
contains a FreeTextAnswer element, which
describes a text field; a SelectionAnswer
element, which describes a multiple choice field; or, a
FileUploadAnswer, which prompts the
Worker to upload a file as the answer to the question.
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>
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
|
<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>
A FileUploadAnswer prompts the Worker
to upload a file as the answer to the question. When the
Worker uploads the file, Amazon Mechanical Turk stores the
file separately from the answer data. Once the HIT is
submitted, your application can call the
GetFileUploadURL operation to get a
temporary URL it can use to download the file.
The FileUploadAnswer specification
contains two elements, a
MinFileSizeInBytes and a
MaxFileSizeInBytes, that specify the
minimum and maximum allowed file sizes, respectively. If the
Worker uploads a file whose size in bytes is outside of this
range, the answer will be rejected, and the Worker will have
to upload a different file to complete the HIT. You can
specify a maximum size up to 2000000000
(2 billion) bytes.
Note: |
A |
<FileUploadAnswer> <MaxFileSizeInBytes>3000000</MaxFileSizeInBytes> <MinFileSizeInBytes>1000</MinFileSizeInBytes> </FileUploadAnswer>
The following is an example of a complete
QuestionForm data structure. Remember
that to pass this structure in as a value of a parameter to an
operation, XML characters must be escaped as character entities. (See Using XML Parameter Values for more information.)
<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>