Какие атрибуты полей указываются в API контракте кроме имени и формата

Что проверяют

Проектировали ли вы контракты сами или только читали чужие. Интервьюер ждёт, что вы опишете поле так, чтобы разработчики обеих сторон не пришли к вам с вопросами. Следом часто спрашивают, чем обязательное поле отличается от поля, которое может быть null.

Как отвечать

Удобно отвечать в терминах OpenAPI, это фактический стандарт для REST-контрактов:

• обязательность: в схеме тела это список required на уровне объекта, для параметров пути и запроса флаг required: true. Может различаться для запроса и ответа;
• допустимость null: nullable: true в OpenAPI 3.0 или type: [string, "null"] в 3.1. Обязательное поле может приходить со значением null, и это отдельная договорённость;
• ограничения: minLength, maxLength, pattern, minimum, maximum, для массивов minItems, maxItems, uniqueItems;
• перечисление: enum с описанием каждого значения и правилом, что клиент делает с незнакомым значением;
• значение по умолчанию: default, и кто его подставляет, сервер или клиент;
• направление: readOnly для полей, которые генерирует сервер (ID, дата создания), writeOnly для пароля;
• описание и пример: description с бизнес-смыслом и единицами измерения, example;
• устаревание: deprecated: true и дата, после которой поле уберут.

За пределами схемы аналитик фиксирует ещё маппинг поля на источник (система, таблица, колонка), бизнес-правила валидации, коды ошибок при нарушении и чувствительность данных, например что поле содержит персональные данные и не пишется в логи.

Где спотыкаются

Путают обязательность и nullable. Одна сторона присылает null, другая ждёт, что поля не будет вовсе, и интеграция падает уже на проде.

Называют уникальность атрибутом поля в контракте. В схеме её нет, кроме uniqueItems для элементов массива. Уникальность это бизнес-правило, её описывают текстом и отдельным кодом ошибки.

Не пишут единицы и форматы: сумма в рублях или копейках, дата в UTC или в локальном времени. Поле формально описано, а смысл у каждой стороны свой.