Toloka documentation

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.

Alert

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.

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

You can configure the specification manually. In this case, automatic detection of input and output data doesn't work. You may need to enable this option if:

  • You don't want the specification version to be affected by changes in the instructions or other project fields.
  • You have fields that you need but they become optional or are deleted after automatic generation.

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.

Examples:

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_address": {
        "country": "UK",
        "city": "London",
        "address": "221b Baker St"
    }
}

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"
  ]
}

Note

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.

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"
  }
}

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

Note

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.

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 image/svg+xml . 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
    }
    
  • Only Latin letters and numbers

    "my_en_string": {
        "type": "string",
        "required": true,
        "min_length": 10,
        "max_length": 100,
        "pattern": "[a-zA-Z0-9]+"
    }
    
  • Only Russian letters and numbers

    "my_ru_string": {
        "type": "string",
        "required": true,
        "min_length": 10,
        "max_length": 100,
        "pattern": "[а-яА-Я0-9]+"
    }
    
  • Letters and characters without numbers

    "my_number_string": {
        "type": "string",
        "required": true,
        "min_length": 10,
        "max_length": 100,
        "pattern": "[^0-9]+"
    }
    
  • Link from a specific site

    "my_url": {
        "type": "string",
        "required": true,
        "pattern": "(?:http(?:s)?:\\/\\/)?(?:[a-zA-z-]+(\\.)+)*(?:google\\.com){1}(\\/|\\/[a-zA-Z-\\._~:/\\?#\\[\\]@!\\$&'\\(\\)\\*\\+,;=]+)?"
    }
    
  • Phone number with the +, - and space characters

    "my_phone_string": {
        "type": "string",
        "required": true,
        "pattern": "\\+?[0-9\\s-]{4,}"
    }
    
  • 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,}"
    }
    
  • Month

    "my_month_string": {
        "type": "string",
        "required": true,
        "allowed_values": ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October" "November", "December"]
    }
    
Link
"my_url": {
    "type": "url",
    "required": true
}
Boolean
"my_boolean": {
    "type": "boolean",
    "required": true
}
Numbers
  • Integer from the specified range:

    "my_integer": {
        "type": "integer",
        "required": true,
        "min_value": 1,
        "max_value": 100
    }
    
  • Integer with a list of allowed values:

    "my_integer": {
        "type": "integer",
        "required": true,
        "allowed_values": [10, 20, 30]
    }
    
  • Fractional number:

    "my_float": {
        "type": "float",
        "required": true,
        "min_value": 10.11,
        "max_value": 65.51
    }
    
  • 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})?$"
    }
    
File
"my_file": {
    "type": "file",
    "required": true
}
Array of files
"my_file_array": {
    "type": "array_file",
    "required": true,
    "max_size": 5
}
Coordinates
"my_coordinates": {
    "type": "coordinates",
    "required": true
}
JSON
"my_json": {
    "type": "json",
    "required": true
}
Hidden field

The string a Toloker can't access:

"my_string": {
    "type": "string",
    "hidden": true
}
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 Toloker's response is required in the output data.

By default, fields are optional — false.

Hidden

hidden

Allows you to hide data from a Toloker. If this is not done, Tolokers 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.

Reviewing assignments

A pool setting that allows you to check responses so you don't have to pay for poorly completed tasks.

By default, the field is visible — false.

Warning

Hidden fields are not available in the task interface, even through JS or the template code in the constructor.

Array

array_<тип>

Array of objects of the same type. Used, for example, for multiple photos uploaded by a Toloker. 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 Toloker'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 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