Форматировщик JSON

Что делает этот форматировщик JSON

JSON (JavaScript Object Notation) — самый распространённый формат для передачи структурированных данных между программами: ответы API, файлы конфигурации, строки логов и многое другое. Он спроектирован компактным, что также делает его трудным для чтения, когда объекты вложены на несколько уровней или приходят одной строкой. Этот инструмент берёт любой JSON, который вы вставите, и переписывает его двумя способами: красиво отформатированным, с единообразными отступами, чтобы структура была видна с первого взгляда, или минифицированным, без каждого необязательного пробела, чтобы быть как можно меньше при передаче.

Он также проверяет данные во время форматирования. Поскольку он разбирает текст перед повторной сериализацией, некорректный JSON никогда не даёт обманчивого вывода — вместо этого вы получаете строку и столбец, где разбор не удался, всюду, где их удаётся вывести, и переходите прямо к проблеме.

Форматирование против минификации — когда что

Два режима служат противоположным целям, и большинство рабочих процессов используют оба на разных этапах:

• Форматируйте, когда читаете или отлаживаете: изучаете ответ API, сравниваете два payload или просматриваете файл конфигурации в pull request. Отступы превращают стену текста в удобное дерево.
• Минифицируйте, когда отправляете: встраиваете JSON в HTML, храните его в cookie или кэше, либо отправляете в теле запроса, где важен каждый байт. Минифицированный JSON — это ровно те же данные, только без пробелов.

Выбор отступа (2 пробела, 4 пробела или таб) влияет только на отформатированный вывод. Два пробела — самое распространённое соглашение в JavaScript и веб-инструментах; четыре пробела или табы подходят командам, которые их предпочитают. Что бы вы ни выбрали, результат остаётся корректным JSON — отступы носят чисто косметический характер.

Чтение ошибок проверки

Когда JSON некорректен, инструмент сообщает строку и столбец первой проблемы вместо простого «некорректно» — кроме единственного случая, который описывает раздел о том, куда указывают строка и столбец. Сообщения об ошибках движков различаются между браузерами и часто опускают позицию, поэтому место вычисляется независимо и указывает на разумную точку, откуда начать. Исправьте первую ошибку и проверьте снова — один заблудившийся символ часто превращается в несколько кажущихся проблем.

Частые ошибки в JSON

JSON строже, чем объектные литералы JavaScript, на которые он похож. Вот ошибки, которые чаще всего сбивают с толку:

• Завершающие запятые: запятая после последнего элемента объекта или массива корректна в JavaScript, но не в JSON.
• Одинарные кавычки: строки и ключи JSON должны использовать двойные кавычки. 'значение' некорректно; "значение" правильно.
• Ключи без кавычек: каждый ключ объекта должен быть строкой в кавычках, поэтому { name: "x" } должно стать { "name": "x" }.
• Комментарии: в JSON нет синтаксиса комментариев. // и /* */ вызовут ошибку разбора.
• Особые числа: NaN, Infinity и -Infinity не являются корректными числами JSON.
• Неправильные кавычки: «типографские кавычки», вставленные из текстового редактора, выглядят как кавычки, но это другие символы, и они не будут разобраны.

Куда указывают сообщённые строка и столбец

Позиция — это не то место, где вы что-то пропустили. Это место, где анализатор впервые встретил то, чего там быть не может, и обычно это два разных места. В объекте ниже строке 3 не хватает запятой, которая должна её закрывать, — и инструмент сообщает строку 4, столбец 3: открывающую кавычку следующего ключа. До прихода этой кавычки ничего неверного не было, потому что документ мог законно закончиться после строки 3; поэтому анализатор узнаёт о пропуске лишь тогда, когда встречает нечто, что не является ни запятой, ни закрывающей фигурной скобкой.

{
  "id": 42,
  "name": "widget"
  "price": 9.99
}

• Пропущенная запятая сообщается на первом символе того, что идёт дальше, а в JSON с отступами, как выше, это следующая строка: читайте названную строку вместе с той, что над ней.
• Лишняя запятая сообщается на закрывающей скобке: строка 3, столбец 1 для объекта, чья последняя пара стоит на строке 2. Запятая обещает ещё одну пару, а скобка — то, что нарушает обещание.
• Незакрытая строка обычно сообщается в конце той строки, на которой она открылась, а не на открывающей кавычке — потому что следующая кавычка на более поздней строке может закрыть её в другом месте. Перевод строки не может стоять внутри строки JSON, поэтому перевод и есть первый символ, которого там быть не может.
• Строка 1, столбец 1 в документе, который выглядит безупречно, обычно означает метку порядка байтов. Некоторые редакторы записывают её при сохранении в UTF-8; она невидима, стоит перед открывающей скобкой, и в JSON для неё нет места.

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

Что форматирование меняет и что сохраняет

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

• Один и тот же ключ, написанный дважды: выживает только последний из двух, потому что объект не может нести один ключ дважды. RFC 8259 говорит, что программа, получившая объект с повторяющимися именами, ведёт себя непредсказуемо, а другой анализатор может оставить первый, так что и на то, какой из двух вам достанется, полагаться нельзя.
• Целое число длиннее пятнадцати цифр: числа JSON читаются как число с плавающей точкой двойной точности, которое точно вмещает каждое целое до двух в пятьдесят третьей — шестнадцатизначного числа, — так что пятнадцатизначное целое выживает всегда, а более длинное может и не выжить. Вставьте 12345678901234567890, и выйдет 12345678901234567000. Длинные идентификаторы из базы данных — обычная жертва: держите их строками, если можете.
• Формы с экспонентой и с конечными нулями нормализуются: 1e3 возвращается как 1000, а 1.50 как 1.5. Это то же число, записанное стандартным образом.
• Величина за пределами того, что этот формат выдерживает, возвращается чем-то иным: у 1e400 нет значения двойной точности и она возвращается как null, а 1e-400 возвращается как 0. Длинная десятичная дробь округляется до той точности, которая у формата есть, ровно как и длинное целое.
• Escape-последовательность становится тем символом, который она обозначает: \u00e9 возвращается как é, а экранированная суррогатная пара — как эмодзи, который она составляет. Для любого анализатора это одна и та же строка; просто одна из двух записей короче.

Порядок ключей сохраняется таким, каким вы его написали, с одним исключением, которое стоит знать: ключ, состоящий только из цифр и читаемый как простое неотрицательное целое меньше примерно четырёх миллиардов, считается индексом массива и возвращается в начало своего объекта в числовом порядке, где бы вы его ни поставили. Больше ничто не двигается: никакой другой ключ не переставляется, и ни один не добавляется и не переименовывается. Если что-то из этого для вас важно, минифицируйте вместо форматирования и сравните результат со своим исходником символ за символом. Это самый короткий путь увидеть, что сделала поездка туда и обратно.

Когда нужный вам JSON лежит внутри строки

Журналы вебхуков, очереди сообщений и столбцы базы данных очень часто несут целый документ JSON как одно строковое значение, где каждая кавычка внутри экранирована. Внешний документ совершенно корректен, поэтому инструмент форматирует его и сообщает, что он корректен, — а та часть, за которой вы пришли, остаётся одной длинной строкой обратных слешей. Ничего не сломалось: это два документа, один завёрнут в строку другого.

{
  "event": "order.created",
  "payload": "{\"id\":42,\"total\":19.99}"
}

Поэтому чтение требует двух проходов. Отформатируйте здесь внешний документ, скопируйте то, что стоит между кавычками нужной строки, снимите экранирование и вставьте результат обратно. Инструмент Экранирование строк JSON делает этот средний шаг: его обратное направление превращает \" снова в ", а строку — в документ, который эта страница может отформатировать. Если вы управляете тем, что создало файл, лучшее исправление лежит выше: отправляйте payload вложенным объектом, а не строкой, и тогда ни один проход не нужен.

Один объект на строку — это не один документ

Файлы логов, экспорт из API и потоковые конечные точки обычно держат по одному целому объекту JSON на строку; формат называется JSON Lines, или NDJSON. Каждая строка сама по себе корректный JSON, но файл не является документом JSON, потому что документ JSON держит ровно одно значение верхнего уровня, а этот держит несколько, одно за другим и без чего-либо, что их соединяет.

{"level":"info","msg":"started"}
{"level":"warn","msg":"retrying"}
{"level":"error","msg":"gave up"}

Вставьте это здесь, и инструмент сообщит строку 2, столбец 1: первый объект закончился чисто, а затем начался второй там, где документ должен был завершиться. Отсюда есть два пути. Форматируйте по одной строке — это то, что нужно, когда вы читаете одну запись лога. Либо превратите файл в один документ: оберните строки в квадратные скобки и поставьте запятую в конце каждой строки, кроме последней, — это то, что нужно, когда вы собираетесь загрузить всё это в нечто, ожидающее массив.