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.
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.
In this example, the question
field with the string type will be created in the specification.
{
"question": "Do you like dogs?"
}
In this example, the verdict
field with the boolean type will be created in the specification.
{
"verdict": true
}
In this example, the age
field with the number type will be created in the specification.
{
"age": 42
}
In this example, the registration_address
field with the JSON type will be created in the specification.
{
...
"registration_аddress": {
"country": "Russia",
"city": "Moscow",
"address": "Tverskaya str, 3-53"
}
}
In this example, the images
field with the array type will be created in the specification.
{
"images": [
"https://cdn.stocksnap.io/img-thumbs/960w/surfer-wave_3DBOYBPB3X.jpg",
"https://cdn.stocksnap.io/img-thumbs/960w/fisherman-silhouette_UADULRRHEK.jpg",
"https://cdn.stocksnap.io/img-thumbs/960w/old-photo_GEQ27OWZVV.jpg"
]
}
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"
}
}
In this example, the specification will contain the verdict
field with the string type and the acceptable values "true" and "false".
{
"type": "field.radio-group",
"options": [
{
"label": "Yes",
"value": "true"
},
{
"label": "No",
"value": "false"
}
],
"data": {
"type": "data.output",
"path": "verdict"
}
}
In this example, the specification will contain the verdict
field with the number type and acceptable values 0
and 1
.
{
"type": "field.radio-group",
"options": [
{
"label": "Yes",
"value": 1
},
{
"label": "No",
"value": 0
}
],
"data": {
"type": "data.output",
"path": "verdict"
}
}
In this example, the specification will contain the results
field with the JSON type. The results
field will have the JSON object { "verdict": true }
or { "verdict": false }
.
{
"type": "field.radio-group",
"options": [
{
"label": "Yes",
"value": true
},
{
"label": "No",
"value": false
}
],
"data": {
"type": "data.output",
"path": "results.verdict"
}
}
In this example, the specification will contain the images
field with the array type.
{
"type": "field.radio-group",
"options": [
{
"label": "Yes",
"value": 1
},
{
"label": "No",
"value": 0
}
],
"data": {
"type": "data.output",
"path": "verdicts.0"
}
}
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 .
To switch modes, click . Examples of fields:
- Examples of fields:
-
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 - 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": ["январь", "февраль", "март", "апрель", "май", "июнь", "июль", "август", "сентябрь", "октябрь" "ноябрь", "декабрь"] }
Copied to clipboard - 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 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
Text in different formatsBoolean"my_boolean": { "type": "boolean", "required": true }
Copied to clipboardNumbersArray of files"my_file_array": { "type": "array_file", "required": true, "max_size": 5 }
Copied to clipboardCoordinates"my_coordinates": { "type": "coordinates", "required": true }
Copied to clipboard
string
url
boolean
number
float
file
coordinates
json
string
url
boolean
number
float
file
coordinates
json
Parameter | Parameter in JSON | Description |
---|---|---|
Name | id | Field ID. Only Latin letters, numbers, hyphens and underscores are allowed. |
Type | type | Data type: For arrays, add the |
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 — |
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 By default, the field is visible — |
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: |
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 |
| Saving the performer's current coordinates ( The default value is |
Pattern | pattern | Regular expression that the string must match. You can configure this parameter in JSON mode. |
Parameter | Parameter in JSON | Description |
---|---|---|
Name | id | Field ID. Only Latin letters, numbers, hyphens and underscores are allowed. |
Type | type | Data type: For arrays, add the |
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 — |
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 By default, the field is visible — |
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: |
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 |
| Saving the performer's current coordinates ( The default value is |
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.