Input and output data

Note. This section describes how to edit the specification in the HTML/JS/CSS editor. To learn how to edit the specification in the Template Builder, go to the corresponding page.

In the Specifications field, you set parameters for input and output data. These settings will be valid for all tasks in the customizable project.

In the specification, add fields for the data used in the task or for the data you need in the results. Reference these fields when you configure the interface.

Don't repeat the input data in the output data. You will receive all data, including the input, in the results.

How to edit the specification

There are two ways to edit a specification in project settings: you can do it either in regular mode or in 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 .

To switch modes, click . Examples of fields:

Examples of fields:

Text in different formats

String of a certain length

"my_string": {
    "type": "string",
    "required": true,
    "min_length": 10,
    "max_length": 100
}
Copied to clipboard

Only Russian letters and numbers

"my_ru_string": {
    "type": "string",
    "required": true,
    "min_length": 10,
    "max_length": 100,
    "pattern": "[а-яА-Я0-9]+"
}
Copied to clipboard

Only Latin letters and numbers

"my_en_string": {
    "type": "string",
    "required": true,
    "min_length": 10,
    "max_length": 100,
    "pattern": "[a-zA-Z0-9]+"
}
Copied to clipboard

Letters and characters without numbers

"my_number_string": {
    "type": "string",
    "required": true,
    "min_length": 10,
    "max_length": 100,
    "pattern": "[^0-9]+"
}
Copied to clipboard

Link from a specific site

"my_url": {
    "type": "string",
    "required": true,
    "pattern": "(?:http(?:s)?:\\/\\/)?(?:[a-zA-z-]+(\\.)+)*(?:yandex\\.ru){1}(\\/|\\/[a-zA-Z-\\._~:/\\?#\\[\\]@!\\$&'\\(\\)\\*\\+,;=]+)?"
}
Copied to clipboard

Phone number with the +, - and space characters

"my_phone_string": {
    "type": "string",
    "required": true,
    "pattern": "\\+?[0-9\\s-]{4,}"
}
Copied to clipboard

Email with the @, - and . characters

"my_mail_string": {
    "type": "string",
    "required": true,
    "pattern": "[a-zA-Z]{1}[a-zA-Z0-9\\.\\-_]+@[a-zA-Z0-9\\.\\-_]+\\.[a-zA-Z]{2,}"
}
Copied to clipboard

Month

"my_month_string": {
    "type": "string", 
    "required": true,
    "allowed_values": ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October" "November", "December"] }
Copied to clipboard

Link

"my_url": {
    "type": "url",
    "required": true
}
Copied to clipboard

Boolean

"my_boolean": {
    "type": "boolean",
    "required": true
}
Copied to clipboard

Numbers

Integer from the specified range:

"my_integer": {
    "type": "integer",
    "required": true,
    "min_value": 1,
    "max_value": 100
}
Copied to clipboard

Integer with a list of allowed values:

"my_integer": {
    "type": "integer",
    "required": true,
    "allowed_values": [10, 20, 30]
}
Copied to clipboard

Fractional number:

"my_float": {
    "type": "float",
    "required": true,
    "min_value": 10.11,
    "max_value": 65.51
}
Copied to clipboard

A number with 0, 1, or 2 decimal places.
To do this, choose the string type and use regular expression for validation. Note that the decimal separator is a comma:
```
"my_mail_string": {
    "type": "string",
    "required": true,
    "pattern": "^([0-9]+)(,([0-9]){1,2})?$"
}
Copied to clipboard
```

File

"my_file": {
    "type": "file",
    "required": true
}
Copied to clipboard

Array of files

"my_file_array": {
    "type": "array_file",
    "required": true,
    "max_size": 5
}
Copied to clipboard

Coordinates

"my_coordinates": {
    "type": "coordinates",
    "required": true
}
Copied to clipboard

JSON

"my_json": {
    "type": "json",
    "required": true
}
Copied to clipboard

Hidden field

The string the performer can't access:

"my_string": {
    "type": "string",
    "hidden": true
}
Copied to clipboard

Explanations for configuring fields


Parameter	Parameter in JSON	Overview
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`. Attention. Hidden fields are not available in the task interface, even through JS or the template code in the constructor.
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.


Parameter	Parameter in JSON	Overview
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`. Attention. Hidden fields are not available in the task interface, even through JS or the template code in the constructor.
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.
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 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.

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

Create a task pool in the customizable project.
Learn more about how to set up a project:

Troubleshooting

How do I insert a function that is called by an image click in my task?

You can find an example of the task template for selecting image groups at this link. The input and output data, as well as a fragment of the instructions, are in the comments to the project.

How do I add a mask for the input field, like dd.mm.yyyy for the date field or numbers only (10 or 12) for INN (Taxpayer Identification Number)?

To validate the input data format, you can use the output field type, specifying the acceptable or minimum/maximum values. For example, create an output field for the taxpayer number with the “string” type and enter its minimum and maximum length (like 10 and 12). To use a more sophisticated validation in the template, use RegExp.

To enter a date, you can add a calendar to the task interface. See an example of a calendar.

Do I need to convert all the images in the task to the same size or can they be different?

You can use different image sizes.

If a project's output data may include any number from 1 to 999999, can I specify a range?

You can't use a range as a fixed value.

How do I show two different versions of the text to performers?

If you pass texts to the input data, you can upload 2 different tasks to the pool: pass Text 1 in the INPUT: <input field name> field of Task 1. In Task 2, use this field to pass Text 2.

If the text is in the HTML block of the task template, then clone the project. To limit a performer to doing only one task in your project, use the Submitted responses rule. You can assign a skill or ban the performer after they submit one response.