Creating specifications

Project settings in Toloka must include specifications for the input and output data. If you use Template Builder in the Toloka interface, the specification is created automatically by default.


Specifications are currently created in test mode. After saving the project, check the input and output data specifications. If you have any problems, please contact support.

Specification setting modes

You can configure the specification automatically or manually. You can change the way the specification is configured using the Define data specification manually option. This option is disabled by default.

Option disabled
Option enabled

The specifications of input and output data are generated automatically depending on the task interface settings.

Filling in input data

If automatic generation of specifications is enabled, the input data fields are created from the configuration code. Provide a detailed example to get a ready-to-use specification. If you have optional fields, include them also.



In this example, the question field with the string type will be created in the specification.

"question": "Do you like dogs?"

By default, all the input data fields are marked as required in the specification. To make the field optional, specify the default property in the data.input configuration component.

Filling in output data

If automatic generation of specifications is enabled, the output data fields are created from the configuration code. It takes into account the components that use data.output as well as the values supported by it.



In this example, the specification will contain the verdict field with the boolean type.

"type": "",
"options": [
"label": "Yes",
"value": true
"label": "No",
"value": false
"data": {
"type": "data.output",
"path": "verdict"

If there are different types of values in the output, the JSON type will be included in the specification.

How to edit the specification


Specification editing is available only when the Define data specification manually option is enabled.

There are two ways to edit the specification in project settings: using either regular mode or JSON mode. JSON mode gives you more options — you can hide input data and use regular expressions to validate output data.

Regular mode
JSON mode

To add a field in the regular mode, click Add field.

To edit an existing field, hover over the field and click image.

Explanations for configuring fields


  • If you edit a required field, the changes apply only to new task pools. For example, if you need to fix an error in a project, clone the pool or create a new one. Existing task pools will continue using the previous version of the project.

  • In the output, use value validation and don't forget to mark the field as required if a Toloker has to fill it in.

  • Hidden fields are intended only for requesters and are not available in the task interface. The values of hidden fields can't be used either in the JS code or in the template constructor.

    Let's say you pass product data (like articles or batch numbers) that Tolokers don't need in order to complete the task. Or you are moderating comments and you need the authors' personal data in the results for further data processing, but Tolokers shouldn't have access to personal data.

    To create a hidden field, add it to the specification yourself and then add the "hidden": true parameter to this field in JSON mode. You should do this in Toloka when configuring your project. The hidden field remains when the specification is re-generated using the Template Builder.

What's next

Contact support

Last updated: August 2, 2023

Getting started
Important tips
Useful recommendations
Working with Toloka
Project analysis
Toloka settings
Task interface
Template Builder
HTML/CSS/JS editor
Help and support