WSDL and Schema Locations

Topics

The Amazon Mechanical Turk Service can be accessed using the SOAP web services messaging protocol, or using the REST method of HTTP requests with parameters. The SOAP interface is described by a Web Services Description Language (WSDL) document. REST requests return messages that conform to an XML Schema document.

To make it easy to upgrade your application when a new version of schemas are released, all schemas have a version number. The version number appears in the URL of a schema file, and in a schema's target namespace. The API schemas (the WSDL and request/response messages) and the data structure schemas (question and answer values) use separate version numbers. The latest versions are as follows:

Type of Schema	Latest Version
The API: WSDL and message schemas	`2008-08-02`
The QuestionForm, QuestionFormAnswers and AnswerKey schemas	`2005-10-01`
The ExternalQuestion schema	`2006-07-14`
The formatted content XHTML subset	`2006-07-14`
The notifications receptor API	`2006-05-05`

The WSDL and Message Schema Locations

The WSDL for a given version of the Amazon Mechanical Turk Service API can be found at a URL that corresponds to the API version. For example, the WSDL for the 2008-08-02 version of the API can be found here:

http://mechanicalturk.amazonaws.com/AWSMechanicalTurk/2008-08-02/AWSMechanicalTurkRequester.wsdl

The XML Schema for the messages of a given version of the Amazon Mechanical Turk Service API can be found at a URL that corresponds to the API version. For example, the XML Schema for the 2008-08-02 version of the API can be found here:

http://mechanicalturk.amazonaws.com/AWSMechanicalTurk/2008-08-02/AWSMechanicalTurkRequester.xsd

The Data Structure Schema Locations

The Amazon Mechanical Turk Service has several parameters and return values that contain XML data. The XML content must validate against the appropriate XML schema. For more information, see QuestionForm, QuestionFormAnswers, and AnswerKey.

Note

	Note
The API version number and the data structure version number are not related. The two sets of schemas may have new releases at different times, and may have different version numbers. For example, an application using the `2008-08-02` version of the API may create HITs using the `2005-10-01` version of the QuestionForm schema. (There may not be a "2008-08-02" version of the QuestionForm schema.) Your application may use any supported version of the data schemas with any supported version of the API. A data structure returned by the service will include a namespace that corresponds to the relevant schema.

The API version number and the data structure version number are not related. The two sets of schemas may have new releases at different times, and may have different version numbers. For example, an application using the 2008-08-02 version of the API may create HITs using the 2005-10-01 version of the QuestionForm schema. (There may not be a "2008-08-02" version of the QuestionForm schema.)

Your application may use any supported version of the data schemas with any supported version of the API. A data structure returned by the service will include a namespace that corresponds to the relevant schema.

The 2005-10-01 version of the QuestionForm schema can be found here:

http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/QuestionForm.xsd

The 2005-10-01 version of the QuestionFormAnswers schema can be found here:

http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/QuestionFormAnswers.xsd

The 2005-10-01 version of the AnswerKey schema can be found here:

http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/AnswerKey.xsd

The 2006-07-14 version of the ExternalQuestion schema can be found here:

http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2006-07-14/ExternalQuestion.xsd

Note

	Note
To conform to a schema, XML content must use namespace declarations that match the target namespace for the schema. The target namespace is declared at the top of the schema, as the "targetNamespace" attribute of the "xs:schema" element. The schemas for QuestionForm, QuestionFormAnswers, and AnswerKey use namespace URIs similar to the URL at which the schema file can be found, including the service version. For example: <QuestionForm xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/QuestionForm.xsd" > `[...]` </QuestionForm> 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.

To conform to a schema, XML content must use namespace declarations that match the target namespace for the schema. The target namespace is declared at the top of the schema, as the "targetNamespace" attribute of the "xs:schema" element.

The schemas for QuestionForm, QuestionFormAnswers, and AnswerKey use namespace URIs similar to the URL at which the schema file can be found, including the service version. For example:

<QuestionForm
  xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/QuestionForm.xsd"
  >
    [...]
</QuestionForm>

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.

The Formatted Content XHTML Subset

HITs and Qualification tests can include blocks of content formatted with XHTML tags in their instructions and question data. To include text and markup for formatted content in a web service request, you specify it as XML CDATA inside a FormattedContent element, part of the QuestionForm data structure.

Amazon Mechanical Turk validates formatted content by converting the text and markup in the CDATA block into an XML document, then validating it against a schema. For more information about how this XML document is produced, see Formatted Content: XHTML, "How XHTML Formatted Content Is Validated".

The 2006-07-14 version of the schema used to validate formatted content can be found here:

http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2006-07-14/FormattedContentXHTMLSubset.xsd

The Notifications Receptor WSDL Location

The WSDL for the notification receptor API is located here:

http://mechanicalturk.amazonaws.com/AWSMechanicalTurk/2006-05-05/AWSMechanicalTurkRequesterNotification.wsdl

For more information about building a notification receptor web service, see The Notification Receptor API.

Service API Versions

When a new version of the service API is released, previous versions are supported for a limited time to allow applications to continue to function until they are upgraded. The version of a service API is specified as a date, such as 2008-08-02.

The version of the API can be found in the URLs of the WSDL and schema files. It can also be found in the targetNamespace of the WSDL and schema files.

You can retrieve the WSDL or schema files for previous versions of the API by replacing the version date in the URL with the desired version. For example, to retrieve the WSDL for API version 2008-08-02:

http://mechanicalturk.amazonaws.com/AWSMechanicalTurk/2008-08-02/AWSMechanicalTurkRequester.wsdl

For information about which versions of the API are supported, visit the Amazon Web Services web site at http://aws.amazon.com/mturk.

Accessing a Specific Service Version

For your application to use a specific version of the service API, the service needs to be told which version is being used with each request.

For SOAP requests, the Amazon Mechanical Turk Service determines which API version you are using based on the namespace in your request message, which is determined by the WSDL you are using with your application. SOAP requests always include this information, and SOAP toolkits determine the namespace automatically from the WSDL.

For REST requests, you must explicitly request the version to use by including the Version parameter in your request. The Version parameter ensures that the service does not return response elements that your application is not designed to handle.

Here is an example REST request that includes the Version parameter:

http://mechanicalturk.amazonaws.com/?Service=AWSMechanicalTurkRequester
&AWSAccessKeyId=[the Requester's Access Key ID]
&Version=2008-08-02
&Operation=GetHIT
&HITId=123RVWYBAZW00EXAMPLE

The Default Version

Older AWS services supported requests that did not specify an API version. This behavior is still supported for legacy reasons, but its use is discouraged.

When the Amazon Mechanical Turk Service receives a REST request without a Version parameter, the service will use the latest version. If your application does not specify the Version in each request, when a new version of the API is released, your application will start using the new version automatically. Because new versions of the API may be incompatible with applications expecting to use an older version, specifying an explicit Version parameter with each request is strongly recommended.

A similar legacy feature exists for SOAP: A request for the WSDL or a schema file using a URL that does not include the version number will return the file for the latest version of the API. Using WSDL/schema URLs that include the API version number is strongly recommended.