Полное руководство по валидации JSON: синтаксис, схемы и лучшие практики

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

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

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

Три категории валидации защищают ваше приложение:

• Синтаксическая валидация — можно ли вообще разобрать JSON?
• Типовая валидация — соответствуют ли значения ожидаемым типам данных?
• Схемная валидация — соответствует ли структура ожидаемому контракту?

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

1. Ключи должны быть строками в двойных кавычках

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

// Неверно
{ name: "Алиса", 'age': 30 }

// Верно
{ "name": "Алиса", "age": 30 }

2. Нет завершающих запятых

Завершающие запятые после последнего элемента в объекте или массиве запрещены в JSON, хотя JavaScript их допускает.

// Неверно
{
  "host": "localhost",
  "port": 5432,
}

// Верно
{
  "host": "localhost",
  "port": 5432
}

3. Нет комментариев

В JSON нет синтаксиса комментариев. Ни //, ни /* */ не являются допустимыми.

Если вам нужны конфигурационные файлы с аннотациями, рассмотрите JSONC (JSON с комментариями) или JSON5 как надмножество, но учтите, что стандартные парсеры JSON их отклонят.

4. Строки должны быть правильно экранированы

Специальные символы внутри строк должны быть экранированы обратной косой чертой.

{
  "path": "C:\\Users\\alice\\documents",
  "message": "Она сказала \"привет\"",
  "newline": "первая строка\nвторая строка"
}

5. Числа подчиняются строгим правилам

Числа JSON не могут иметь ведущие нули (кроме самого 0), не могут использовать NaN или Infinity, и не должны заключаться в кавычки, если представляют числовые значения.

// Неверно
{ "value": 0123, "ratio": Infinity }

// Верно
{ "value": 123, "ratio": 1e308 }

6. Значение верхнего уровня должно быть допустимым

JSON-документ может иметь любое допустимое значение JSON в корне — объект, массив, строку, число, булево значение или null. Пустой файл или голый идентификатор — это недопустимый JSON.

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

Структурная валидация с JSON Schema

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

JSON Schema (определённая на json-schema.org) является стандартом для описания структуры, типов и ограничений JSON-документов.

Базовый пример JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "name", "email"],
  "properties": {
    "id": {
      "type": "integer",
      "minimum": 1
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "role": {
      "type": "string",
      "enum": ["admin", "editor", "viewer"]
    }
  },
  "additionalProperties": false
}

Эта схема обеспечивает соблюдение следующих условий:

• Документ является объектом с обязательными полями id, name и email
• id — положительное целое число
• name — непустая строка длиной до 100 символов
• email соответствует формату электронной почты
• role, если присутствует, должен быть одним из трёх допустимых значений
• Дополнительные поля не разрешены

Ключевые ключевые слова JSON Schema

Практические сценарии валидации

Валидация ответов API

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

async function fetchUser(id) {
  const response = await fetch(`/api/users/${id}`);
  const data = await response.json();

  // Валидировать перед использованием
  const valid = ajv.validate(userSchema, data);
  if (!valid) {
    throw new Error(`Недопустимый ответ API: ${ajv.errorsText()}`);
  }

  return data;
}

Валидация конфигурационных файлов

Конфигурационные файлы вроде appsettings.json или пользовательских config.json часто пишутся вручную и редко проверяются до тех пор, пока что-то не сломается. Запуск схемной валидации как части CI-пайплайна позволяет обнаружить неправильно настроенные развёртывания прежде, чем они попадут в продакшн.

# Используя ajv-cli
npx ajv validate -s config.schema.json -d config.json

Валидация тела запроса в API

На стороне сервера валидация входящих тел запросов защищает приложение от некорректного или вредоносного ввода. Библиотеки ajv, zod и joi легко интегрируются с фреймворками Node.js.

// Express middleware с использованием ajv
app.post('/users', (req, res) => {
  const valid = ajv.validate(createUserSchema, req.body);
  if (!valid) {
    return res.status(400).json({ errors: ajv.errors });
  }
  // обработка корректного запроса
});

Инструменты валидации

Несколько инструментов делают валидацию JSON простой и удобной:

• JSONKit Validate — вставьте любой JSON и получите мгновенный отчёт об ошибках синтаксиса с номерами строк, без установки
• ajv — самый быстрый валидатор JSON Schema для JavaScript/Node.js
• jsonschema — стандартная библиотека JSON Schema для Python
• json-schema-validator — широко используемая библиотека для Java

Советы по эффективной валидации JSON

1. Валидируйте на границах — валидируйте, когда данные поступают в систему или покидают её, а не глубоко внутри бизнес-логики.
2. Используйте строгие схемы — устанавливайте additionalProperties: false и явно помечайте все обязательные поля; нестрогие схемы пропускают реальные ошибки.
3. Включайте валидацию форматов — используйте ключевые слова format (email, uri, date-time) для выявления семантически некорректных строк.
4. Возвращайте структурированные ошибки — когда валидация не проходит, возвращайте путь к полю и нарушенное ограничение, а не просто «недопустимый JSON».
5. Тестируйте с некорректными данными — пишите тесты, намеренно передающие плохие данные, чтобы убедиться, что ваш уровень валидации их отклоняет.

Заключение

Валидация JSON не опциональна в продакшн-системах. Синтаксическая валидация обеспечивает разборчивость; схемная валидация обеспечивает корректность. Вместе они формируют надёжный контракт между производителями и потребителями данных.

Инструмент Validate в JSONKit позволяет мгновенно проверить любой JSON на наличие синтаксических ошибок — вставьте JSON, получите чёткий отчёт об ошибках с номерами строк и исправьте проблемы до того, как они попадут в ваш код. Без регистрации, без загрузки на сервер.