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

Введение

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

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

В этой статье вы узнаете:

• ✅ Что такое JSON и почему он стал стандартом
• ✅ Синтаксис и все типы данных
• ✅ Работа с JSON в JavaScript, Python и PHP
• ✅ JSON vs XML — когда что выбрать
• ✅ Валидация с JSON Schema
• ✅ Частые ошибки и как их избежать

Что такое JSON

JSON (JavaScript Object Notation) — текстовый формат обмена данными, основанный на синтаксисе объектов JavaScript. Несмотря на название, JSON не привязан к JavaScript — его поддерживают все современные языки программирования.

JSON используется повсюду:

• REST API — формат запросов и ответов
• Конфигурации — package.json, tsconfig.json, .eslintrc.json
• Базы данных — MongoDB, PostgreSQL (JSONB), CouchDB
• Обмен данными — между микросервисами, клиентом и сервером
• Хранение — localStorage в браузере, файлы настроек

Краткая история

Синтаксис JSON

JSON строится на двух структурах:

• Объект — набор пар «ключ: значение» в фигурных скобках { }
• Массив — упорядоченный список значений в квадратных скобках [ ]

Объект

{
  "name": "Иван Петров",
  "age": 30,
  "email": "ivan@example.com",
  "is_active": true
}

Массив

[
  "JavaScript",
  "Python",
  "Go",
  "PHP"
]

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

{
  "name": "Иван",
  "age": 30,          ← запятая после последнего элемента
}

Типы данных

JSON поддерживает 6 типов данных:

Вложенность и массивы

Настоящая мощь JSON — в комбинации объектов и массивов. Пример реального API-ответа:

{
  "user": {
    "id": 42,
    "name": "Иван Петров",
    "email": "ivan@example.com",
    "address": {
      "city": "Москва",
      "country": "Россия",
      "coordinates": {
        "lat": 55.7558,
        "lng": 37.6173
      }
    },
    "skills": ["JavaScript", "Python", "Go"],
    "projects": [
      {
        "id": 1,
        "name": "API Gateway",
        "status": "active",
        "tags": ["backend", "microservices"]
      },
      {
        "id": 2,
        "name": "Dashboard",
        "status": "completed",
        "tags": ["frontend", "react"]
      }
    ],
    "settings": {
      "theme": "dark",
      "notifications": {
        "email": true,
        "push": false,
        "sms": null
      }
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-23T10:30:00Z"
  }
}

Доступ к вложенным данным:

data.user.name                         // "Иван Петров"
data.user.address.city                 // "Москва"
data.user.address.coordinates.lat      // 55.7558
data.user.skills[0]                    // "JavaScript"
data.user.projects[1].name             // "Dashboard"
data.user.projects[0].tags[1]          // "microservices"
data.user.settings.notifications.email // true

JSON в JavaScript

JavaScript имеет встроенный объект JSON с двумя методами:

JSON.parse() — строка в объект

const jsonString = '{"name": "Иван", "age": 30}';
const obj = JSON.parse(jsonString);

console.log(obj.name); // "Иван"
console.log(obj.age);  // 30

// С reviver-функцией (преобразование при парсинге)
const data = JSON.parse(jsonString, (key, value) => {
  if (key === 'age') return value + 1;
  return value;
});
// data.age === 31

JSON.stringify() — объект в строку

const user = {
  name: "Иван",
  age: 30,
  skills: ["JS", "Python"]
};

// Компактная строка
JSON.stringify(user);
// '{"name":"Иван","age":30,"skills":["JS","Python"]}'

// Красивый вывод (с отступами)
JSON.stringify(user, null, 2);
// {
//   "name": "Иван",
//   "age": 30,
//   "skills": [
//     "JS",
//     "Python"
//   ]
// }

// С фильтрацией полей
JSON.stringify(user, ['name', 'age']);
// '{"name":"Иван","age":30}'

// С replacer-функцией
JSON.stringify(user, (key, value) => {
  if (typeof value === 'number') return undefined;
  return value;
});
// '{"name":"Иван","skills":["JS","Python"]}'

fetch + JSON

// GET — получение JSON
const response = await fetch('/api/users');
const users = await response.json();

// POST — отправка JSON
await fetch('/api/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Иван', email: 'ivan@test.ru' })
});

JSON в Python

import json

# Строка → словарь
json_string = '{"name": "Иван", "age": 30, "is_active": true}'
data = json.loads(json_string)
print(data['name'])  # Иван
print(type(data))    # <class 'dict'>

# Словарь → строка
user = {
    'name': 'Иван',
    'age': 30,
    'skills': ['Python', 'Go'],
    'address': None
}

# Компактно
json.dumps(user)
# '{"name": "\u0418\u0432\u0430\u043d", ...}'

# Красиво + кириллица
json.dumps(user, indent=2, ensure_ascii=False)
# {
#   "name": "Иван",
#   "age": 30,
#   "skills": ["Python", "Go"],
#   "address": null
# }

# Чтение из файла
with open('data.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

# Запись в файл
with open('output.json', 'w', encoding='utf-8') as f:
    json.dump(user, f, indent=2, ensure_ascii=False)

Маппинг типов Python ↔ JSON

JSON в PHP

<?php

// Строка → массив/объект
$jsonString = '{"name": "Иван", "age": 30, "skills": ["PHP", "Laravel"]}';

$data = json_decode($jsonString, true);  // true = ассоциативный массив
echo $data['name'];   // Иван
echo $data['age'];    // 30

$obj = json_decode($jsonString);  // объект stdClass
echo $obj->name;      // Иван

// Массив → строка
$user = [
    'name' => 'Иван',
    'age' => 30,
    'skills' => ['PHP', 'Laravel'],
    'address' => null
];

// Компактно
echo json_encode($user);

// Красиво + кириллица
echo json_encode($user, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
// {
//     "name": "Иван",
//     "age": 30,
//     "skills": ["PHP", "Laravel"],
//     "address": null
// }

// Проверка ошибок
$result = json_decode('invalid json');
if (json_last_error() !== JSON_ERROR_NONE) {
    echo 'Ошибка: ' . json_last_error_msg();
}

// PHP 7.3+: флаг JSON_THROW_ON_ERROR
try {
    $data = json_decode('invalid', true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo 'JSON ошибка: ' . $e->getMessage();
}

JSON vs XML

Одни и те же данные в двух форматах:

{
  "user": {
    "name": "Иван",
    "age": 30,
    "active": true
  }
}

<?xml version="1.0"?>
<user>
  <name>Иван</name>
  <age>30</age>
  <active>true</active>
</user>

Валидация: JSON Schema

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

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "email"],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 100,
      "description": "Имя пользователя"
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "Email адрес"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    },
    "role": {
      "type": "string",
      "enum": ["admin", "user", "moderator"],
      "default": "user"
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "uniqueItems": true,
      "maxItems": 10
    }
  },
  "additionalProperties": false
}

Валидация в коде

// Node.js (ajv — самый быстрый валидатор)
const Ajv = require('ajv');
const ajv = new Ajv();

const schema = {
  type: 'object',
  required: ['name', 'email'],
  properties: {
    name: { type: 'string', minLength: 2 },
    email: { type: 'string', format: 'email' }
  }
};

const validate = ajv.compile(schema);

const valid = validate({ name: 'Иван', email: 'ivan@test.ru' });
console.log(valid); // true

const invalid = validate({ name: '' });
console.log(validate.errors);
// [{ keyword: 'minLength', ... }, { keyword: 'required', ... }]

# Python (jsonschema)
from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "required": ["name", "email"],
    "properties": {
        "name": {"type": "string", "minLength": 2},
        "email": {"type": "string", "format": "email"}
    }
}

try:
    validate(instance={"name": "Иван", "email": "ivan@test.ru"}, schema=schema)
    print("Валидно!")
except ValidationError as e:
    print(f"Ошибка: {e.message}")

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

{'name': 'Иван'}   ← ОШИБКА: одинарные кавычки
{"name": "Иван"}   ← правильно: двойные кавычки

{"a": 1, "b": 2,}  ← ОШИБКА: запятая после последнего элемента
{"a": 1, "b": 2}   ← правильно

{name: "Иван"}      ← ОШИБКА: ключ без кавычек (это JS, не JSON)
{"name": "Иван"}    ← правильно

{"value": undefined}  ← ОШИБКА: undefined не существует в JSON
{"value": NaN}        ← ОШИБКА: NaN не существует в JSON
{"value": null}       ← правильно: используйте null

{"age": "30"}   ← это строка "30", не число
{"age": 30}     ← это число 30

Продвинутые темы

JSON Lines (NDJSON)

Для потоковой обработки больших данных — каждая строка файла является отдельным JSON-объектом:

{"id": 1, "name": "Иван", "action": "login"}
{"id": 2, "name": "Мария", "action": "purchase"}
{"id": 3, "name": "Алексей", "action": "logout"}

Преимущество: файл можно читать построчно, не загружая целиком в память. Используется в логах, Big Data, потоковых API.

JSON5 — расширенный JSON

Неофициальное расширение, добавляющее удобства:

// JSON5 — допускает:
{
  // Комментарии
  name: 'Иван',           // ключи без кавычек
  'surname': "Петров",    // одинарные кавычки
  age: 30,                // trailing comma
  bio: 'Строка с \
  переносом',             // многострочные строки
  hex: 0xFF,              // шестнадцатеричные числа
  infinity: Infinity,     // Infinity и NaN
}

Удобен для конфигурационных файлов, но не для API — не является стандартом.

JSON Pointer и JSON Patch

// JSON Pointer (RFC 6901) — путь к значению
"/user/address/city"      → data.user.address.city
"/users/0/name"           → data.users[0].name

// JSON Patch (RFC 6902) — описание изменений
[
  { "op": "replace", "path": "/name", "value": "Пётр" },
  { "op": "add", "path": "/phone", "value": "+7999" },
  { "op": "remove", "path": "/temp_field" }
]

JSON Patch позволяет описать изменения в документе без отправки всего объекта — используется в PATCH-запросах HTTP API.

FAQ

Заключение

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

Статья опубликована: 23 февраля 2026
Автор: LightBox API Team