Единообразные имена и регистр полей JSON

Что это такое

JSON (RFC 8259, указан в источниках) ограничивает только синтаксис: объекты состоят из пар имя/значение, имена являются строками, а внутри одного объекта их следует делать уникальными. Вид имён определяется соглашением. Руководство Google по стилю JSON (указано в источниках) требует имён свойств в виде ASCII-строк в camelCase с определённым смыслом, предостерегает от произвольной группировки данных, представляет значения перечислений строками и даты — строками RFC 3339. Отображение ProtoJSON (указано в источниках) сериализует имена полей protobuf в ключи lowerCamelCase, значения перечислений — в их имена, а 64-битные целые — в десятичные строки, поскольку многие потребители JSON не могут представить их точно. snake_case (created_at) столь же распространён. Важно, чтобы одно соглашение действовало для всех конечных точек, включая тела ошибок и полезную нагрузку вебхуков.

Почему это важно

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

Как применять

• Запишите соглашение в руководство по стилю API с примерами: регистр, множественное число для массивов (items), префиксы булевых полей (isActive, hasChildren), суффиксы единицы или формата (durationSeconds, sizeBytes), окончание Id у полей идентификаторов.
• Обеспечьте автоматический контроль: линтер документа OpenAPI либо правила имён полей protobuf вместе с отображением ProtoJSON.
• Именуйте по смыслу, а не по хранению: customerId, а не cust_fk; не переименовывайте поле при изменении столбца базы данных.
• Один раз выберите форматы значений: временные метки RFC 3339 со смещением, явные суффиксы единиц или длительности ISO 8601, строки перечислений вместо чисел, денежные суммы строками или целыми числами минимальных денежных единиц.
• Используйте одинаковое имя для одного понятия в разных ресурсах; owner в одном ресурсе и ownerId в другом — дефект.
• Отдельно обрабатывайте объекты JSON, используемые как словари: их ключи — данные, на них правило именования не распространяется, а документация должна указывать, какие объекты являются словарями.

Подводные камни

Переименование поля ради исправления регистра — несовместимое изменение; добавьте новое имя и сохраните старое на период вывода из употребления. Выведение идентификаторов реализации, таких как $type или __typename, в публичный контракт без документации. Сокращения, понятные только исходной команде. Дубликаты с разным регистром (userId и userID), сохраняющиеся потому, что никто не запускает линтер.