# Question and Answer Data
<a name="ApiReference_QuestionAnswerDataArticle"></a>

**Topics**
+ [

# Crowd HTML Elements
](ApiReference_HTMLCustomElementsArticle.md)
+ [

# Using XML Parameter Values
](ApiReference_XMLParameterValuesArticle.md)
+ [

# HITLayout
](ApiReference_HITLayoutArticle.md)
+ [

# HTMLQuestion
](ApiReference_HTMLQuestionArticle.md)
+ [

# ExternalQuestion
](ApiReference_ExternalQuestionArticle.md)
+ [

# QuestionForm
](ApiReference_QuestionFormDataStructureArticle.md)
+ [

# QuestionFormAnswers
](ApiReference_QuestionFormAnswersDataStructureArticle.md)
+ [

# Formatted Content: XHTML
](ApiReference_FormattedContentXHTMLArticle.md)
+ [

# AnswerKey
](ApiReference_AnswerKeyDataStructureArticle.md)
+ [

# Data Structure Schema Locations
](ApiReference_SchemaLocationArticle.md)

 The questions and answers that Amazon Mechanical Turk passes between Requesters and Workers are XML documents that conform to schemas. These documents are passed to the service and returned by the service as parameter values.

# Crowd HTML Elements
<a name="ApiReference_HTMLCustomElementsArticle"></a>

**Topics**
+ [

## Description
](#ApiReference_HTMLCustomElementsArticle-description)
+ [

## Use Cases
](#ApiReference_HTMLCustomElementsArticle-usecases)
+ [

## Examples
](#ApiReference_HTMLCustomElementsArticle-examples)
+ [

## Element Reference
](#ApiReference_HTMLCustomElementsArticle-elementref)
+ [

## Related Documents
](#ApiReference_HTMLCustomElementsArticle-seealso)

## Description
<a name="ApiReference_HTMLCustomElementsArticle-description"></a>

**Crowd HTML Elements** extend the capabilities of the [ExternalQuestion](ApiReference_ExternalQuestionArticle.md) and [HTMLQuestion](ApiReference_HTMLQuestionArticle.md). They are web components that provide a number of task widgets and design elements that can be tailored to the question being asked.

## Use Cases
<a name="ApiReference_HTMLCustomElementsArticle-usecases"></a>

**Crowd HTML Elements** are web components, a web standard that abstracts HTML markup, CSS, and JavaScript functionality into an HTML tag or set of tags. If you'd like to see how that works, try the `<crowd-bounding-box>` example below. The element provides a bounding box widget which can be customized with different instructions, labels, and headers.

Other types of questions that can be customized include: semantic segmentation, image classification, text classification, utterance collection, and more.

## Examples
<a name="ApiReference_HTMLCustomElementsArticle-examples"></a>

To quickly try one of the examples below, open a text editor on your local machine, copy an example from this page, paste it into the text editor, and then save the file with whatever name you want and a `.html` extension. Open the file in a browser and the example should work. You can try customizing it further or adding other **Crowd HTML Elements** by exploring the [element reference](https://docs.aws.amazon.com/sagemaker/latest/dg/sms-ui-template-reference.html).

### Crowd HTML Essential Elements
<a name="ApiReference_HTMLCustomElementsArticle-examples-skel"></a>

Every use of **Crowd HTML Elements** requires two things:
+  The **Crowd HTML Elements** loader, which is a `<script>` element that should be placed before your form.

  `<script src="https://assets.crowd.aws/crowd-html-elements.js"></script>`
+ Opening and closing `<crowd-form>` tags. Put your form's content between the tags. The benefit to these is that they set up the specifications for your form and the "submit" button. You write less code and need to remember fewer specific things.

### Crowd HTML Bounding Box
<a name="ApiReference_HTMLCustomElementsArticle-examples-BoundingBox"></a>

Try this bounding box example. Copy it, paste it, and run it in a browser as instructed above.

**Example**  

```
<script src="https://assets.crowd.aws/crowd-html-elements.js"></script>

<crowd-form>
  <crowd-bounding-box
    name="annotatedResult"
    labels="['Basketball player', 'Referee']"
    src="https://s3.amazonaws.com/cv-demo-images/basketball-outdoor.jpg"
    header="Draw boxes around each basketball player and referee in this image"
  >
    <full-instructions header="Bounding Box Instructions" >
      <p>Use the bounding box tool to draw boxes around the requested target of interest:</p>
      <ol>
        <li>Draw a rectangle using your mouse over each instance of the target.</li>
        <li>Make sure the box does not cut into the target, leave a 2 - 3 pixel margin</li>
        <li>
          When targets are overlapping, draw a box around each object,
          include all contiguous parts of the target in the box.
          Do not include parts that are completely overlapped by another object.
        </li>
        <li>
          Do not include parts of the target that cannot be seen,
          even though you think you can interpolate the whole shape of the target.
        </li>
        <li>Avoid shadows, they're not considered as a part of the target.</li>
        <li>If the target goes off the screen, label up to the edge of the image.</li>
      </ol>
    </full-instructions>

    <short-instructions>
      Draw boxes around each basketball player and referee in this image.
    </short-instructions>
  </crowd-bounding-box>
</crowd-form>
```

Pay attention to the attributes and regions of the `<crowd-bounding-box>` element. It requires the `header`, `labels`, `name`, and `src` attributes. It also requires the `<full-instructions>` and `<short-instructions>` regions, though what is put in them is up to you.

The sample will also display the form output when you press the "submit" button, so you can see the format of the output you will receive.

### Crowd HTML Sentiment Analysis
<a name="ApiReference_HTMLCustomElementsArticle-examples-sentiment"></a>

Try this sentiment analysis example. Copy it, paste it, and run it in a browser as instructed above.

**Example**  

```
<script src="https://assets.crowd.aws/crowd-html-elements.js"></script>

<crowd-form>
    <crowd-classifier
      name="sentiment"
      categories="['Positive', 'Negative', 'Neutral', 'N/A']"
      header="What sentiment does this text convey?"
    >
      <classification-target>
        Everything is wonderful.
      </classification-target>
      
      <full-instructions header="Sentiment Analysis Instructions">
        <p><strong>Positive</strong> sentiments include: joy, excitement, delight</p>
        <p><strong>Negative</strong> sentiments include: anger, sarcasm, anxiety</p>
        <p><strong>Neutral</strong>: neither positive or negative, such as stating a fact</p>
        <p><strong>N/A</strong>: when the text cannot be understood</p>
        <p>When the sentiment is mixed, such as both joy and sadness, use your judgment to choose the stronger emotion.</p>
      </full-instructions>

      <short-instructions>
       Choose the primary sentiment that is expressed by the text. 
      </short-instructions>
    </crowd-classifier>
</crowd-form>
```

This shares some characteristics with other elements, like the bounding box above. For example, they both require a name, a header, and instructions. One thing that's notably different is the `<classification-target>` region. That has simple text in it, but it can contain just about any HTML: a video clip, an audio clip, an animation, anything that can be represented in a browser and simply classified.

## Element Reference
<a name="ApiReference_HTMLCustomElementsArticle-elementref"></a>

**[The Custom HTML Element Reference](https://docs.aws.amazon.com/sagemaker/latest/dg/sms-ui-template-reference.html)** provides a list of all supported custom elements, their requirements, attributes, and sample outputs (where appropriate).

## Related Documents
<a name="ApiReference_HTMLCustomElementsArticle-seealso"></a>
+ [HTMLQuestion](ApiReference_HTMLQuestionArticle.md)
+ [ExternalQuestion](ApiReference_ExternalQuestionArticle.md)
+ [Element Reference](https://docs.aws.amazon.com/sagemaker/latest/dg/sms-ui-template-reference.html)

# Using XML Parameter Values
<a name="ApiReference_XMLParameterValuesArticle"></a>

 The [HTMLQuestion](ApiReference_HTMLQuestionArticle.md#ApiReference_HTMLQuestionArticle.title),[ExternalQuestion](ApiReference_ExternalQuestionArticle.md#ApiReference_ExternalQuestionArticle.title), [QuestionForm](ApiReference_QuestionFormDataStructureArticle.md#ApiReference_QuestionFormDataStructureArticle.title), [QuestionFormAnswers](ApiReference_QuestionFormAnswersDataStructureArticle.md#ApiReference_QuestionFormAnswersDataStructureArticle.title), and [AnswerKey](ApiReference_AnswerKeyDataStructureArticle.md#ApiReference_AnswerKeyDataStructureArticle.title) data structures are used as parameter values in service requests, and as return values in service responses. Unlike other data structures described in this API reference, these XML structures are not part of the service API directly, but rather are used as string values going in and out of the service. This article describes the encoding methods needed to use XML data as parameter and return values.

## XML Data as a Parameter
<a name="ApiReference_XMLParameterValuesArticle-xml-data-as-a-parameter"></a>

 Data must be *URL encoded* to appear as a single parameter value in the request. Characters that are part of URL syntax, such as question marks (**?**) and ampersands (**&**), must be replaced with the corresponding URL character codes. 

**Note**  
 XML data should only be URL encoded, *not* XML escaped. 

 In service responses, this data will be XML escaped. 

## Namespaces for XML Parameter Values
<a name="ApiReference_XMLParameterValuesArticle-namespaces-for-xml-parameter-values"></a>

 XML data in parameter values must have a namespace specified for all elements. The easiest way to do this is to include an `xmlns` attribute in the root element equal to the appropriate namespace. 

 The namespace for a `HTMLQuestion`,`ExternalQuestion`, `QuestionForm`, `QuestionFormAnswers`, or `AnswerKey` element is identical to the URL of the corresponding schema document, including the version date. While XML namespaces need not be URLs according to the XML specification, this convention ensures that the consumer of the value knows which version of the schema is being used for the data. 

 For the locations of the schema documents, as well as instructions on how to include the version date in the URL, see [Schema Locations](ApiReference_SchemaLocationArticle.md#ApiReference_SchemaLocationArticle.title). 

# HITLayout
<a name="ApiReference_HITLayoutArticle"></a>

**Topics**
+ [

## Description
](#ApiReference_HITLayoutArticle-description)
+ [

## Obtaining a Layout ID
](#ApiReference_HITLayoutArticle-creatingHITlayoutId)
+ [

## Using a HITLayout
](#ApiReference_HITLayoutArticle-usingaHITlayoutId)
+ [

## Guidelines for Using HITLayouts
](#ApiReference_HITLayoutArticle-guidelines-for-using-HITLayout-questions)

## Description
<a name="ApiReference_HITLayoutArticle-description"></a>

A HITLayout is a reusable Amazon Mechanical Turk project template used to provide Human Intelligence Task (HIT) question data for `CreateHIT`. You can create a HITLayout template by creating a Mechanical Turk project on the [Amazon Mechanical Turk Requester website](https://requester.mturk.com/create/projects/new). For more information about creating a project, see [How to Create a Project](http://docs.aws.amazon.com/AWSMechTurk/latest/RequesterUI/CreatingaHITTemplate.html) in the [Requester UI Guide](http://docs.aws.amazon.com/AWSMechTurk/latest/RequesterUI/). 

## Obtaining a Layout ID
<a name="ApiReference_HITLayoutArticle-creatingHITlayoutId"></a>

A **Layout ID** is assigned to each Mechanical Turk project you create on the Requester website. You use the **Layout ID** as the value for `HITLayoutId` when calling `CreateHIT` to identify the HITLayout project template to use. Mechanical Turk projects can contain parameter placeholders in the format `${parameter_name}`. The names for the parameter placeholders used in a HITLayout project template are listed as **Parameters** along with the **Layout ID** on the Requester website. 

**To view the Layout ID and the Parameters used in your HITLayout project template**

1.  Go to the [Amazon Mechanical Turk Requester website](https://requester.mturk.com/). Or for the Requester Sandbox site, go to the [Amazon Mechanical Turk Requester Sandbox website](https://requestersandbox.mturk.com/). 

1.  Click **Create**, and then click **New Batch with an Existing Project**. 

1.  Click the **Project Name** of an existing project to view **Layout ID** and **Parameters**.   
![\[Click Project Name to View LayoutID\]](http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/images/AWS-Mturk-Existing-Projects-LayoutId-01.jpg)

## Using a HITLayout
<a name="ApiReference_HITLayoutArticle-usingaHITlayoutId"></a>

You can use the HITLayout form of a HIT by calling `CreateHIT` with a `HITLayoutId` and a list of [HITLayoutParameter](ApiReference_HITLayoutParameterArticle.md) structures. The project parameter placeholders are replaced with values from the [HITLayoutParameter](ApiReference_HITLayoutParameterArticle.md) structures when you call `CreateHIT` to create a HIT. You need one structure for each of the parameter values you want substituted. The parameter names that you pass to `CreateHIT` must match the parameter names used in the HITLayout project template created on the Requester website. The parameter values cannot be changed after the HIT has been created.

**Note**  
You can use either the `HITLayoutId` or the `Question` parameter when calling `CreateHIT`, but not both.

Each `CreateHIT` call merges the parameter values from HITLayoutParameter structures into the HITLayout template to generate the HIT question document. You use the same **Layout ID** in `HITLayoutId` to call `CreateHIT` multiple times, with different parameter values supplied each time for the placeholders.

Requesters can use this parameter substitution capability to create a large number of HITs that all share a common design. For example, you can create a HIT question that asks Workers to provide keywords for an image and draw boxes around key image features using a JavaScript library. First, you use the Requester website to create a Mechanical Turk project that uses a parameter placeholder for the image URL. Then you call `CreateHIT` using the same HITLayout template iteratively, using a different image URL value each time. Each call to `CreateHIT` uses the same **Layout ID**, but each call uses a different HITLayoutParameter structure that contains a unique image URL. 

## Guidelines for Using HITLayouts
<a name="ApiReference_HITLayoutArticle-guidelines-for-using-HITLayout-questions"></a>
+ After a HIT is created, the HIT behaves like an HTMLQuestion HIT, which gives you the option to use HTML and JavaScript features in your HIT design, including Asynchronous JavaScript and XML (AJAX) callbacks.
+ Parameter substitution allows you to replace a short parameter name with long strings of text. You will receive errors if the resulting document is longer than permitted by the `Question` parameter of `CreateHIT`. 
+ The HITLayout is used to create an HTMLQuestion document. HITLayoutParameter values with reserved characters or invalid HTML markup may result in an invalid HTMLQuestion document. For more information, see [HTMLQuestion](ApiReference_HTMLQuestionArticle.md).

# HTMLQuestion
<a name="ApiReference_HTMLQuestionArticle"></a>

**Topics**
+ [

## Description
](#ApiReference_HTMLQuestionArticle-description)
+ [

## The HTMLQuestion Data Structure
](#ApiReference_HTMLQuestionArticle-the-HTMLQuestion-data-structure)
+ [

## Example
](#ApiReference_HTMLQuestionArticle-example)
+ [

## Using Crowd HTML Elements
](#ApiReference_HTMLQuestionArticle-crowd)
+ [

## Preview Mode
](#ApiReference_HTMLQuestionArticle-the-external-form-preview-mode)
+ [

## The Form Action
](#ApiReference_HTMLQuestionArticle-the-external-form-the-form-action)
+ [

## The Answer Data
](#ApiReference_HTMLQuestionArticle-the-answer-data)
+ [

## Guidelines For Using HTML Questions
](#ApiReference_HTMLQuestionArticle-guidelines-for-using-external-questions)

## Description
<a name="ApiReference_HTMLQuestionArticle-description"></a>

 The `HTMLQuestion` data structure defines one or more questions for a HIT using HTML. The `HTMLQuestion` data structure is similar to both the `QuestionForm` and `ExternalQuestion` data structures.

The `QuestionForm` data structure defines, using a special XML language, how Amazon Mechanical Turk displays HIT questions and collects the answers. The `ExternalQuestion` data structure defines, using HTML, questions you host on your own "external" website. If you want to define your questions using HTML forms without having to host a website, you can use the `HTMLQuestion` data structure. 

A `HTMLQuestion` HIT is like a cross between a `QuestionForm` HIT and an `ExternalQuestion` HIT, for instance:
+ Like a `QuestionForm` HIT, you do not need to run a website or run any other infrastructure to have your HIT display on Mechanical Turk. You define your question when you call CreateHIT and then collect worker answers later, after they have been submitted. 
+  Like an `ExternalQuestion` HIT, you can define your HIT in HTML. Your HTML code must contain a form for the Worker to fill out and submit, which is displayed in a frame in the Worker's web browser. The Worker submits results using your form, and your form submits the results back to Amazon Mechanical Turk. Worker answers are processed by Mechanical Turk in the same way as `ExternalQuestion` HITs. If you choose, you can collect or process the results before submitting to Mechanical Turk. 

The worker interaction and presentation options available for `HTMLQuestion` are similar to `ExternalQuestion`. HTMLQuestions differ from ExternalQuestions primarily in how they are created.

As with the other question data structures, an `HTMLQuestion` is a string value that consists of XML data. This data must conform to the `HTMLQuestion` schema. See [Data Structure Schema Locations](ApiReference_SchemaLocationArticle.md) for the location of this schema. For more information about using XML data as a parameter or return value, see [Using XML Parameter Values](ApiReference_XMLParameterValuesArticle.md). 

**Note**  
You can only use an `HTMLQuestion` as the question of a HIT. You cannot use an `HTMLQuestion` with a Qualification test. 

The `HTMLQuestion` data structure is used as a parameter value for the following operation: 
+  `CreateHIT` 

The `HTMLQuestion` data structure is a value in a [HIT](ApiReference_HITDataStructureArticle.md) data structure.

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

## The HTMLQuestion Data Structure
<a name="ApiReference_HTMLQuestionArticle-the-HTMLQuestion-data-structure"></a>

 The `HTMLQuestion` data structure has a root element of `HTMLQuestion`. 

 The `HTMLQuestion` element contains the following elements: 


| Name | Description | Required | 
| --- | --- | --- | 
|   `HTMLContent`   |  The HTML code of your web form, to be displayed in a frame in the Worker's web browser. The HTML must validate against the HTML5 specification. HTML5 is backwards-compatible with a variety of recent HTML document specifications. For more information, see [http://www.w3.org/TR/html5-diff/](http://www.w3.org/TR/html5-diff/). For help in ensuring that your HTML validates, see [http://validator.w3.org](http://validator.w3.org). Type: String Default: None Amazon Mechanical Turk appends the following parameters to this URL: `assignmentId`, `hitId`, `turkSubmitTo`, and `workerId`. For more information about these appended parameters, see the sections following this table.  |  Yes  | 
|   `FrameHeight`   |  The height of the frame, in pixels. If you set the value to 0, your HIT will automatically resize to fit within the Worker's browser window. Type: Integer Default: None  |  Yes  | 

## Example
<a name="ApiReference_HTMLQuestionArticle-example"></a>

The following is an example of a complete `HTMLQuestion` data structure. Remember that to pass this structure in as the value of a parameter to an operation, XML characters must be escaped as character entities. For more information, see [Using XML Parameter Values](ApiReference_XMLParameterValuesArticle.md).

```
<HTMLQuestion xmlns="[the HTMLQuestion schema URL]">
  <HTMLContent><![CDATA[
<!DOCTYPE html>
<html>
 <head>
  <meta http-equiv='Content-Type' content='text/html; charset=UTF-8'/>
  <script type='text/javascript' src='https://s3.amazonaws.com/mturk-public/externalHIT_v1.js'></script>
 </head>
 <body>
  <form name='mturk_form' method='post' id='mturk_form' action='https://www.mturk.com/mturk/externalSubmit'>
  <input type='hidden' value='' name='assignmentId' id='assignmentId'/>
  <h1>What's up?</h1>
  <p><textarea name='comment' cols='80' rows='3'></textarea></p>
  <p><input type='submit' id='submitButton' value='Submit' /></p></form>
  <script language='Javascript'>turkSetAssignmentID();</script>
 </body>
</html>
]]>
  </HTMLContent>
  <FrameHeight>0</FrameHeight>
</HTMLQuestion>
```

## Using Crowd HTML Elements
<a name="ApiReference_HTMLQuestionArticle-crowd"></a>

The HTML Question supports [Crowd HTML Elements](ApiReference_HTMLCustomElementsArticle.md). Based on HTML web components, they encapsulate HTML, CSS, and JavaScript functionality behind a single HTML element. For example, the `<crowd-form>` element sets up your form for you, setting the correct submission endpoint and inserting a submit button at the end. Other elements provide question widgets or design elements you can customize to create more tailored HIT structures.

Try this sample sentiment analysis form.

**Example**  

```
<HTMLQuestion xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2011-11-11/HTMLQuestion.xsd">
  <HTMLContent><![CDATA[
    <!DOCTYPE html>
      <body>
        <script src="https://assets.crowd.aws/crowd-html-elements.js"></script>
        <crowd-form>
          <crowd-classifier
            name="sentiment"
            categories="['Positive', 'Negative', 'Neutral', 'N/A']"
            header="What sentiment does this text convey?"
          >
            <classification-target>
            Everything is wonderful.
            </classification-target>
            
            <full-instructions header="Sentiment Analysis Instructions">
            <p><strong>Positive</strong> 
              sentiment include: joy, excitement, delight</p>
            <p><strong>Negative</strong> sentiment include: 
              anger, sarcasm, anxiety</p>
            <p><strong>Neutral</strong>: neither positive or 
              negative, such as stating a fact</p>
            <p><strong>N/A</strong>: when the text cannot be 
              understood</p>
            <p>When the sentiment is mixed, such as both joy and sadness,
              use your judgment to choose the stronger emotion.</p>
            </full-instructions>
         
            <short-instructions>
             Choose the primary sentiment that is expressed by the text. 
            </short-instructions>
          </crowd-classifier>
        </crowd-form>
      </body>
    </html>
  ]]></HTMLContent>
  <FrameHeight>0</FrameHeight>
</HTMLQuestion>
```

Between the `<classification-target>` opening and closing tags, you can put any HTML that could be rendered and classified. For example you could use an audio clip or a video clip.

For more details, read the [Crowd HTML Elements](ApiReference_HTMLCustomElementsArticle.md) article or view the [Element Reference](https://docs.aws.amazon.com/sagemaker/latest/dg/sms-ui-template-reference.html) to see the different elements that are available.

## Preview Mode
<a name="ApiReference_HTMLQuestionArticle-the-external-form-preview-mode"></a>

The question defined by `HTMLQuestion` displays when a Worker previews the HIT on the Amazon Mechanical Turk website, before the Worker clicks the **Accept HIT** button. When the HIT is being previewed, the URL has a special value for the `assignmentId`: `ASSIGNMENT_ID_NOT_AVAILABLE`. This is the same mechanism used for `ExternalQuestion` HITs. 

When a Worker previews a HIT, your HTML should show the Worker everything they will need to do to complete the HIT, so they can decide whether or not to accept it. The easiest way to do this is to simply display the form as it would appear when the HIT is accepted. However, you may want to take precautions to prevent a Worker from accidentally filling out or submitting your form prior to accepting the HIT. 

You can use JavaScript to check the `assignmentId` parameter, and change the display of the form if the HIT is being previewed (`assignmentId=ASSIGNMENT_ID_NOT_AVAILABLE`). 

## The Form Action
<a name="ApiReference_HTMLQuestionArticle-the-external-form-the-form-action"></a>

For information about form actions for `HTMLQuestion`, see " The Form Action" in [ExternalQuestion](ApiReference_ExternalQuestionArticle.md). 

## The Answer Data
<a name="ApiReference_HTMLQuestionArticle-the-answer-data"></a>

For information about answer data for `HTMLQuestion`, see " The Answer Data" in [ExternalQuestion](ApiReference_ExternalQuestionArticle.md). 

## Guidelines For Using HTML Questions
<a name="ApiReference_HTMLQuestionArticle-guidelines-for-using-external-questions"></a>

**Tip**  
Your HTML code can do many things inside the browser frame, but eventually it must cause the Worker's browser to load the "externalSubmit" URL in the frame with the results in POST data. The easiest way to do this is with an HTML form whose fields contain the HIT results, with a submit button that the Worker clicks. If a `HTMLQuestion` HIT prevents the Worker from submitting results back to Amazon Mechanical Turk using the "externalSubmit" mechanism, the Worker may not be able to claim rewards or continue doing work without restarting their session. Amazon Mechanical Turk reserves the right to remove any `HTMLQuestion` HITs that are not functioning properly.



**Note**  
Your HIT will be rendered inside an IFRAME that has certain limitations. The IFRAME operates in HTML5 “sandbox” mode that has extra restrictions on the content that can appear in the frame. This limits your ability to execute certain code and to use technologies such as Adobe Flash. To ensure your HITs work as expected, we recommend you test them first in the [Requester Sandbox](https://requester.mturk.com/developer/sandbox). 

**Tip**  
All `HTMLQuestion` HITs are served from the same domain, regardless of requester. Bear this in mind if you choose to set cookies from JavaScript in your HTML.

# ExternalQuestion
<a name="ApiReference_ExternalQuestionArticle"></a>

**Topics**
+ [

## Description
](#ApiReference_ExternalQuestionArticle-description)
+ [

## The ExternalQuestion Data Structure
](#ApiReference_ExternalQuestionArticle-the-externalquestion-data-structure)
+ [

## Example
](#ApiReference_ExternalQuestionArticle-example)
+ [

## The External Form
](#ApiReference_ExternalQuestionArticle-the-external-form)
+ [

## Using Crowd HTML Elements
](#ApiReference_ExternalQuestionArticle-crowd)
+ [

## The Answer Data
](#ApiReference_ExternalQuestionArticle-the-answer-data)
+ [

## Guidelines For Using External Questions
](#ApiReference_ExternalQuestionArticle-guidelines-for-using-external-questions)

## Description
<a name="ApiReference_ExternalQuestionArticle-description"></a>

Instead of providing a [QuestionForm data structure](ApiReference_QuestionFormDataStructureArticle.md) that tells Amazon Mechanical Turk how to display your questions and collect answers, you can host the questions on your own website using an "external" question. 

A HIT with an external question displays a web page from your website in a frame in the Worker's web browser. Your web page displays a form for the Worker to fill out and submit. The Worker submits results using your form, and your form submits the results back to Amazon Mechanical Turk. Using your website to display the form gives your website control over how the question appears and how answers are collected. 

To use an external question with a HIT, you provide an `ExternalQuestion` data structure as the value of the `Question` parameter when calling the `CreateHIT` operation. As with the `QuestionForm` data structure, an `ExternalQuestion` is a string value that consists of XML data. This data must conform to the `ExternalQuestion` schema. See [Data Structure Schema Locations](ApiReference_SchemaLocationArticle.md) for the location of this schema. For more information about using XML data as a parameter or return value, see [Using XML Parameter Values](ApiReference_XMLParameterValuesArticle.md). 

**Note**  
 You can only use an external question as the question of a HIT. You cannot use an external question with a Qualification test. 

## The ExternalQuestion Data Structure
<a name="ApiReference_ExternalQuestionArticle-the-externalquestion-data-structure"></a>

 The `ExternalQuestion` data structure has a root element of **ExternalQuestion**. 

 The **ExternalQuestion** element contains the following elements: 


| Name | Description | Required | 
| --- | --- | --- | 
|   `ExternalURL`   |  The URL of your web form, to be displayed in a frame in the Worker's web browser. This URL must use the HTTPS protocol. Type: URL Default: None Amazon Mechanical Turk appends the following parameters to this URL: `assignmentId`, `hitId`, `turkSubmitTo`, and `workerId`. For more information about these appended parameters, see the sections following this table.   |  Yes  | 
|   `FrameHeight`   |  The height of the frame, in pixels. If you set the value to 0, your HIT will automatically resize to fit within the Worker's browser window. Type: Integer Default: None  |  Yes  | 

## Example
<a name="ApiReference_ExternalQuestionArticle-example"></a>

The following is an example of a complete `ExternalQuestion` data structure. Remember that to pass this structure in as the value of a parameter to an operation, XML characters must be escaped as character entities. For more information about escaping XML characters, see [Using XML Parameter Values](ApiReference_XMLParameterValuesArticle.md). See [Data Structure Schema Locations](ApiReference_SchemaLocationArticle.md) for the location of this schema.

```
<?xml version="1.0" encoding="UTF-8"?>
<ExternalQuestion xmlns="[the ExternalQuestion schema URL]">
  <ExternalURL>https://tictactoe.amazon.com/gamesurvey.cgi?gameid=01523</ExternalURL>
  <FrameHeight>0</FrameHeight>
</ExternalQuestion>
```

## The External Form
<a name="ApiReference_ExternalQuestionArticle-the-external-form"></a>

When a Worker attempts to complete a HIT with an external question, the external website is loaded into a frame in the middle of the screen. The web page at that URL should display a form for the Worker to fill out, and all the information the Worker will need to complete the HIT. 

### The Frame's URL and Parameters
<a name="ApiReference_ExternalQuestionArticle-the-external-form-the-frames-url-and-parameters"></a>

The URL used for the frame is the `ExternalURL` of the question with the following parameters appended: `assignmentId`, `hitId`, `turkSubmitTo`, and `workerId`. These parameters are appended CGI-style: The full URL has a question mark (`?`) before the first parameter, and an ampersand (`&`) between each parameter, with each parameter consisting of a name, an equal sign (`=`), and a value. Other parameters already present in this style in `ExternalURL` are preserved, so the final URL will only have one question mark, and all parameters will be separated by ampersands (`&`). 

**Note**  
 The URL you use for the `ExternalURL` must use the HTTPS protocol.

For example, consider an `ExternalURL` of: 

```
https://tictactoe.amazon.com/gamesurvey.cgi?gameid=01523
```

 With this `ExternalURL`, the full URL used for the page in the frame could be as follows: 

```
https://tictactoe.amazon.com/gamesurvey.cgi?gameid=01523
&assignmentId=123RVWYBAZW00EXAMPLE456RVWYBAZW00EXAMPLE
&hitId=123RVWYBAZW00EXAMPLE
&turkSubmitTo=https://www.mturk.com/
&workerId=AZ3456EXAMPLE
```

### Preview Mode
<a name="ApiReference_ExternalQuestionArticle-the-external-form-preview-mode"></a>

 Your external question will be displayed when a Worker previews the HIT on the Amazon Mechanical Turk website, before the Worker has clicked the "Accept HIT" button. When the HIT is being previewed, the URL will have a special value for the `assignmentId`: `ASSIGNMENT_ID_NOT_AVAILABLE`. 

When a Worker previews a HIT, your web page should show her everything she will need to do to complete the HIT, so she can decide whether or not to accept it. The easiest way to do this is to simply display the form as it would appear when the HIT is accepted. However, you may want to take precautions to prevent a Worker from accidentally filling out or submitting your form prior to accepting the HIT. 

 You can use JavaScript or server-side logic to check the `assignmentId` parameter, and change the display of the form if the HIT is being previewed (`assignmentId=ASSIGNMENT_ID_NOT_AVAILABLE`). 

 If a Worker submits your form before accepting the HIT, and your form attempts to post the data back to Amazon Mechanical Turk, Amazon Mechanical Turk will display an error message to the Worker, and the results will not be accepted. 

### The Form Action
<a name="ApiReference_ExternalQuestionArticle-the-external-form-the-form-action"></a>

The form on the external website must post the result data back to Amazon Mechanical Turk using the following URL:

```
https://www.mturk.com/mturk/externalSubmit
```

 Or, if you are using the Amazon Mechanical Turk sandbox, you should post the result data back to Mechanical Turk using the following sandbox URL:

```
https://workersandbox.mturk.com/mturk/externalSubmit
```

 The form must include the `assignmentId` field that was appended to the URL used to access your form. It should be submitted along with the other form fields submitted by your form, with a name of `assignmentId` and the same value as was passed to the form. Be sure to spell the field name as it appears here, with the same letters uppercase and lowercase. 

**Note**  
The field names `assignmentId`, `hitId`, `turkSubmitTo`, and `workerId` are reserved for special purposes. Your form only needs to submit the `assignmentId` field. Any data submitted with a field name of "`hitId`" will be ignored, and will not appear in the results data for the HIT. 

The form must submit data to that URL using the "POST" method. The data the form submits should be name-value pairs in the CGI-style: 
+ Each field appears as the name, an equal sign, and the value. For example: `favoriteColor=blue` 
+ Data that appears in the posted URL is preceded by a question mark (`?`), and is delimited by ampersands (`&`). For example: 

  ```
  https://www.mturk.com/mturk/externalSubmit?favoriteColor=blue&favoriteNumber=7&...
  ```
+ Data that appears in the HTTP message body (using the "POST" method) has one data pair per line. For example: 

  ```
  favoriteColor=blue
  favoriteNumber=7
  ...
  ```

 The easiest way to post the data in the CGI-style is to use an HTML form on the web page, with the `externalSubmit` URL as the "action," and "POST" as the "method." 

## Using Crowd HTML Elements
<a name="ApiReference_ExternalQuestionArticle-crowd"></a>

The External Question supports [Crowd HTML Elements](ApiReference_HTMLCustomElementsArticle.md). Based on HTML web components, they encapsulate HTML, CSS, and JavaScript functionality behind a single HTML element. For example, the `<crowd-form>` element sets up your form for you, setting the correct submission endpoint and inserting a submit button at the end. Other elements provide question widgets or design elements you can customize to create more tailored HIT structures.

### Requirements
<a name="ApiReference_ExternalQuestionArticle-crowd-requirements"></a>

There are three requirements for using Crowd HTML elements:
+ You must place the elements between the `<crowd-form>` opening and closing elements. As noted above, these also invisibly set up a `<form>` element and place a "submit" button at the bottom.

  
+ Place the Crowd HTML Elements loader script before the opening `<crowd-form>` element.

  
+ Store the HTML file in an S3 bucket, make the file publicly accessible, and reference it in the `<ExternalURL>` element of your XML .

  

Try this sample sentiment analysis form.

**Example**  

```
<!DOCTYPE html>
<html>
  <body>
	<script src="https://assets.crowd.aws/crowd-html-elements.js"></script>
	<crowd-form>
	  <crowd-classifier
	    name="sentiment"
	    categories="['Positive', 'Negative', 'Neutral', 'N/A']"
	    header="What sentiment does this text convey?"
	  >
	    <classification-target>
	    Everything is wonderful.
	    </classification-target>
	    
	    <full-instructions header="Sentiment Analysis Instructions">
	    <p><strong>Positive</strong> 
	      sentiment include: joy, excitement, delight</p>
	    <p><strong>Negative</strong> sentiment include: 
	      anger, sarcasm, anxiety</p>
	    <p><strong>Neutral</strong>: neither positive or 
	      negative, such as stating a fact</p>
	    <p><strong>N/A</strong>: when the text cannot be 
	      understood</p>
	    <p>When the sentiment is mixed, such as both joy and sadness,
	      use your judgment to choose the stronger emotion.</p>
	    </full-instructions>
	 
	    <short-instructions>
	     Choose the primary sentiment that is expressed by the text. 
	    </short-instructions>
	  </crowd-classifier>
	</crowd-form>
  </body>
</html>
```

Between the `<classification-target>` opening and closing tags, you can put any HTML that could be rendered and classified. For example you could use an audio clip or a video clip.

For more details, read the [Crowd HTML Elements](ApiReference_HTMLCustomElementsArticle.md) article or view the [Element Reference](https://docs.aws.amazon.com/sagemaker/latest/dg/sms-ui-template-reference.html) to see the different elements that are available.

## The Answer Data
<a name="ApiReference_ExternalQuestionArticle-the-answer-data"></a>

When the Worker submits your form, the form sends the field data to Amazon Mechanical Turk using the `externalSubmit` URL, and Amazon Mechanical Turk records the field data as the results of the Assignment. 

When you retrieve the results using `ListAssignmentsForHIT`, the field data submitted by your form will appear in the `Answer` of the [Assignment](ApiReference_AssignmentDataStructureArticle.md) as if each field were a free-text answer. The `QuestionIdentifier` element of the answer will be the name of the field, and the `FreeText` element will contain the value. 

See the [QuestionFormAnswers data format](ApiReference_QuestionFormAnswersDataStructureArticle.md) for more information about the format of answer data. 

## Guidelines For Using External Questions
<a name="ApiReference_ExternalQuestionArticle-guidelines-for-using-external-questions"></a>

External questions give your application a great deal of power over how Workers submit results for your HITs. To ensure you get good results for your HITs, you should make sure your web server and web pages can provide your Workers with a quality experience. 

Because external questions depend on your web server for rendering the question form, both while Workers are previewing HITs and while Workers are completing HITs, your server will need to be engineered for high availability. The Amazon Mechanical Turk website gets heavy traffic, so your web server will need to be able to respond quickly and correctly when receiving many requests in a short period of time. 

**Tip**  
 [Amazon S3](http://aws.amazon.com/s3) offers high availability of data, accessible via public HTTPS URLs. You can host your external questions as web pages in Amazon S3, and not have to run your own server. When you use an S3-hosted layout, you need to add a `ContentType` header and set the ACL to public read, as shown in the following Python SDK [PutObject](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.put_object) call:  

```
s3_client.put_object(
   ACL='public-read',
   Body=HTML layout,
   Bucket=S3 bucket name,
   Key=Object name,
   ContentType="text/html"
)
```

 Your website can do many things inside the frame, but eventually it must cause the Worker's browser to load the "externalSubmit" URL in the frame with the results in POST data. The easiest way to do this is with an HTML form whose fields contain the HIT results, with a submit button that the Worker will click. If an external HIT prevents the Worker from submitting results back to Amazon Mechanical Turk using the "externalSubmit" mechanism, the Worker may not be able to claim rewards or continue doing work without restarting their session. Amazon Mechanical Turk reserves the right to remove any external HITs that are not functioning properly. 

**Note**  
 Your HIT will be rendered inside an IFRAME that has certain limitations. The IFRAME operates in HTML5 "sandbox" mode that has extra restrictions on the content that can appear in the frame. This limits your ability to execute certain code and to use technologies such as Adobe Flash. To ensure your HITs work as expected, we recommend you test them first in the [Requester Sandbox](https://requester.mturk.com/developer/sandbox). 

Finally, please remember that external questions must meet the Amazon Mechanical Turk Participation Agreement, and Amazon Mechanical Turk's standards for appropriate content. Specifically, the Participation Agreement expressly prohibits the use of Amazon Mechanical Turk for advertising or solicitation. If your website typically displays advertising to visitors, please make sure those advertisements do not appear in your external questions. Amazon Mechanical Turk reserves the right to remove HITs with inappropriate content. 

# QuestionForm
<a name="ApiReference_QuestionFormDataStructureArticle"></a>

**Topics**
+ [

## Description
](#ApiReference_QuestionFormDataStructureArticle-description)
+ [

## QuestionForm Structure
](#ApiReference_QuestionFormDataStructureArticle-questionform-structure)
+ [

## Content Structure
](#ApiReference_QuestionFormDataStructureArticle-content-structure)
+ [

## Answer Specification
](#ApiReference_QuestionFormDataStructureArticle-answer-specification)
+ [

## Example
](#ApiReference_QuestionFormDataStructureArticle-example)

## Description
<a name="ApiReference_QuestionFormDataStructureArticle-description"></a>

 The `QuestionForm` data format describes one or more *questions* for a HIT, or for a Qualification test. It contains instructions and data Workers use to answer 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. 

 A `QuestionForm` is a string value that consists of XML data. This XML data must conform to the `QuestionForm` schema. All elements in a `QuestionForm` belong to a namespace whose name is identical to the URL of the `QuestionForm` schema document. See [Schema Locations](ApiReference_SchemaLocationArticle.md) for the location of this schema. 

**Tip**  
 For information about creating HITs that use your own web site in a frame instead of questions, see [the ExternalQuestion data structure](ApiReference_ExternalQuestionArticle.md). 

 The `QuestionForm` data structure is used as a parameter value for the following operations: 
+  `CreateHIT and CreateHITWithHITType` 
+  `CreateQualificationType` 
+  `UpdateQualificationType` 

 For more information about using XML data as a parameter or return value, see [Using XML Parameter Values](ApiReference_XMLParameterValuesArticle.md). 

## QuestionForm Structure
<a name="ApiReference_QuestionFormDataStructureArticle-questionform-structure"></a>

 The top-most element of the `QuestionForm` data structure is a `QuestionForm` element. This element contains optional `Overview` elements and one or more `Question` elements. There can be any number of these two element types listed in any order. The following example structure has an `Overview` element and a `Question` element followed by a second `Overview` element and `Question` element—all within the same `QuestionForm`. 

```
<QuestionForm xmlns="[the QuestionForm schema URL]">
  <Overview>
    [...]
  </Overview>
  <Question>
    [...]
  </Question>
  <Overview>
    [...]
  </Overview>
  <Question>
    [...]
  </Question>
  [...]
</QuestionForm>
```

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

 Each `Question` element can contain the elements described in the following table. See also the example below the table. 


| Name | Description | Required | 
| --- | --- | --- | 
|   `QuestionIdentifier`   |   An identifier for the question. This identifier is used to associate the Worker's answers with the question in the answer data.  Type: String  Default: None  |  Yes  | 
|   `DisplayName`   |   A name for the question, displayed as a prominent heading.  Type: String Default: None  |  No  | 
|   `IsRequired`   |   Specifies whether the Worker must provide an answer for this question to successfully submit the form.  Type: Boolean Default: false Valid Values: true \$1 false  |  No  | 
|   `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 in the *Content Structure* section below.  Type: Content structure Default: None  |  Yes  | 
|   `AnswerSpecification`   |   A structure that describes the field type and possible values for the answer to this question, as described in the *Answer Specification* section below. This element controls how the form field is rendered and specifies which values are valid answers for this question.  Type: An answer specification structure Default: None  Valid Values: `FreeTextAnswer` \$1 `SelectionAnswer` \$1 `FileUploadAnswer`   |  Yes  | 

 For example: 

```
  <Question>
    <QuestionIdentifier>my_question_id</QuestionIdentifier>
    <DisplayName>My Question</DisplayName>
    <IsRequired>true</IsRequired>
    <QuestionContent>
      [...]
    </QuestionContent>
    <AnswerSpecification>
      [...]
    </AnswerSpecification>
  </Question>
```

## Content Structure
<a name="ApiReference_QuestionFormDataStructureArticle-content-structure"></a>

 The `Overview` elements and the `QuestionContent` elements of a `QuestionForm` can contain different types of information. For example, you might include a paragraph of text and an image in your HIT's overview. 

 Each kind of information is defined by a corresponding element. These elements can appear in any number, in any order. The content elements are rendered in the order in which they occur in the containing element. 

 Following are the allowed information types: 
+ Title
+ Text
+ List
+ Binary
+ Application (Deprecated)
+ EmbeddedBinary
+ FormattedContent

 Each of these types are described in detail in the following subsections. A full example showing the use of the elements and information types is at the end of the section. 

### Title
<a name="ApiReference_QuestionFormDataStructureArticle-content-structure-title"></a>

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

```
<Title>The Next Move</Title>
```

### Text
<a name="ApiReference_QuestionFormDataStructureArticle-content-structure-text"></a>

 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 appear verbatim in the web output. 

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

### List
<a name="ApiReference_QuestionFormDataStructureArticle-content-structure-list"></a>

 A `List` element displays a bulleted list of items. Items are specified using one or more `ListItem` elements inside the `List`. The `ListItem` element is a string. 

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

### Binary
<a name="ApiReference_QuestionFormDataStructureArticle-content-structure-binary"></a>

 A `Binary` element specifies non-textual data of some kind, such as an image, audio, or video. The elements listed in the following table are required and must be entered in the order shown here. 


| Name | Description | Required | 
| --- | --- | --- | 
|   `MimeType`   |  Specifies the type of the data. Type: `MimeType` element Default: None Child Elements: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_QuestionFormDataStructureArticle.html)  |  Yes  | 
|   `DataURL`   |   The data itself specified with a `DataURL` element that contains a valid HTTP URL.  Type: `DataURL` element Default: None  |  Yes  | 
|   `AltText`   |   The text that should appear if the data cannot be rendered in the browser.  Type: String Default: None  |  Yes  | 

```
<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>
```

### Application (Deprecated)
<a name="ApiReference_QuestionFormDataStructureArticle-content-structure-application"></a>

**Important**  
Beginning Tuesday, December 12th 2017 the QuestionForm data structure will **no longer support the `Application` element.** Instead, we recommend using the [HTMLQuestion](ApiReference_HTMLQuestionArticle.md) or [ExternalQuestion](ApiReference_ExternalQuestionArticle.md) data structures for including interactive content for Workers.

 An `Application` element specifies an embedded application. 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, Amazon Mechanical Turk includes two parameters specific to the HIT: `hitId` and `assignmentId`. The `hitId` parameter is equal to the ID of the HIT. The `assignmentId` parameter is 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. 

 The `JavaApplet` element includes the elements described in the following table: 


| Name | Description | Required | 
| --- | --- | --- | 
|   `AppletPath`   |  The URL path to the directory that contains Java classes for the applet. Type: URL Default: None  |  Yes  | 
|   `AppletFilename`   |  The name of the class file that contains the applet code, which is located in the path specified by `AppletPath`. Type: String Default: None  |  Yes  | 
|   `Width`   |  The width of the bounding box for the applet. Type: String Default: None  |  Yes  | 
|   `Height`   |  The height of the bounding box for the applet. Type: String Default: None  |  Yes  | 
|   `ApplicationParameter`   |  The parameters for the applet. Type: `ApplicationParameter`  Default: None Child Elements: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_QuestionFormDataStructureArticle.html)  |  No  | 

 The `Flash` element includes the elements described in the following table: 


| Name | Description | Required | 
| --- | --- | --- | 
|   `FlashMovieURL`   |  The URL of the Flash movie file. Type: URL Default: None  |  Yes  | 
|   `Width`   |  The width of the bounding box for the Flash movie. Type: String Default: None  |  Yes  | 
|   `Height`   |  The height of the bounding box for the Flash movie. Type: String Default: None  |  Yes  | 
|   `ApplicationParameter`   |   The parameters for the Flash movie.  Type: `ApplicationParameter`  Default: None Child Elements: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_QuestionFormDataStructureArticle.html)  |  No  | 

```
<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>
```

### EmbeddedBinary
<a name="ApiReference_QuestionFormDataStructureArticle-content-structure-embeddedbinary"></a>

 An `EmbeddedBinary` element specifies an external object of non-textual data of some kind, such as an image, audio or video, that displays in your browser. The elements listed in the following table are required and must be entered in the order shown here. 


| Name | Description | Required | 
| --- | --- | --- | 
|   `EmbeddedMimeType`   |  Specifies the type of the data. Type: `EmbeddedMimeType` element Default: None Child Elements: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_QuestionFormDataStructureArticle.html)  |  Yes  | 
|   `DataURL`   |   The data itself specified by a `DataURL` element that contains a valid HTTP URL  Type: `DataURL` element Default: None  |  Yes  | 
|   `AltText`   |   The text that should appear if the data cannot be rendered in the browser.  Type: String Default: None  |  Yes  | 
|   `Width`   |   The width of the bounding box for the object.  Type: String Default: None  |  Yes  | 
|   `Height`   |   The height of the bounding box for the object.  Type: String Default: None  |  Yes  | 
|   `ApplicationParameter`   |  The parameters for the `EmbeddedBinary` object.  Type: `ApplicationParameter`  Default: None Child elements: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_QuestionFormDataStructureArticle.html)  |  No  | 

```
<EmbeddedBinary>
  <EmbeddedMimeType>
    <Type>image</Type>
    <SubType>gif</SubType>
  </EmbeddedMimeType>
  <DataURL>http://tictactoe.amazon.com/game/01523/board.gif</DataURL>
  <AltText>The game board, with "X" to move.</AltText>
  <Width>400</Width>
  <Height>300</Height>
  <ApplicationParameter>
    <Name>game_id<Name>
    <Value>01523</Value>
  </ApplicationParameter>
</EmbeddedBinary>
```

### FormattedContent
<a name="ApiReference_QuestionFormDataStructureArticle-content-structure-formattedcontent"></a>

 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](ApiReference_FormattedContentXHTMLArticle.md). 

 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>
```

## Answer Specification
<a name="ApiReference_QuestionFormDataStructureArticle-answer-specification"></a>

 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. 

### FreeTextAnswer
<a name="ApiReference_QuestionFormDataStructureArticle-answer-specification-freetextanswer"></a>

 A `FreeTextAnswer` element describes a text field and constraints on its possible values. It includes the elements described in the following table: 


| Name | Description | Required | 
| --- | --- | --- | 
|   `Constraints`   |   Describes the constraints on the allowed values for the text field. This element is described in the next table.  Type: `Constraints` element Default: None  |  No  | 
|   `DefaultText`   |   Specifies default text. This value appears in the form when it is rendered, and is accepted as the answer if the Worker does not change it.  Type: String Default: An empty value  |  No  | 
|   `NumberOfLinesSuggestion`   |   Specifies how tall the form field should be, if possible. The field might be rendered as a text box with this many lines, depending on the device the Worker is using to see the form.  Type: Integer Default: 1  |  No  | 

**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 allowed values for the text field. If no constraints are specified, any value is accepted for the field. 

 The `Constraints` element includes the elements described in the following table: 


| Name | Description | Required | 
| --- | --- | --- | 
|   `IsNumeric`   |  Specifies that the value entered must be numeric. Type: empty element Default: None Attributes: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_QuestionFormDataStructureArticle.html)  |  No  | 
|   `Length`   |  Specifies the length range of the answer. Type: empty element Default: None Attributes: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_QuestionFormDataStructureArticle.html)  |  No  | 
|   `AnswerFormatRegex`   |   Specifies that JavaScript validates the answer string against a given pattern.    A limitation of this approach is that Workers who have disabled JavaScript on their browsers cannot validate their answers. Although this is uncommon, you might want to caution your Workers.   Type: empty element Default: None Attributes: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_QuestionFormDataStructureArticle.html)  |  No  | 

 The `Constraints` element can contain multiple `AnswerFormatRegex` elements. All `AnswerFormatRegex` constraints must be satisfied before the Worker can submit the HIT.

 The following examples demonstrate how to use the `FreeTextAnswer` element. 

 If you want a 3-digit positive integer between 100 and 999, use the following: 

```
<FreeTextAnswer>
  <Constraints>
    <IsNumeric minValue="100" maxValue="999"/>
    <Length minLength="3" maxLength="3"/>
  </Constraints>
</FreeTextAnswer>
```

 If you want a 3-digit number that includes decimals, use the following: 

```
<FreeTextAnswer>
  <Constraints>
     <IsNumeric/>
     <Length minLength="3" maxLength="3"/>
  </Constraints>
</FreeTextAnswer>
```

 If you want to ensure that there is some text, use the following example. The **minLength** attribute includes whitespaces in the character count. 

```
<FreeTextAnswer>
  <Constraints>
    <Length minLength="2" />
    <AnswerFormatRegex regex="\S" errorText="The content cannot be blank."/>
  </Constraints>
</FreeTextAnswer>
```

 If you specify the **minLength** attribute, it is the same as if the ` IsRequired ` element is `true`. If you want to allow an *optional* string that must be at least two characters, use the following: 

```
<FreeTextAnswer>
  <Constraints>
    <AnswerFormatRegex regex="(^$|\S{2,})"
     errorText="You must enter at least two characters."/>
  </Constraints>
</FreeTextAnswer>
```

 To request a US phone number in the format 1-nnn-nnn-nnnn, where "1-" is optional, use the following: 

```
<FreeTextAnswer>
  <Constraints>
    <AnswerFormatRegex
     regex="^(1[- ]?)?(\([2-9]\d{2}\)\s*|[2-9]\d{2}-?)[2-9]\d{2}-?\d{4}$)"
     errorText="You must enter a US phone number in the format
     1-555-555-1234 or 555-555-1234."/>
  </Constraints>
</FreeTextAnswer>
```

 If you want an answer that contains a date formatted as yyyy-mm-dd, use the following: 

```
<FreeTextAnswer>
  <Constraints>
    <AnswerFormatRegex regex="^[12][0-9]{3}-[01]?\d-[0-3]?\d$"
     errorText="You must enter a date with the format yyyy-mm-dd."/>
  </Constraints>
</FreeTextAnswer>
```

 If you want an answer that contains "regex" and variations including RegEx, REGex, and RegExes, use the following: 

```
<FreeTextAnswer>
  <Constraints>
    <AnswerFormatRegex regex="regex" flags="i"
     errorText="You must enter 'regex'."/>
  </Constraints>
</FreeTextAnswer>
```

### SelectionAnswer
<a name="ApiReference_QuestionFormDataStructureArticle-answer-specification-selectionanswer"></a>

 A `SelectionAnswer` describes a multiple-choice question. Depending on the element defined, the Worker might be able to select zero, one, or multiple items from a set list as the answer to the question. 

 A `SelectionAnswer` element includes the elements described in the following table: 


| Name | Description | Required | 
| --- | --- | --- | 
|   `MinSelectionCount`   |   Specifies the minimum number of selections allowed for a valid answer. This value can range from 0 to the number of selections.  Type: non-negative Integer Default: 1  |  No  | 
|   `MaxSelectionCount`   |   Specifies the maximum number of selections allowed for a valid answer. This value can range from 1 to the number of selections.  Type: positive Integer Default: 1  |  No  | 
|   `StyleSuggestion`   |   Specifies what style of multiple-choice form field to use when displaying the question to the Worker. The field might not use the suggested style, depending on the device the Worker is using to see the form.  Type: String Default: None Valid Values: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_QuestionFormDataStructureArticle.html)  |  No  | 
|   `Selections`   |  Specifies the answer selections. Type: `Selections` structure Default: None Child elements: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_QuestionFormDataStructureArticle.html)  |  Yes  | 

 The `Selections` element lists the selection options available. It contains one or more `Selection` elements, one for each possible answer in the set. The `Selection` element includes the elements described in the following table: 


| Name | Description | Required | 
| --- | --- | --- | 
|   `SelectionIdentifier`   |   A unique alphanumeric string that is in the answer data if this selection is chosen.  Type: String Default: None  |  Yes  | 
|   One of the following elements:   |  |  Yes  | 
|   `Text`   |  Contains the content of the selected item. Type: String Default: None  | 
|   `FormattedContent`   |   A block of text formatted using XHTML tags that contains the content of the selected item. For more information about this format, see [Formatted Content: XHTML](ApiReference_FormattedContentXHTMLArticle.md).  Type: String Default: None  | 
|   `Binary`   |  Contains the content of the selected item. Type: `Binary` Default: None  | 

 The following example shows a `SelectionAnswer` element that specifies a question with four radiobuttons. 

```
<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>
```

### FileUploadAnswer (Deprecated)
<a name="ApiReference_QuestionFormDataStructureArticle-answer-specification-fileuploadanswer"></a>

**Important**  
Beginning Tuesday, December 12th 2017 the Answer Specification structure will **no longer support the `FileUploadAnswer` element** to be used for the QuestionForm data structure. Instead, we recommend that Requesters who want to create HITs asking Workers to upload files use [Amazon S3](http://aws.amazon.com/s3).

 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 required 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 is rejected, and the Worker must upload a different file to complete the HIT. You can specify a maximum size up to 2000000000 (2 billion) bytes. 

**Note**  
 A `FileUploadAnswer` element can only be used with HITs. It cannot be used with Qualification tests. 

 The following example demonstrates a `FileUploadAnswer` element that specifies a file with a minimum of 1000 bytes and a maximum of 3000000 bytes. 

```
<FileUploadAnswer>
  <MaxFileSizeInBytes>3000000</MaxFileSizeInBytes>
  <MinFileSizeInBytes>1000</MinFileSizeInBytes>
</FileUploadAnswer>
```

## Example
<a name="ApiReference_QuestionFormDataStructureArticle-example"></a>

 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](ApiReference_XMLParameterValuesArticle.md) 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>
```

# QuestionFormAnswers
<a name="ApiReference_QuestionFormAnswersDataStructureArticle"></a>

**Topics**
+ [

## Description
](#ApiReference_QuestionFormAnswersDataStructureArticle-description)
+ [

## The Structure of Answers
](#ApiReference_QuestionFormAnswersDataStructureArticle-the-structure-of-answers)
+ [

## Example
](#ApiReference_QuestionFormAnswersDataStructureArticle-example)

## Description
<a name="ApiReference_QuestionFormAnswersDataStructureArticle-description"></a>

 The `QuestionFormAnswers` data format describes answers submitted by a Worker for a HIT, or for a Qualification test. 

 A `QuestionFormAnswers` data structure is a string value that consists of XML data. The XML data must conform to the QuestionForm schema. See [Schema Locations](ApiReference_SchemaLocationArticle.md) for the location of this schema. For more information about using XML data as parameter or return value, see [Using XML Parameter Values](ApiReference_XMLParameterValuesArticle.md). 

**Note**  
 Answer data is *not* guaranteed by the Amazon Mechanical Turk Service to conform to the answer specifications described in a QuestionForm. MTS only guarantees that answer data returned by the service will conform to the `QuestionFormAnswers` schema. Your application should check that the answer data sufficiently answers the question. 

 The `QuestionFormAnswers` data structure is used as a response element for the following operations: 
+  `GetAssignmentsForHIT` 
+  `GetQualificationRequests` 

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

## The Structure of Answers
<a name="ApiReference_QuestionFormAnswersDataStructureArticle-the-structure-of-answers"></a>

 A `QuestionFormAnswers` element contains an `Answer` element for each question in the HIT or Qualification test for which the Worker provided an answer. Each `Answer` contains a `QuestionIdentifier` element whose value corresponds to the `QuestionIdentifier` of a `Question` in the QuestionForm. See [the QuestionForm data structure](ApiReference_QuestionFormDataStructureArticle.md) for more information about questions and answer specifications. 

 If the question expects a free-text answer, the `Answer` element contains a `FreeText` element. This element contains the Worker's answer. 

 If the question expects a multiple-choice answer, the `Answer` element contains a `SelectionIdentifier` element for each option the Worker selected. If the Worker did not make any selections, the `Answer` will contain zero `SelectionIdentifier` elements. The identifier corresponds to the `SelectionIdentifier` for the selection provided in the answer specification for the question. 

 If the multiple-choice question includes an `OtherSelection` field, and the Worker enters data into this field, that data appears in the `Answer` in an `OtherSelectionText` element. If the Worker both selects an option from the list and provides text in this field, both values will be present in the answer. 

 If the question expects an uploaded file as an answer, the `Answer` element contains an `UploadedFileSizeInBytes` element, and an `UploadedFileKey` element. `UploadedFileSizeInBytes` indicates the size of the file the Worker uploaded. `UploadedFileKey` is a unique identifier for the file, unique with respect to other files that Workers may have uploaded. To retrieve an uploaded file, your application calls the `GetFileUploadURL` operation, which returns a temporary URL your application can use to download the file. See the `GetFileUploadURL` operation for more information on retrieving uploaded files. 

 Answer data will always conform to the answer specification provided in the HIT question, or in the Qualification test question. 

## Example
<a name="ApiReference_QuestionFormAnswersDataStructureArticle-example"></a>

 The following is an example of a complete `QuestionFormAnswers` data structure. Remember that this value will be returned as a single return value, XML escaped in the response. 

```
<QuestionFormAnswers xmlns="[the QuestionFormAnswers schema URL]">
  <Answer>
    <QuestionIdentifier>nextmove</QuestionIdentifier>
    <FreeText>C3</FreeText>
  </Answer>
  <Answer>
    <QuestionIdentifier>likelytowin</QuestionIdentifier>
    <SelectionIdentifier>notlikely</SelectionIdentifier>
  </Answer>
</QuestionFormAnswers>
```

When using [Crowd HTML Elements](ApiReference_HTMLCustomElementsArticle.md) in your form, they will output JSON formatted data in the `<FreeText>` field. For example, the output for a [crowd-bounding-box](https://docs.aws.amazon.com/sagemaker/latest/dg/sms-ui-template-crowd-bounding-box.html) with three boxes on the image would contain a text string similar to the one below.

```
<FreeText>
  {
    'annotatedResult': 
    {
      'boundingBoxes': 
      [
        {
          'height': 902,
          'label': 'human',
          'left': 53,
          'top': 174,
          'width': 619
        },
        {
          'height': 936,
          'label': 'human',
          'left': 734,
          'top': 73,
          'width': 684
        },
        {
          'height': 686,
          'label': 'human',
          'left': 1174,
          'top': 121,
          'width': 556
        }
      ],
      'inputImageProperties': 
      {
        'height': 1080, 
        'width': 1920
      }
    }
  }
</FreeText>
```

# Formatted Content: XHTML
<a name="ApiReference_FormattedContentXHTMLArticle"></a>

**Topics**
+ [

## Using Formatted Content
](#ApiReference_FormattedContentXHTMLArticle-using-formatted-content)
+ [

## Supported XHTML Tags
](#ApiReference_FormattedContentXHTMLArticle-supported-xhtml-tags)
+ [

## How XHTML Formatted Content Is Validated
](#ApiReference_FormattedContentXHTMLArticle-how-xhtml-formatted-content-is-validated)

 When you create a HIT or a Qualification test, you can include various kinds of content to be displayed to the Worker on the Amazon Mechanical Turk web site, such as text (titles, paragraphs, lists), media (pictures, audio, video) and browser applets (Java or Flash). 

 You can also include blocks of formatted content. Formatted content lets you include XHTML tags directly in your instructions and your questions for detailed control over the appearance and layout of your data. 

 You include a block of formatted content by specifying a `FormattedContent` element in the appropriate place in your [QuestionForm data structure](ApiReference_QuestionFormDataStructureArticle.md). You can specify any number of `FormattedContent` elements in content, and you can mix them with other kinds of content. 

 The following example uses other content types (`Title`, `Text`) along with `FormattedContent` to include a table in a HIT: 

```
<Text>
  This HIT asks you some questions about a game of Tic-Tac-Toe
  currently in progress.  Your answers will help decide the next move.
</Text>
<Title>The Current Board</Title>
<Text>
  The following table shows the board as it currently stands.
</Text>
<FormattedContent><![CDATA[
<table border="1">
  <tr>
    <td></td>
    <td align="center">1</td>
    <td align="center">2</td>
    <td align="center">3</td>
  </tr>
  <tr>
    <td align="right">A</td>
    <td align="center"><b>X</b></td>
    <td align="center">&nbsp;</td>
    <td align="center"><b>O</b></td>
  </tr>
  <tr>
    <td align="right">B</td>
    <td align="center">&nbsp;</td>
    <td align="center"><b>O</b></td>
    <td align="center">&nbsp;</td>
  </tr>
  <tr>
    <td align="right">C</td>
    <td align="center">&nbsp;</td>
    <td align="center">&nbsp;</td>
    <td align="center"><b>X</b></td>
  </tr>
  <tr>
    <td align="center" colspan="4">It is <b>X</b>'s turn.</td>
  </tr>
</table>
]]></FormattedContent>
```

 For more information about describing the contents of a HIT or Qualification test, see [the QuestionForm data structure](ApiReference_QuestionFormDataStructureArticle.md). 

## Using Formatted Content
<a name="ApiReference_FormattedContentXHTMLArticle-using-formatted-content"></a>

 As you can see in the example above, formatted content is specified in an XML CDATA block, inside a `FormattedContent` element. The CDATA block contains the text and XHTML markup to display in the Worker's browser. 

 Only a subset of the XHTML standard is supported. For a complete list of supported XHTML elements and attributes, see the table below. In particular, JavaScript, element IDs, `class` and `style` attributes, and `<div>` and `<span>` elements are not allowed. 

 XML comments (`<!-- ... -->`) are not allowed in formatted content blocks. 

 Every XHTML tag in the CDATA block must be closed before the end of the block. For example, if you start an XHTML paragraph with a `<p>` tag, you must end it with a `</p>` tag within the same `FormattedContent` block. 

**Note**  
 The tag closure requirement means you cannot open an XHTML tag in one `FormattedContent` block and close it in another. There is no way to "wrap" other kinds of question form content in XHTML. `FormattedContent` blocks must be self-contained. 

 XHTML tags must be nested properly. When tags are used inside other tags, the inner-most tags must be closed before outer tags are closed. For example, to specify that some text should appear in bold italics, you would use the `<b>` and `<i>` tags as follows: 

```
<b><i>This text appears bold italic.</i></b>
```

 But the following would not be valid, because the closing `</b>` tag appears before the closing `</i>` tag: 

```
<b><i>These tags don't nest properly!</b></i>
```

 Finally, formatted content must meet other requirements to validate against the XHTML schema. For instance, tag names and attribute names must be all lowercase letters, and attribute values must be surrounded by quotes. 

 For details on how Amazon Mechanical Turk validates XHTML formatted content blocks, see "How XHTML Formatted Content Is Validated," below. 

## Supported XHTML Tags
<a name="ApiReference_FormattedContentXHTMLArticle-supported-xhtml-tags"></a>

 `FormattedContent` supports a limited subset of [the XHTML 1.0 ("transitional") standard](http://www.w3.org/TR/xhtml1/). The complete list of supported tags and attributes appears in the table below. Notable differences with the standard include: 
+  JavaScript is not allowed. The `<script>` tag is not supported, and anchors (`<a>`) and images (`<img>`) cannot use `javascript:` targets in URLs. 
+  CSS is not allowed. The `<style>` tag is not supported, and the `class` and `style` attributes are not supported. The `id` attribute is also not supported. 
+  XML comments (`<!-- ... -->`) are not supported. 
+  URL methods in anchor targets and image locations are limited to the following: `http:// https:// ftp:// news:// nntp:// mailto:// gopher:// telnet://` 

 Other things to note with regards to supported tags and attributes: 
+  In addition to the attributes listed, the `title` attribute is supported for all tags, and the `dir` and `lang` attributes are supported for all tags except `<br>`. 
+  The `alt` attribute is required for `<area>` and `<img>` tags. 
+  `<img>` tags also require a `src` attribute. 
+  `<map>` tags require a `name` attribute. 

 The following table lists the supported tags and attributes: 


| Tag | Attributes | 
| --- | --- | 
|  a  |  accesskey charset coords href hreflang name rel rev shape tabindex target type  | 
|  area  |  alt coords href nohref shape target  | 
|  b  |    | 
|  big  |    | 
|  blockquote  |  cite  | 
|  br  |    | 
|  center  |    | 
|  cite  |    | 
|  code  |    | 
|  col  |  align char charoff span valign width  | 
|  colgroup  |  align char charoff span valign width  | 
|  dd  |    | 
|  del  |  cite datetime  | 
|  dl  |    | 
|  em  |    | 
|  font  |  color face size  | 
|  h1  |  align  | 
|  h2  |  align  | 
|  h3  |  align  | 
|  h4  |  align  | 
|  h5  |  align  | 
|  h6  |  align  | 
|  hr  |  align noshade size width  | 
|  i  |  | 
|  img  |  align alt border height hspace ismap longdesc src usemap vspace width  | 
|  ins  |  cite datetime  | 
|  li  |  type value  | 
|  map  |  name  | 
|  ol  |  compact start type  | 
|  p  |  align  | 
|  pre  |  width  | 
|  q  |  cite  | 
|   `small`   |   ``   | 
|  strong  |     | 
|  sub  |     | 
|  sup  |     | 
|  table  |  align bgcolor border cellpadding cellspacing frame rules summary width  | 
|  tbody  |  align char charoff valign  | 
|  td  |  abbr align axis bgcolor char charoff colspan headers height nowrap rowspan scope valign width  | 
|  tfoot  |  align char charoff valign  | 
|  th  |  abbr align axis bgcolor char charoff colspan headers height nowrap rowspan scope valign width  | 
|  thead  |  align char charoff valign  | 
|  tr  |  align bgcolor char charoff valign  | 
|  u  |    | 
|  ul  |  compact type  | 

## How XHTML Formatted Content Is Validated
<a name="ApiReference_FormattedContentXHTMLArticle-how-xhtml-formatted-content-is-validated"></a>

 When you create a HIT or a Qualification test whose content uses `FormattedContent`, Amazon Mechanical Turk attempts to validate the formatted content blocks against a schema. If the formatted content does not validate against the schema, the operation call will fail and return an error. 

 To validate the formatted content, Amazon Mechanical Turk takes the contents of the `FormattedContent` element (the text and markup inside the CDATA), then constructs an XML document with an appropriate XML header, `<FormattedContent>` as the root element, and the text and markup as the element's contents (without the CDATA). This document is then validated against a schema. 

 For example, consider the following `FormattedContent` block: 

```
  ...
  <FormattedContent><![CDATA[
    I absolutely <i>love</i> chocolate ice cream!
  ]]></FormattedContent>
  ...
```

 To validate this block, Amazon Mechanical Turk produces the following XML document: 

```
<?xml version="1.0"?>
<FormattedContent xmlns="http://www.w3.org/1999/xhtml">
  I absolutely <i>love</i> chocolate ice cream!
</FormattedContent>
```

 The schema used for validation is called `FormattedContentXHTMLSubset.xsd`. For information on how to download this schema, see [Data Structure Schema Locations](ApiReference_SchemaLocationArticle.md). 

 You do not need to specify the namespace of the XHTML tags in your formatted content. This is assumed automatically during validation. 

# AnswerKey
<a name="ApiReference_AnswerKeyDataStructureArticle"></a>

**Topics**
+ [

## Description
](#ApiReference_AnswerKeyDataStructureArticle-description)
+ [

## The Structure of an Answer Key
](#ApiReference_AnswerKeyDataStructureArticle-the-structure-of-an-answer-key)
+ [

## Example
](#ApiReference_AnswerKeyDataStructureArticle-example)

## Description
<a name="ApiReference_AnswerKeyDataStructureArticle-description"></a>

 The AnswerKey data structure specifies answers for a Qualification test, and a mechanism to use to calculate a score from the key and a Worker's answers. 

 An AnswerKey data structure is a string value that consists of XML data. The XML data must conform to the AnswerKey schema. See [WSDL and Schema Locations](ApiReference_SchemaLocationArticle.md) for the location of this schema. For more information about using XML data as parameter or return value, see [Using XML Parameter Values](ApiReference_XMLParameterValuesArticle.md). 

 The AnswerKey data structure is used as a parameter for the following operations: 
+  `CreateQualificationType` 

 The AnswerKey data structure is used as a return value for the following operations: 
+  `GetQualificationType` 

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

## The Structure of an Answer Key
<a name="ApiReference_AnswerKeyDataStructureArticle-the-structure-of-an-answer-key"></a>

 An answer key is contained in a `AnswerKey` element. This element contains a `Question` element for each question in the Qualification test, and an optional `QualificationValueMapping` element that describes how to calculate the Qualification value from the answer key and the Worker's answers. 

### Question
<a name="ApiReference_AnswerKeyDataStructureArticle-the-structure-of-an-answer-key-question"></a>

 A `Question` element contains a `QuestionIdentifier` element, which identifies the question for this answer. This value corresponds to a `QuestionIdentifier` in the QuestionForm. 

 A `Question` element has one or more `AnswerOption` elements, one for each combination of selections in the multiple-choice question that affects the Worker's test score. 

 Each `AnswerOption` contains one or more `SelectionIdentifier` elements that correspond to identifiers for the selections in the QuestionForm. It also contains an `AnswerScore` element, a number that is added to the Worker's test score if the Worker's answer matches this option. The Worker must select all of the selections specified by the `SelectionIdentifier` elements, and no others, to earn the score. 

**Tip**  
 An `AnswerScore` for an `AnswerOption` may be negative. 

 The `Question` may have an optional `DefaultScore`, a number that is added to the Worker's test score if none of the answer options exactly match the Worker's answer for the question. `DefaultScore` is optional, and defaults to 0. 

```
<AnswerOption>
  <SelectionIdentifier>apples</SelectionIdentifier>
  <AnswerScore>10</AnswerScore>
</AnswerOption>
```

### QualificationValueMapping
<a name="ApiReference_AnswerKeyDataStructureArticle-the-structure-of-an-answer-key-qualificationvaluemapping"></a>

 The `Question` may have an optional `QualificationValueMapping` element that describes how to calculate the Worker's overall score from the scores of the Worker's answers. It contains either a `PercentageMapping` element, a `ScaleMapping` element, or a `RangeMapping` element. 

 If no `QualificationValueMapping` is specified, the sum of the scores of the answers is used as the Qualification value. 

```
<QualificationValueMapping>
  ...
</QualificationValueMapping>
```

 A `PercentageMapping` specifies a maximum score for the test, as a `MaximumSummedScore` element. The Qualification value is calculated as the sum of the scores of the selected answers, divided by the maximum, multiplied by 100 and rounded to the nearest integer to produce a percentage. 

```
  ...
  <PercentageMapping>
    <MaximumSummedScore>15</MaximumSummedScore>
  </PercentageMapping>
```

 A `ScaleMapping` specifies a multiplier, as a decimal value in a `SummedScoreMultiplier` element. The Qualification value is calculated as the sum of the scores of the selected answers, multiplied by the multiplier. 

```
  ...
  <ScaleMapping>
    <SummedScoreMultiplier>3</SummedScoreMultiplier>
  </ScaleMapping>
```

 A `RangeMapping` assigns specific Qualification values to ranges of total test scores. It contains one or more `SummedScoreRange` elements, each of which specify an `InclusiveLowerBound` element, an `InclusiveUpperBound` element, and a `QualificationValue` that becomes the Qualification value if the sum of the scores of the selected answers falls within the specified range. Finally, the `RangeMapping` includes a single `OutOfRangeQualificationValue`, which specifies the Qualification value if the sum of the scores of the selected answers do not fall within a specified range. 

**Note**  
 Ranges cannot overlap. If ranges overlap, the behavior is undefined. 

```
  ...
  <RangeMapping>
    <SummedScoreRange>
      <InclusiveLowerBound>5</InclusiveLowerBound>
      <InclusiveUpperBound>7</InclusiveUpperBound>
      <QualificationValue>5</QualificationValue>
    </SummedScoreRange>
    <SummedScoreRange>
      <InclusiveLowerBound>8</InclusiveLowerBound>
      <InclusiveUpperBound>10</InclusiveUpperBound>
      <QualificationValue>10</QualificationValue>
    </SummedScoreRange>
    <OutOfRangeQualificationValue>0</OutOfRangeQualificationValue>
  </RangeMapping>
```

## Example
<a name="ApiReference_AnswerKeyDataStructureArticle-example"></a>

The following is an example of a complete `AnswerKey` data structure. Remember that to pass this structure in as a parameter to an operation, XML characters must be escaped as character entities. For more information, see [Using XML Parameter Values](ApiReference_XMLParameterValuesArticle.md). 

```
<AnswerKey xmlns="[the AnswerKey schema URL]">
  <Question>
    <QuestionIdentifier>nextmove</QuestionIdentifier>
    <AnswerOption>
      <SelectionIdentifier>D</SelectionIdentifier>
      <AnswerScore>5</AnswerScore>
    </AnswerOption>
  </Question>
  <Question>
    <QuestionIdentifier>favoritefruit</QuestionIdentifier>
    <AnswerOption>
      <SelectionIdentifier>apples</SelectionIdentifier>
      <AnswerScore>10</AnswerScore>
    </AnswerOption>
  </Question>
  <QualificationValueMapping>
    <PercentageMapping>
      <MaximumSummedScore>15</MaximumSummedScore>
    </PercentageMapping>
  </QualificationValueMapping>
</AnswerKey>
```

# Data Structure Schema Locations
<a name="ApiReference_SchemaLocationArticle"></a>

**Topics**

 The Amazon Mechanical Turk uses several XML data structures to help you define your tasks flexibly. These data structures are specified using schemas that are versioned. This allows MTurk to add new versions of task types while preserving backwards compatibility.

 When constructing an XML object for any of these structures, you must declare a namespace that matches the target namespace for the schema for the structure. The namespace is defined using the URL to the schema definition. For example, here is how to declare your namespace when constructing an HTMLQuestion: 

```
<HTMLQuestion
xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2011-11-11/HTMLQuestion.xsd">
[...]
</HTMLQuestion>
```

 If the service returns an error message about data not validating against the schema, make sure your namespace declaration matches the target namespace specified in the schema. 

**Important**  
Beginning Tuesday, December 12th 2017 the [QuestionForm](ApiReference_QuestionFormDataStructureArticle.md) structure will **no longer support the `FileUploadAnswer` element and the `Application` element.** The **2017-11-06** version of the QuestionForm schema has been updated to reflect these changes. If you don't use the deprecated elements in your QuestionForm, the **2005-10-01** schema will continue to work. 

 You can find the schema namespace values for all of the question and answer data structures below: 


|  Type of Schema  |  Latest Version  |  Schema Namespace | 
| --- | --- | --- | 
|  The [HTMLQuestion](ApiReference_HTMLQuestionArticle.md) schema  |  2011-11-11  |  [Download HTMLQuestion.zip](samples/HTMLQuestion.zip)  | 
|  The [ExternalQuestion](ApiReference_ExternalQuestionArticle.md) schema  |  2006-07-14  |  [Download ExternalQuestion.zip](samples/ExternalQuestion.zip)  | 
|  The [Formatted Content: XHTML](ApiReference_FormattedContentXHTMLArticle.md) subset |  2006-07-14  |  [Download FormattedContentXHTMLSubset.zip](samples/FormattedContentXHTMLSubset.zip)  | 
| The [QuestionForm](ApiReference_QuestionFormDataStructureArticle.md) schemas  | 2017-11-06 |  [Download QuestionForm.zip](samples/QuestionForm.zip) | 
|  The [QuestionFormAnswers](ApiReference_QuestionFormAnswersDataStructureArticle.md) schemas  |  2005-10-01  |  [Download QuestionFormAnswers.zip](samples/QuestionFormAnswers.zip)  | 
|  The [AnswerKey](ApiReference_AnswerKeyDataStructureArticle.md) schemas schemas  |  2005-10-01  |  [Download AnswerKey.zip](samples/AnswerKey.zip)  |