Как валидировать JSON: полное руководство с примерами

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

Почему важна валидация JSON

Невалидный JSON — один из самых распространённых источников ошибок в веб-приложениях. Одна не на месте запятая, ключ без кавычек или завершающая запятая могут привести к тому, что JSON.parse() выбросит SyntaxError, обрушив весь конвейер данных. Валидация выявляет эти ошибки на ранних этапах, прежде чем они распространятся по системе и вызовут сбои в downstream.

Помимо синтаксической корректности, валидация также гарантирует, что JSON-данные соответствуют ожидаемой структуре. API может вернуть валидный JSON, но с отсутствующими обязательными полями, неправильными типами данных или значениями вне допустимого диапазона. Валидация Schema решает эти структурные проблемы.

Правила синтаксиса JSON

Прежде чем углубляться в инструменты валидации, важно понять правила, которые делают JSON валидным. JSON имеет строгий синтаксис, определённый RFC 8259, и даже одно нарушение символа делает весь документ невалидным.

Строки должны использовать двойные кавычки

Все строковые значения и ключи объектов должны быть заключены в двойные кавычки. Одинарные кавычки не являются допустимыми разделителями строк JSON — это распространённая ошибка разработчиков, переходящих с JavaScript.

// Invalid - single quotes
{'name': 'Alice', 'age': 30}

// Valid - double quotes
{"name": "Alice", "age": 30}

Ключи объектов должны быть в кавычках

В отличие от объектных литералов JavaScript, JSON требует, чтобы все ключи объектов были заключены в двойные кавычки. Ключи без кавычек являются синтаксической ошибкой.

// Invalid - unquoted keys
{name: "Alice", age: 30}

// Valid - quoted keys
{"name": "Alice", "age": 30}

Завершающие запятые запрещены

JSON не разрешает запятые после последнего элемента в объекте или массиве. Это ещё одна распространённая ошибка, особенно при ручном редактировании JSON.

// Invalid - trailing comma
{
  "name": "Alice",
  "age": 30,
}

// Valid - no trailing comma
{
  "name": "Alice",
  "age": 30
}

Комментарии не поддерживаются

JSON не поддерживает комментарии. Ни // однострочные, ни /* */ многострочные комментарии не являются допустимыми в JSON. Если вам нужна документация, используйте отдельные файлы или форматы, такие как JSONC.

Распространённые ошибки валидации JSON

Понимание самых распространённых ошибок помогает быстро их выявлять и исправлять. Вот ошибки, с которыми вы столкнётесь чаще всего:

• Неожиданный токен: обычно вызван одинарными кавычками, ключами без кавычек или завершающими запятыми. Сообщение об ошибке содержит позицию, где парсинг не удался.
• Неожиданный конец JSON-ввода: JSON-строка неполная или пустая. Это часто происходит, когда сетевой запрос возвращает пустой ответ.
• Неожиданный не-пробельный символ: дополнительный контент после основного JSON-значения, например, второй объект, не обёрнутый в массив.
• Невалидное число: числа с ведущими нулями (кроме самого 0), шестнадцатеричная нотация или значения NaN/Infinity не являются валидным JSON.

Валидация JSON в JavaScript

Самый простой способ валидации JSON в JavaScript — обернуть JSON.parse() в блок try-catch. Если JSON невалиден, метод выбрасывает SyntaxError.

function validateJSON(jsonString) {
  try {
    JSON.parse(jsonString);
    return { valid: true };
  } catch (error) {
    return {
      valid: false,
      error: error.message
    };
  }
}

const result = validateJSON('{"name": "Alice"}');
console.log(result);
// { valid: true }

const badResult = validateJSON("{'name': 'Alice'}");
console.log(badResult);
// { valid: false, error: "Unexpected token '..." }

Валидация JSON в Python

Python предоставляет модуль json с json.loads() для парсинга JSON-строк. Как и в JavaScript, невалидный JSON вызывает json.JSONDecodeError с подробной информацией о позиции.

import json

def validate_json(json_string):
    try:
        json.loads(json_string)
        return {"valid": True}
    except json.JSONDecodeError as e:
        return {
            "valid": False,
            "error": str(e),
            "line": e.lineno,
            "column": e.colno
        }

result = validate_json('{"name": "Alice"}')
print(result)
# {'valid': True}

Валидация JSON Schema

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

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "email"],
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0 }
  }
}

Популярные валидаторы JSON Schema включают Ajv для JavaScript, jsonschema для Python и json-schema-validator для Java. Эти библиотеки проверяют JSON-данные по вашей Schema и генерируют подробные сообщения об ошибках для каждого нарушения.

Онлайн-инструменты валидации JSON

Когда вам нужно быстро проверить JSON-документ без написания кода, онлайн-валидаторы — самый быстрый вариант. Они предоставляют мгновенную обратную связь с подсветкой ошибок и номерами строк.

Лучшие практики валидации JSON

• Валидируйте как можно раньше: проверяйте JSON на границах системы, таких как конечные точки API и функции импорта файлов, до того, как данные попадут в бизнес-логику.
• Используйте валидацию Schema: помимо синтаксиса, используйте валидацию JSON Schema для проверки структуры данных, выявления отсутствующих полей, неправильных типов и значений вне диапазона.
• Предоставляйте чёткие сообщения об ошибках: когда валидация не удаётся, включайте путь к полю, ожидаемый тип и фактическое значение, чтобы помочь пользователям быстро исправить проблему.
• Валидируйте и на клиенте, и на сервере: клиентская валидация обеспечивает мгновенную обратную связь, а серверная валидация гарантирует безопасность и целостность данных.
• Автоматизируйте валидацию в CI/CD: используйте инструменты, такие как ajv-cli или jsonschema, для проверки JSON-фикстур и конфигурационных файлов в конвейере сборки.
• Логируйте ошибки валидации: записывайте сбои валидации с контекстом, чтобы выявлять закономерности и устранять коренные причины в производителях данных.