Документация Толоки

Создание спецификации

Обратите внимание

Документация на русском языке может быть устаревшей. Самые последние изменения доступны в документации на английском языке.

В Толоке в настройках проекта должна быть указана спецификация входных и выходных данных. Если вы используете конструктор шаблонов в интерфейсе Толоки, то по умолчанию спецификация создается автоматически.

Внимание

Создание спецификации работает в тестовом режиме. После сохранения проекта проверьте спецификацию входных и выходных данных. Если возникнут проблемы, обратитесь в службу поддержки.

Режимы настройки спецификации

Спецификацию можно настраивать как автоматически, так и вручную. Изменить способ настройки спецификации можно с помощью опции Настроить спецификацию вручную. По умолчанию опция выключена.

Cпецификация входных и выходных данных генерируется автоматически в зависимости от настроек интерфейса задания.

Вы можете сами настроить спецификацию. В этом случае автоматическое определение входных и выходных данных работать не будет. Включение опции может понадобиться, если:

  • Вы хотите, чтобы изменение инструкции или других полей проекта не повлияло на версию спецификации.
  • У вас есть поля, которые вам нужны, но после автоматической генерации они становятся необязательными или вообще удаляются.

Заполнение входных данных

Если используется автоматическая генерация спецификации, то поля входных данных создаются из кода конфигурации. Указывайте максимально подробный пример, чтобы получить готовую спецификацию. Например, если есть необязательные поля, укажите и их.

Примеры:

В этом примере в спецификации будет создано поле question с типом строка.

{
  "question": "Do you like dogs?"
}

В этом примере в спецификации будет создано поле verdict с типом логический.

{
  "verdict": true
}

В этом примере в спецификации будет создано поле age с типом число.

{
  "age": 42
}

В этом примере в спецификации будет создано поле registration_аddress с типом JSON.

{
    ...
    "registration_address": {
        "country": "UK",
        "city": "London",
        "address": "221b Baker St"
    }
}

В этом примере в спецификации будет создано поле images с типом массив.

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

Примечание

По умолчанию все поля входных данных в спецификации помечаются обязательными. Чтобы сделать поле необязательным, надо в конфигурации в компоненте data.input задать свойство default.

Заполнение выходных данных

Если используется автоматическая генерация спецификации, то поля выходных данных создаются из кода конфигурации. Учитывается то, в каких компонентах используется data.output, а также какие значения в нем разрешены.

Примеры:

В этом примере в спецификации будет поле verdict с типом логический.

{
  "type": "field.radio-group",
  "options": [
    {
      "label": "Да",
      "value": true
    },
    {
      "label": "Нет",
      "value": false
    }
  ],
  "data": {
    "type": "data.output",
    "path": "verdict"
  }
}

В этом примере в спецификации будет поле verdict с типом строка и допустимыми значениями "true", "false".

{
  "type": "field.radio-group",
  "options": [
    {
      "label": "Да",
      "value": "true"
    },
    {
      "label": "Нет",
      "value": "false"
    }
  ],
  "data": {
    "type": "data.output",
    "path": "verdict"
  }
}

В этом примере в спецификации будет поле verdict с типом число и допустимыми значениями 0 и 1.

{
  "type": "field.radio-group",
  "options": [
    {
      "label": "Да",
      "value": 1
    },
    {
      "label": "Нет",
      "value": 0
    }
  ],
  "data": {
    "type": "data.output",
    "path": "verdict"
  }
}

В этом примере в спецификации будет поле results с типом JSON. В поле results будет записан JSON-объект { "verdict": true } или { "verdict": false }.

{
  "type": "field.radio-group",
  "options": [
    {
      "label": "Да",
      "value": true
    },
    {
      "label": "Нет",
      "value": false
    }
  ],
  "data": {
    "type": "data.output",
    "path": "results.verdict"
  }
}

В этом примере в спецификации будет поле verdicts с типом массив.

{
  "type": "field.radio-group",
  "options": [
    {
      "label": "Да",
      "value": 1
    },
    {
      "label": "Нет",
      "value": 0
    }
  ],
  "data": {
    "type": "data.output",
    "path": "verdicts.0"
  }
}

Примечание

Если в выходных данных будут значения разных типов, то в спецификации будет указан тип JSON.

Как редактировать спецификацию

Примечание

Редактирование спецификации доступно только при включенной опции Настроить спецификацию вручную.

Чтобы добавить поле в обычном режиме, нажмите кнопку Добавить поле.

Чтобы редактировать существующее поле, наведите курсор на поле и нажмите кнопку .

Для переключения режима нажмите кнопку . Примеры полей:

Примеры полей

Текст в разных форматах

  • Строка определенной длины

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

  • Только латинские буквы и цифры

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

  • Только русские буквы и цифры

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

  • Буквы и символы без цифр

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

  • Ссылка с определенного сайта

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

  • Номер телефона с символами +, - и пробелом

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

  • Электронная почта с символами @, - и .

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

  • Месяц

    "my_month_string": {
    "type": "string",
    "required": true,
    "allowed_values": ["январь", "февраль", "март", "апрель", "май", "июнь", "июль", "август", "сентябрь", "октябрь" "ноябрь", "декабрь"]
}
Ссылка
"my_url": {
    "type": "url",
    "required": true
}
Логический тип данных
"my_boolean": {
    "type": "boolean",
    "required": true
}
Числа

  • Целое число из указанного диапазона:

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

  • Целое число со списком допустимых значений:

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

  • Дробное число:

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

  • Число с 0, 1 или 2 знаками после запятой.

    Для этого надо выбрать тип строка и проверять с помощью регулярного выражения. Обратите внимание, что разделитель дробной части — запятая:

    "my_mail_string": {
    "type": "string",
    "required": true,
    "pattern": "^([0-9]+)(,([0-9]){1,2})?$"
}
Файл
"my_file": {
    "type": "file",
    "required": true
}
Массив файлов
"my_file_array": {
    "type": "array_file",
    "required": true,
    "max_size": 5
}
Географические координаты
"my_coordinates": {
    "type": "coordinates",
    "required": true
}
JSON
"my_json": {
    "type": "json",
    "required": true
}
Скрытое поле

Строка, к которой исполнитель не сможет получить доступ:

"my_string": {
    "type": "string",
    "hidden": true
}
Пояснения к настройке полей

Параметр

Параметр в JSON

Описание

Название

id

Идентификатор поля. Допустимы латинские буквы, цифры, дефис и нижнее подчеркивание.

Тип

type

Тип данных:

  • строка — string;

  • ссылка — url;

  • логический — boolean;

  • число — number;

  • дробное число — float;

  • файл — file;

  • географические координаты — coordinates;

  • объект JSON — json.

Для массивов в режиме JSON к типу добавляется префикс array_. Например: array_file.

Обязательное поле

required

Обязательность объекта при загрузке заданий для входных данных.

Обязательность ответа исполнителя для выходных данных.

По умолчанию поле необязательное — false.

Скрытое поле

hidden

Позволяет скрыть данные от исполнителя. Если этого не сделать, исполнители могут получить значение поля программно. Параметр можно настроить в режиме JSON.

Например, вы можете скрыть идентификатор assigment_id, который вам понадобится при выполнении отложенной приемки в отдельном проекте.

Отложенная приемка

Параметр настройки пула, который позволяет проверять ответы и при этом не платить за задания, которые исполнители сделали некачественно.

По умолчанию поле открытое — false.

Внимание

Скрытые поля недоступны в интерфейсе задания, даже через JS или код шаблона в конструкторе.

Массив

array_<тип>

Массив объектов одного типа. Используется, например, для загрузки нескольких фотографий исполнителем. В режиме JSON массив — это отдельный тип данных. Например: "type": "array_file".

Мин. элементов

min_size

Минимальное число элементов в массиве.

Макс. элементов

max_size

Максимальное число элементов в массиве.

Допустимые значения

allowed_values

Допустимые значения для строк, дробных и целых чисел, логического типа данных.

Мин. длина

min_length

Минимальная длина строки.

Макс. длина

max_length

Максимальная длина строки.

Мин. значение

min_value

Минимальное значений для дробных и целых чисел.

Макс. значение

max_value

Максимальное значений для дробных и целых чисел.

Текущее положение

current_location

Сохранение текущих координат исполнителя (true/false). Только для типа данных coordinates. Используется в заданиях для мобильного приложения.

По умолчанию false.

Шаблон

pattern

Регулярное выражение, которому должна соответствовать строка. Параметр можно настроить в режиме JSON.

Рекомендации

  • Если вы редактируете обязательные поля, изменения применятся только к новым пулам заданий. Например, если вам пришлось исправить ошибку в проекте, клонируйте пул или создайте новый. Существующие пулы заданий будут работать в соответствии со старой версией проекта.

  • В выходных данных используйте проверку значений и не забывайте помечать поле обязательным, если исполнитель всегда должен заполнить его.

  • Скрытые поля нужны только заказчикам и недоступны в интерфейсе задания. Значения скрытых полей невозможно использовать ни в JS-коде, ни в конструкторе шаблонов.

    Например, вы передаете в задании служебные данные товара, которые не нужны исполнителям: артикул или номер партии. Или вы модерируете комментарии и вам нужны в результатах персональные данные авторов для последующей обработки данных, но исполнители не должны иметь к ним доступ.

    Чтобы создать скрытое поле, добавьте его в спецификацию самостоятельно, затем в режиме JSON добавьте к этому полю параметр "hidden": true. Эти действия надо выполнять в Толоке при настройке проекта. Скрытое поле сохранится при повторной генерации спецификации с помощью Конструктора шаблонов.

Что дальше

В этой статье: