Creating specifications

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

Attention. Creating a specification is in test mode, so double check the results. If you have any problems, please contact support.

Filling in input data

Input data fields are created from the code on the Example of input data tab. Provide a detailed example to get a ready-to-use specification. For example, if you have optional fields, include them also.

Examples:

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, in the data.input configuration component specify the default property.

Filling in output data

The output data fields depend on the components that use data.output and values supported by it.

Examples:

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

{
  "type": "field.radio-group",
  "options": [
    {
      "label": "Yes",
      "value": true
    },
    {
      "label": "No",
      "value": false
    }
  ],
  "data": {
    "type": "data.output",
    "path": "verdict"
  }
}
Note. If there are different types of values in the output, the JSON type will be included in the specification.

How to edit the specification

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

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

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

Explanations for configuring fields

Parameter

Parameter in JSON

Description

Name

id

Field ID. Only Latin letters, numbers, hyphens and underscores are allowed.

Type

type

Data type:

  • string

  • url

  • boolean

  • number

  • float

  • file
  • coordinates

  • json

For arrays, add the array_ prefix to the field type in JSON mode. For example: array_file.

Required

required

Whether the field must be filled when uploading the tasks for the input data.

Whether the performer's response is required in the output data.

By default, fields are optional — false.

Hidden

hidden

Allows you to hide data from the performer. If this is not done, performers can get the field value programmatically. You can configure this parameter in JSON mode.

For example, you can hide the assigment_id identifier you will need when reviewing assignments in a separate project.

By default, the field is visible — false.

Array array_<type> Array of objects of the same type. Used, for example, for multiple photos uploaded by a performer.

In JSON mode, there is a separate data type for the array. For example: "type": "array_file".

Min size

min_size Minimum number of items in the array.
Max size max_size Maximum number of items in the array.

Allowed values

allowed_values

Allowed values for string, integer, float and boolean data types.

Min length

min_length

Minimum length of the string.

Max length

max_length Maximum length of the string.

Min value

min_value Minimum values for float and integer numbers.

Max value

max_value Maximum values for float and integer numbers.
Current location

current_location

Saving the performer's current coordinates (true/false). Only for the coordinates data type. Used in tasks for the mobile app.

The default value is false.

Pattern pattern

Regular expression that the string must match. You can configure this parameter in JSON mode.

Recommendations

  • 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 the performer has to fill it in.
  • Make the field hidden if you don't want performers to access it. This is possible even if you don't display this field in the interface. To do this, add the "hidden": true parameter in JSON mode.

    Let's say you pass product data (like articles or batch numbers) that performers 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 the performers shouldn't have access to personal data.