Валідувати синтаксис JSON

Для чого служить JSON validator?

JSON validator має більш скромну, але більш точну роль, ніж форматер: він нічого не переписує. Він бере рядок і відповідає на бінарне питання: чи є цей текст JSON, що відповідає RFC 8259? Якщо так, інструмент повертає контроль. Якщо ні, він вказує точно рядок, стовпець і фрагмент JSON навколо проблеми, щоб допомогти розробнику виправити її негайно.

На практиці, це інструмент, який використовується, як тільки де-небудь парсер повертає криптичне повідомлення про помилку типу SyntaxError: Unexpected token } in JSON at position 217. Замість того, щоб рахувати символи вручну в редакторі, вставте повний рядок, прочитайте позицію і побачте проблемний фрагмент.

Валідація, форматування: дві різні операції

Їх часто плутають. Наш JSON formatter бере дійсний JSON і переписує його з читабельним відступом. Валідатор, натомість, обмежується синтаксичним вердиктом. Він не виконує семантичну валідацію: він не знає, чи значення поля email схоже на email, ні чи структура відповідає JSON Schema. Для цього використовуйте спеціальні інструменти (ajv у Node, justinrainbow/json-schema у PHP).

Класична послідовність при debug: спочатку валідувати (інструмент вказує синтаксичну помилку), потім форматувати (тепер дійсний payload стає читабельним), нарешті порівнювати з іншим референсним payload через наш JSON diff.

Найпоширеніші помилки JSON

• Кінцева кома (trailing comma): {"a": 1, "b": 2,}. Допускається JavaScript, ECMAScript та JSON5; заборонена чистим JSON. Це помилка №1 при копіюванні-вставці з редактора коду.
• Апострофи замість подвійних лапок: {'a': 1} є недійсним. JSON приймає лише подвійні лапки, як навколо ключів, так і навколо рядкових значень.
• Ключі без лапок: {a: 1}, дійсний синтаксис JavaScript, але недійсний JSON.
• Неекрановані керуючі символи у рядку: сирий перенос рядка, табуляція. JSON вимагає \n, \t, \r.
• Коментарі: // коментар або /* */. Приймаються у JSONC (конфігурація VS Code) або JSON5, заборонені у чистому JSON.
• Неправильне кодування: BOM UTF-8 на початку файлу, вміст у latin-1, погано конвертований. Валідатор часто повертає загальне повідомлення для таких випадків.
• Незакінчена структура: { або [ без закриття, часте при усіченні payload під час копіювання-вставки.

Як валідатор локалізує помилку

Інструмент використовує json_decode() PHP з прапором JSON_THROW_ON_ERROR. PHP повертає повідомлення, що містить позицію у байтах (position 217), яку ми конвертуємо у пару рядок/стовпець, рахуючи переноси рядків перед зміщенням. Фрагмент приблизно 80 символів потім вирізається навколо позиції для надання контексту. Цього зазвичай достатньо для знаходження помилки з першого погляду.

Типові випадки використання

• Пошкоджена конфігурація: composer.json, package.json, tsconfig.json, які перешкоджають запуску білда. Вставляємо, бачимо рядок, виправляємо.
• Усічена відповідь API: проксі обрізав payload. Структура незавершена, валідатор це сигналізує.
• Payload вебхука: сторонній сервіс надсилає погано сформований JSON. Валідатор дозволяє зафіксувати проблему на стороні відправника без занурення в код застосунку.
• JSON, побудований конкатенацією: практика, яку слід уникати, але поширена, особливо в bash або SQL. Валідатор виявляє неекрановані подвійні лапки.

Обмеження інструменту

Валідатор не виконує перевірку за схемою. Він не повідомляє про відсутність поля email, що значення не є цілим числом або що очікуваний масив має неправильну довжину. Для цих структурних перевірок використовується JSON Schema. Валідатор також не виправляє JSON: він не намагається додати відсутню фігурну дужку чи видалити зайву кому. Це свідомий вибір: автоматичне виправлення занадто часто маскує реальні помилки.

Часті запитання

Приклад запиту

curl -X POST https://cdrn.fr/api/v1/tools/json-validator/execute \
  -H "Content-Type: application/json" \
  -d '{"input":"..."}'

Схема вхідних даних

Точки доступу

• GET https://cdrn.fr/api/v1/tools - перелічує всі доступні інструменти
• GET https://cdrn.fr/api/v1/tools/json-validator - отримує схему цього інструменту
• POST https://cdrn.fr/api/v1/tools/json-validator/execute - виконує цей інструмент з JSON-payload