Форматировать JSON

JSON—JavaScript Object Notation—это вездесущий текстовый формат для обмена структурированными данными. Он стандартизирован как IETF в качестве RFC 8259 , так и Ecma International в качестве ECMA-404, которые вместе определяют компактный, не зависящий от языка синтаксис, лежащий в основе современных API, журналов, конфигураций и баз данных.

Синтаксис и кодировка: точные биты, поддерживающие общение систем

Значение JSON — это либо объект, массив, строка, число, либо один из литералов true, false или null; объекты сопоставляют строки со значениями, а массивы содержат упорядоченные значения — с незначительными пробелами, разрешенными вокруг структурных символов (RFC 8259, ECMA-404). Хотя JSON возник из JavaScript, он не зависит от языка и поддерживается практически везде (MDN: JSON). По сети де-факто и рекомендуемой кодировкой является UTF-8 (RFC 8259 §8.1). Для дополнительной безопасности взаимодействия профиль I-JSON (RFC 7493) ужесточает правила в отношении кодировок и числовых диапазонов.

В JavaScript глобальный объект JSON предоставляет два основных инструмента:JSON.parse (с необязательным reviver) и JSON.stringify (с replacer/spacing для красивой печати), как задокументировано на MDN (parse, stringify).

Числа: обманчиво простые, удивительно острые

Числовая грамматика JSON является десятичной, но спецификация не предписывает точность или различия между целыми числами и числами с плавающей запятой. Реализации выбирают, как их представлять (RFC 8259 §6). В JavaScript и Node.js Number — это двойная точность IEEE-754, что означает, что только целые числа в диапазоне [−(2^53−1), 2^53−1] являются абсолютно безопасными — см. Number.MAX_SAFE_INTEGER и тип BigInt. Вот почему публичные API часто передают идентификаторы в виде строк и явно проверяют «безопасные целые числа».

За пределами ванильного JSON: указатели, исправления и исправления слиянием

По мере развития использования появились стандарты для адресации и изменения JSON на месте. JSON Pointer (RFC 6901) — это крошечный синтаксис с разделителями-косой чертой для поиска значений (например, /a/b/0) с правилами экранирования для ~ и /. JSON Patch (RFC 6902) моделирует частичные обновления как упорядоченные операции (add, remove, replace, move, copy, test) и передается как application/json-patch+json. Для более простых различий JSON Merge Patch (RFC 7386) использует слияние в форме документа: существующие поля добавляются/заменяются; установка поля в null удаляет его. Многие фреймворки поддерживают одну или обе формы из коробки.

Схемы и типы: проверка и генерация

Сам JSON не имеет схемы, но экосистемы полагаются на схемы для проверки, документации и генерации кода. Семейство JSON Schema 2020-12 определяет ограничения, такие как type, properties, items и ключевые слова композиции, и соответствует OpenAPI 3.1. Для рабочих процессов, ориентированных на генерацию кода, JSON Type Definition (RFC 8927) предлагает намеренно менее выразительный язык, который предсказуемо сопоставляется с основными системами типов.

Потоковая передача и большие данные: JSON Lines и последовательности

Классический JSON ожидает один полный текст на полезную нагрузку, что усложняет потоковую передачу журналов и долгоживущих ответов. Помогают два шаблона:

• Последовательности текста JSON (RFC 7464): поток текстов JSON в кодировке UTF-8, каждый из которых предваряется разделителем записей (U+001E) и заканчивается LF; зарегистрирован как application/json-seq.
• NDJSON / JSON Lines: каждая строка является автономным значением JSON— легко отслеживать, сжимать gzip и выполнять map-reduce (ndjson.org, jsonlines.org). Он популярен в массовых API, например, в Bulk APIElasticsearch.

Двоичные родственники: когда текст недостаточно компактен

Когда пропускная способность или скорость доминируют, форматы «двоичного JSON» сохраняют модель данных JSON, обменивая удобочитаемость на эффективность:

• BSON (собственный формат MongoDB) добавляет такие типы, как двоичный, datetime и типизированные целые числа (bsonspec.org).
• MessagePack компактен и не имеет схемы, широко реализован на разных языках (msgpack.org).
• CBOR стандартизирует расширяемый, компактный формат (с руководством по перекодированию JSON) и распространен в контекстах IoT/ограниченных ресурсов (RFC 8949, cbor.io).
• Smile (из экосистемы Jackson) кодирует JSON с необязательными обратными ссылками для повторяющихся имен/значений (jackson-dataformat-smile).

Примечания по безопасности: старые трюки и современные исправления

Поскольку JSON — это просто текст, большинство рисков связано с тем, как вы его передаете и обрабатываете:

• JSONP (запрос данных через <script> с обратным вызовом) был обходным путем до CORS для междоменных запросов, но опасен — он выполняет произвольный скрипт. Предпочитайте CORS с реальными ответами application/json (OWASP: злоупотребление JSONP).
• Перехват JSON: наивные конечные точки GET, возвращающие конфиденциальные массивы, могут быть украдены через междоменные теги скриптов в старых браузерах; меры по смягчению последствий включают POST с защитой CSRF или добавление префикса не-JSON-дозорного (OWASP: перехват JSON).
• Внедрение JSON: относитесь к JSON как к данным, а не к коду; тщательно экранируйте и проверяйте входные данные (OWASP: внедрение JSON).

Типы носителей и наследие

JSON дебютировал в RFC 4627 (2006); зарегистрированный тип носителя — application/json, спецификация которого теперь указывает на RFC 8259. Параметры «charset» в ответах JSON обычно не нужны, потому что UTF-8 является стандартом в общедоступном Интернете.

Практические советы по надежному JSON в производстве

• Используйте UTF-8 по умолчанию везде; предполагайте UTF-8 на входе и выходе (RFC 8259 §8.1).
• Будьте точны с большими целыми числами: если идентификатор может превышать 2^53−1, отправляйте его как строку и документируйте это (MDN: MAX_SAFE_INTEGER).
• Проверяйте полезные нагрузки с помощью JSON Schema 2020-12 (или JTD для стеков с интенсивной генерацией кода). Публикуйте схемы рядом с документацией по API (OpenAPI 3.1).
• Применяйте исправления с умом: используйте JSON Patch для различий на уровне операций и Merge Patch для простых обновлений в форме документа.
• Потоковая передача в масштабе: выбирайте Последовательности текста JSON или NDJSON для журналов и долгоживущих ответов; делайте тип носителя явным.
• Прибегайте к двоичным форматам ( BSON, MessagePack, CBOR, Smile), когда текст является узким местом, но убедитесь, что обе стороны согласны с типами.

Краткое слово о «более дружелюбных JSON»

Разработчики часто хотят комментарии, висячие запятые или строки в одинарных кавычках в конфигурациях. Это выходит за рамки стандартного JSON, но JSON5 предоставляет хорошо документированный надмножество для файлов, редактируемых человеком. Избегайте отправки JSON5 через публичные API, если вы не контролируете обе стороны.

Успех JSON обусловлен небольшой площадью поверхности, широкой поддержкой языков и кольцом смежных стандартов — указателей, исправлений, схем, последовательностей, — которые охватывают грязные реалии распределенных систем. Поймите основы (синтаксис, кодировка, числа), опирайтесь на правильные смежные стандарты, и это будет продолжать приносить дивиденды во всех стеках и сервисах (RFC 8259, ECMA-404, RFC 6901, RFC 6902, RFC 7386, JSON Schema, JTD, RFC 7464, NDJSON).