Skip to content

JSON Шпаргалка

Лёгкий формат обмена данными.

01

Начало работы

Базовая структура

JSON поддерживает 6 типов данных: строка, число, логическое значение, null, массив и объект. Ключи должны быть строками в двойных кавычках. JSON не зависит от языка и легко читается и людьми, и машинами.

json
{
  "name": "Alice",
  "age": 30,
  "isStudent": false,
  "height": 1.65,
  "nullValue": null,
  "hobbies": ["reading", "coding", "music"],
  "address": {
    "city": "NYC",
    "zip": "10001"
  }
}

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

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

json
{
  "key": "value",          // key MUST be a double-quoted string
  "nested": { "a": 1 },    // objects use { } with comma-separated pairs
  "list": [1, 2, 3]        // arrays use [ ] with comma-separated values
}

// Rules:
// - Double quotes only for strings and keys (no single quotes)
// - Comma separates members; NO trailing comma
// - The whole document is ONE value (usually an object or array)
// - No comments allowed in standard JSON

Комментарии в JSON

Стандартный JSON запрещает комментарии. Частые обходные пути: добавить поле '_comment' (код его игнорирует), использовать JSONC/JSON5 (поддерживают VS Code и многие инструменты) или вырезать комментарии перед разбором библиотекой вроде comment-json или JSON.minify.

json
// Standard JSON does NOT allow comments.

// Workaround 1: include a descriptive field
{
  "_comment": "This is a config file for the app",
  "port": 8080
}

// Workaround 2: use JSON5 or JSONC (VS Code settings)
{
  // line comment
  "port": 8080 /* block comment */
}

// Workaround 3: strip comments before parsing
// (e.g., JSON.minify, comment-json npm package)

Пробелы и форматирование

Пробелы вне строк незначимы: компактная и красиво отформатированная формы разбираются в одно и то же значение. Компактный JSON экономит трафик; pretty-print (обычно отступ в 2 пробела) улучшает читаемость и диффы. Большинство сериализаторов дают опцию 'pretty'.

json
// These are all equivalent:

{"a":1,"b":2}                       // compact (no whitespace)

{ "a": 1, "b": 2 }                  // readable

{
  "a": 1,
  "b": 2
}                                   // pretty-printed

// Whitespace between tokens is insignificant.
// Use compact for transmission, pretty for humans.

Расширение файла и MIME-тип

Стандартное расширение — .json, MIME-тип — application/json. Варианты вроде JSONC, JSON5, GeoJSON и NDJSON имеют свои соглашения. Всегда используйте кодировку UTF-8; BOM не рекомендуется.

json
// File extensions:
//   .json    standard JSON
//   .jsonc   JSON with comments (VS Code, TypeScript config)
//   .json5   JSON5 (relaxed syntax)
//   .geojson GeoJSON (geographic data)
//   .ndjson  Newline-Delimited JSON (JSON Lines)
//   .har     HTTP Archive (JSON-based)

// MIME type:
Content-Type: application/json

// Older/alternate MIME types (avoid):
//   text/json          (non-standard)
//   application/x-json (non-standard)

// UTF-8 is the default and recommended encoding.

Категории значений JSON

Значения JSON делятся на шесть типов: строка, число, логическое значение, null, массив, объект. Массивы и объекты структурные (могут содержать другие значения), остальные — примитивы. Корректный документ JSON — одно значение: обычно объект или массив, но и голое число или строка тоже допустимы.

json
// A JSON value is exactly one of these six types:

"hello"                 // string
42                      // number
3.14                    // number
true                    // boolean
false                   // boolean
null                    // null
[1, 2, 3]               // array
{ "a": 1 }              // object

// Structured types: array, object
// Primitive types: string, number, boolean, null
// A standalone JSON document is a single value of any type.
02

Типы данных

Тип строка

Строки JSON — текст Unicode в двойных кавычках. Частые экранирования: \" (кавычка), \\ (обратная косая), \/ (слэш), \n, \t, \r, \b, \f и \uXXXX для любого символа Unicode. Одинарные кавычки как разделители строк не допускаются.

json
{
  "single": "double quotes only",
  "empty": "",
  "escaped": "He said \"hi\" and C:\\Users",
  "unicode": "Cafu00e9 \u00e9 \u1F600",
  "multiline": "line1\nline2\ttabbed"
}

// Strings MUST use double quotes.
// Single quotes are NOT valid in JSON.

Тип число

Числа JSON следуют подмножеству двойной точности IEEE 754: целые, десятичные и научная нотация (например, 6.022e23). Ведущие нули запрещены (007 невалидно). NaN, Infinity и -Infinity НЕ допустимы: при необходимости кодируйте их как null или строки.

json
{
  "integer": 42,
  "negative": -7,
  "float": 3.14,
  "zero": 0,
  "scientific": 6.022e23,
  "small": 1.5e-10
}

// Numbers are NOT quoted.
// No leading zeros (007 is invalid).
// No NaN, Infinity, or -Infinity (not valid JSON).

Тип boolean

Логические значения JSON — литералы true и false (в нижнем регистре, без кавычек). 'true'/'false' в кавычках — строки. В JSON нет понятия 0/1 или yes/no как логических: преобразуйте их в коде приложения.

json
{
  "enabled": true,
  "disabled": false,
  "flag": true
}

// Booleans are the bare keywords true and false.
// They are NOT quoted ("true" is a string).
// 0/1, yes/no, on/off are NOT booleans in JSON.

Тип null

JSON null — голое ключевое слово null (без кавычек). Оно сигнализирует намеренное отсутствие значения. Учтите: null отличается от пустой строки '', 0, false или отсутствующего ключа. Многие языки отображают null в None/nil/null.

json
{
  "middleName": null,
  "deletedAt": null,
  "optional": null
}

// null is a bare keyword (unquoted).
// "null" (quoted) is a string, not null.
// null represents the intentional absence of value.

Тип массив

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

json
{
  "numbers": [1, 2, 3],
  "mixed": [1, "two", true, null],
  "nested": [[1, 2], [3, 4]],
  "objects": [
    { "id": 1 },
    { "id": 2 }
  ],
  "empty": []
}

// Arrays are ordered, zero-indexed, and can hold mixed types.

Тип объект

Объекты JSON — неупорядоченные наборы пар ключ/значение в { }. Ключи — уникальные строки в двойных кавычках; значения — любого типа JSON. Хотя объекты концептуально неупорядочены, большинство парсеров сохраняет порядок вставки; не полагайтесь на порядок для корректности.

json
{
  "user": {
    "id": 1,
    "name": "Alice",
    "roles": ["admin", "user"],
    "active": true
  },
  "empty": {}
}

// Objects are unordered collections of key/value pairs.
// Keys MUST be unique strings (double-quoted).
// Values can be any JSON type.
03

Строки

Основы строк

Строки JSON — последовательности символов Unicode в двойных кавычках. Прямой слэш можно экранировать (\/), но не обязательно: это полезно при встраивании JSON в теги <script>. Пустые строки допустимы.

json
{
  "name": "Alice",
  "email": "[email protected]",
  "url": "https://example.com/path?q=1",
  "path": "C:\\Users\\alice",
  "empty": ""
}

// Strings are double-quoted Unicode text.
// Forward slash may be escaped as \/ but does not have to be.

Управляющие последовательности

JSON поддерживает такие экранирования: \" (кавычка), \\ (обратная косая), \/ (слэш), \b (забой), \f (перевод страницы), \n (перевод строки), \r (возврат каретки), \t (табуляция) и \uXXXX (кодовая точка Unicode). Любая другая последовательность после обратной косой невалидна.

json
{
  "quote": "She said \"hello\"",
  "backslash": "C:\\Users\\name",
  "newline": "line1\nline2",
  "tab": "col1\tcol2",
  "carriage": "a\rb",
  "backspace": "a\bb",
  "formfeed": "a\fb",
  "slash": "a\/b"
}

// Valid escapes: \" \\ \/ \b \f \n \r \t \uXXXX

Символы Unicode

Используйте \uXXXX для любой кодовой точки Unicode. Символы выше U+FFFF (например, многие эмодзи) требуют суррогатной пары: двух \u-экранирований. Современные парсеры принимают и сырой символ UTF-8 прямо в строке: \uXXXX нужен в основном для надёжности или когда символ нельзя набрать.

json
{
  "eacute": "Caf\u00e9",
  "euro": "Price: \u20ac10",
  "emoji": "Smile \ud83d\ude00",
  "chinese": "\u4f60\u597d",
  "raw": "Cafu00e9 u00e9 \u00e9"
}

// \uXXXX encodes a code point in the Basic Multilingual Plane.
// Surrogate pairs (two \u escapes) encode characters above U+FFFF.
// Modern parsers also accept the raw UTF-8 character directly.

Спецсимволы в строках

Внутри строк JSON двойную кавычку и обратную косую нужно экранировать всегда (\" и \\). Другие спецсимволы (HTML, SQL, regex) следуют своим правилам, но JSON требует экранировать только \" и \\ (плюс управляющие символы). Литеральная обратная косая записывается как \\.

json
{
  "html": "<div class=\"x\">Hi</div>",
  "sql": "SELECT * FROM t WHERE name='O''Brien'",
  "regex": "^\\d{3}-\\d{4}$",
  "json": "{ \"k\": \"v\" }",
  "cmd": "echo \"hello\""
}

// Backslash is the universal escape character.
// To include a literal backslash, write \\.

Многострочные строки (обход)

Строки JSON не могут содержать литеральные переводы строк — их нужно экранировать как \n. Для многострочного содержимого либо вставляйте \n в строку, либо используйте массив строк-строк, либо переходите на формат вроде YAML или JSON5 с поддержкой многострочных строк. Литеральные неэкранированные переводы строк — синтаксическая ошибка.

json
// JSON does NOT support real multi-line strings.
// The following is INVALID:
// { "text": "line1
// line2" }

// Workaround 1: escape the newline
{ "text": "line1\nline2" }

// Workaround 2: array of lines
{ "lines": ["line1", "line2"] }

// Workaround 3: JSON5 allows continued strings (still single logical line)

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

Частые ошибки: одинарные кавычки, завершающие запятые, забытое экранирование внутренних двойных кавычек и вставка литеральных управляющих символов (табуляции, перевода строки) вместо \t/\n. Строгий парсер отклоняет всё это.

json
// WRONG: single quotes
// { 'name': 'Alice' }

// WRONG: trailing comma
// { "a": 1, }

// WRONG: unescaped quote
// { "msg": "He said "hi"" }

// WRONG: literal tab/newline in string
// { "x": "a<TAB>b" }

// RIGHT:
{ "name": "Alice", "msg": "He said \"hi\"" }
04

Числа

Целые и дробные

В JSON один тип числа, покрывающий целые и дробные значения. Отдельного целочисленного типа на уровне синтаксиса нет: привязки языков могут отображать большие целые в int, long, float или decimal в зависимости от значения и библиотеки.

json
{
  "count": 100,
  "negative": -42,
  "temperature": -273.15,
  "pi": 3.14159,
  "zero": 0,
  "negativeZero": -0
}

// Integers and floats use the same number type.
// JSON does not distinguish int from float at the syntax level.

Научная нотация

JSON поддерживает научную нотацию: мантисса, затем e или E и необязательный знаковый показатель (6.022e23 = 6.022 * 10^23). Принимаются и e, и E. Это необходимо для очень больших и очень малых чисел в научных данных.

json
{
  "avogadro": 6.022e23,
  "planck": 6.626e-34,
  "speedOfLight": 2.998e8,
  "small": 1.5E-10
}

// e or E is allowed (case-insensitive).
// 6.022e23 means 6.022 * 10^23.
// The exponent may be negative.

Точность чисел

Числа JSON обычно разбираются как double IEEE 754, поэтому целые выше 2^53-1 (9007199254740991) теряют точность в JavaScript. Десятичные значения вроде 0.1 не представимы точно. Для денег и целых произвольной точности кодируйте их строками и используйте тип Decimal/BigInteger.

json
{
  "big": 9007199254740993,
  "decimal": 0.1,
  "sum": 0.1,
  "money": 19.99
}

// JavaScript stores numbers as IEEE 754 doubles.
// Integers are safe up to 2^53 - 1 (9007199254740991).
// 0.1 + 0.2 === 0.30000000000000004 (float precision loss).

// For money or big integers, parse as string or use a Decimal type.

Специальные значения (не допускаются)

Стандартный JSON не допускает NaN, Infinity и -Infinity. Обходные пути: null для NaN, Infinity строкой или конечное сигнальное значение. Некоторые сериализаторы (json в Python по умолчанию, JSON5) выводят их как расширения, но результат нестандартный и может быть отклонён строгими парсерами.

json
// NaN, Infinity, and -Infinity are NOT valid JSON.

// INVALID:
// { "x": NaN }
// { "y": Infinity }
// { "z": -Infinity }

// Common workarounds:
{
  "x": null,           // represent NaN/null
  "y": "Infinity",     // encode as a string
  "z": 1.7976931348623157e308  // use a finite max
}

// Many serializers (e.g., Python json) accept these as extensions
// but the output is not standard JSON.

Форматы чисел

Допустимые числа JSON: необязательный минус, целая часть (без ведущих нулей, кроме 0), необязательная дробная часть, необязательный показатель. Hex (0x), двоичные (0b), восьмеричные, подчёркивания, ведущий +, ведущие нули и точка без цифр с обеих сторон — всё это невалидно.

json
// VALID JSON numbers:
42
-7
0
3.14
-0.5
6.022e23
1.5E-10
100.00

// INVALID:
007        // leading zero
.5         // no leading digit
5.         // no trailing digit after dot
+5         // leading plus sign
0x1F       // hex
0b101      // binary
1_000      // underscores

Большие числа и BigInt

Для значений выше 2^53-1 (например, snowflake ID Twitter, 64-битные целые, крупные балансы) кодируйте их строками, чтобы избежать потери точности. Если используете reviver в JSON.parse для преобразования в BigInt, помните: BigInt нельзя повторно сериализовать через JSON.stringify без replacer — строки надёжнее при передаче.

json
{
  "snowflake": "1234567890123456789",
  "timestamp": 1696000000000,
  "balance": "99999999999999999999"
}

// Numbers above 2^53-1 lose precision in JS.
// Use STRINGS for IDs, snowflakes, and big integers.

// In JavaScript, parse with a reviver:
// JSON.parse(str, (k, v) =>
//   typeof v === "number" && v > Number.MAX_SAFE_INTEGER
//     ? BigInt(v) : v);  // careful: BigInt can't be in JSON.stringify

// Better: keep them as strings on the wire.
05

Boolean и null

Логические значения

Логические значения JSON — голые ключевые слова true и false. 'true'/'false' в кавычках — строки. В JSON нет понятия truthy/falsy на уровне синтаксиса: 1, 0, yes, no, on, off — это строки или числа, а не boolean. Преобразуйте их в коде приложения.

json
{
  "enabled": true,
  "disabled": false,
  "isPublic": true,
  "isActive": false
}

// Only two boolean values: true and false (lowercase, unquoted).
// "true" (quoted) is a STRING, not a boolean.
// 1/0, yes/no, on/off are NOT booleans.

Смысл null

JSON null сигнализирует намеренное отсутствие значения. Он отличается от отсутствующего ключа (ключа нет в объекте), пустой строки '', 0, false и пустой коллекции. Используйте null, когда поле есть, но без значения; опускайте ключ, когда поле неприменимо.

json
{
  "middleName": null,
  "deletedAt": null,
  "parent": null,
  "optional": null
}

// null means "no value" or "intentionally absent".
// Distinct from:
//   - missing key (key not present at all)
//   - empty string ""
//   - 0 or false
//   - empty array [] or object {}

Null, пусто и отсутствие

Три разных состояния: ключ с пустым значением (""), ключ явно null и отсутствующий ключ. В JavaScript undefined означает отсутствие ключа, а null — наличие ключа без значения. API должны документировать, какое соглашение используют для необязательных полей.

json
{
  "name": "Alice",
  "nickname": "",          // empty string (present, empty)
  "middleName": null,      // explicit null (present, no value)
  // "maidenName"           // missing (key not in object)
}

// In JavaScript:
//   obj.nickname === ""           // true
//   obj.middleName === null       // true
//   obj.maidenName === undefined  // true (key absent)
//   "maidenName" in obj           // false

// Choose deliberately: null vs "" vs missing.

Boolean в условиях

При работе с логическими значениями JSON предпочитайте строгое сравнение (=== true), а не проверку на истинность, если нужно отличать false от отсутствия. В ответах API всегда включайте логические поля, даже когда false: их отсутствие заставляет клиентов угадывать значение по умолчанию.

json
{
  "isAdmin": true,
  "canEdit": false,
  "active": true
}

// In application code (JavaScript):
// if (user.isAdmin) { ... }       // truthy check
// const canEdit = user.canEdit === true;  // strict boolean check

// Be careful: a missing 'canEdit' key is undefined (falsy),
// but explicit false is also falsy. Distinguish if needed.

// API design: always send the boolean, even when false.

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

Частые ошибки: кавычки вокруг true/false/null превращают их в строки; True/TRUE/None (Python) или true/false в неверном регистре невалидны; в JSON нет undefined (только null). Допустимы только ключевые слова true, false и null в нижнем регистре и без кавычек.

json
// Pitfall 1: quoting booleans/null
// { "x": "true" }   -> x is a STRING, not a boolean
// { "y": "null" }   -> y is a STRING, not null

// Pitfall 2: wrong case
// { "x": True }     -> INVALID (Python-style, not JSON)
// { "x": TRUE }     -> INVALID
// { "x": None }     -> INVALID

// Pitfall 3: confusing null with undefined
//   null exists in JSON; undefined does NOT.

// Correct:
{ "x": true, "y": null }
06

Массивы

Основы массивов

Массивы JSON — упорядоченные списки с индексацией с нуля в [ ], значения через запятую. Пустые массивы и массивы из одного элемента допустимы. Порядок значим и сохраняется парсерами. Завершающая запятая не допускается.

json
{
  "numbers": [1, 2, 3, 4, 5],
  "strings": ["a", "b", "c"],
  "booleans": [true, false, true],
  "empty": [],
  "single": [42]
}

// Arrays are ordered, zero-indexed lists in [ ].
// Elements are separated by commas (no trailing comma).
// Empty arrays [] and single-element arrays are valid.

Массивы смешанных типов

Массивы JSON могут легально содержать смешанные типы ([1, 'two', true, null]). Это допустимо, но часто говорит о слабой схеме. Однородные массивы (все строки, все объекты) проще проверять, документировать и потреблять. Используйте схему, чтобы задать типы элементов.

json
{
  "mixed": [1, "two", true, null, 3.14],
  "nested": [[1, 2], "x", { "a": 1 }]
}

// JSON arrays CAN hold values of different types.
// This is valid but often a sign of weak schema design.
// Prefer homogeneous arrays for clarity and validation.

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

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

json
{
  "matrix": [
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9]
  ],
  "ragged": [[1, 2], [3, 4, 5], [6]]
}

// Arrays can nest arbitrarily deep.
// JSON does not enforce rectangular shape—use a schema if needed.

Массив объектов

Массив объектов — самый частый паттерн для списков записей (пользователи, товары, посты). Обычно у каждого элемента одна форма, но JSON это не проверяет: используйте схему (JSON Schema 'items'), чтобы проверить соответствие всех элементов.

json
{
  "users": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" },
    { "id": 3, "name": "Carol" }
  ],
  "empty": []
}

// A very common pattern: a list of records.
// Each element is an object with the same shape.

Пустые массивы и из одного элемента

Пустые массивы [] и массивы из одного элемента допустимы. В дизайне API различайте [] (список есть, он пуст), null (список есть, но его нет) и отсутствующий ключ (поле неприменимо). Возвращать [] для «нет элементов» обычно дружелюбнее, чем null.

json
{
  "empty": [],
  "single": [42],
  "tags": [],
  "items": ["one"]
}

// Both forms are valid.
// Distinguish [] from null and from a missing key:
//   "tags": []      -> present, empty list
//   "tags": null    -> present, no list
//   // (no tags)    -> missing key

Доступ к массиву в коде

После разбора массивы JSON становятся нативными массивами или списками языка (Array в JS, list в Python, List в Java и т. д.). Используйте обычный доступ по индексу, длину и перебор. Границы и типы — ваша ответственность: сам JSON не проверяет типы элементов.

json
{
  "list": ["a", "b", "c"]
}

// JavaScript:
//   const arr = JSON.parse(json).list;
//   arr[0]            // "a"
//   arr.length        // 3
//   arr.includes("b") // true
//   arr.map(x => x.toUpperCase())  // ["A", "B", "C"]

// Python:
//   data = json.loads(json_str)
//   data["list"][0]   # "a"
//   len(data["list"]) # 3
07

Объекты

Основы объектов

Объекты JSON — неупорядоченные наборы пар ключ/значение в { }. Ключи — строки в двойных кавычках; значения — любого типа JSON. Пары разделяются запятыми без завершающей запятой. Объекты — самая частая структура верхнего уровня JSON.

json
{
  "id": 1,
  "name": "Alice",
  "email": "[email protected]",
  "active": true
}

// Objects are unordered { } collections of key/value pairs.
// Keys MUST be double-quoted strings.
// Pairs are comma-separated (no trailing comma).

Правила именования ключей

Ключи JSON могут быть любой строкой в двойных кавычках, включая пустую, с пробелами, точками или цифрами. Однако для ясности API предпочитайте единый camelCase, snake_case или kebab-case. Избегайте пробелов, точек (конфликт с синтаксисом путей) и пустых ключей в публичных API.

json
{
  "simple": "ok",
  "with-dash": "ok",
  "with_underscore": "ok",
  "with.dot": "ok",
  "with space": "ok (but avoid)",
  "123numeric": "ok (but avoid)",
  "": "empty key is valid"
}

// Keys are arbitrary strings (double-quoted).
// Convention: use camelCase, snake_case, or kebab-case consistently.
// Avoid empty keys and keys with spaces/dots in APIs.

Вложенные объекты

Объекты могут вкладываться на любую глубину — полезно для иерархических данных. Глубокая вложенность валидна, но снижает читаемость и повышает связанность. Для публичных API предпочитайте более плоскую структуру или ссылки (ID) вместо глубоких деревьев.

json
{
  "user": {
    "name": "Alice",
    "address": {
      "street": "123 Main St",
      "city": "NYC",
      "geo": { "lat": 40.7, "lng": -74.0 }
    }
  }
}

// Objects can nest arbitrarily deep.
// Deep nesting is valid but can hurt readability—flatten when sensible.

Объект с массивами

Сочетание объектов (для именованных полей) и массивов (для упорядоченных списков) моделирует почти любые реальные данные. Частый паттерн — объект, оборачивающий массивы вложенных объектов (пользователь с заказами). Используйте схему для документирования и проверки формы.

json
{
  "user": {
    "name": "Alice",
    "roles": ["admin", "user"],
    "orders": [
      { "id": 1, "total": 19.99 },
      { "id": 2, "total": 5.99 }
    ]
  }
}

// Combining objects and arrays models most real-world data.

Порядок членов

Спецификация JSON считает объекты неупорядоченными. На практике большинство современных парсеров (V8 в JavaScript, Python 3.7+, LinkedHashMap в Java) сохраняют порядок вставки, но не полагайтесь на это для корректности. Если порядок важен для хеширования или подписи, явно сортируйте ключи.

json
{
  "z": 1,
  "a": 2,
  "m": 3
}

// JSON objects are SPECIFIED as unordered.
// In practice, most parsers (JS, Python 3.7+) preserve insertion order.
// DO NOT rely on order for correctness—sort keys if order matters.

// Sorting keys (e.g., for stable hashing):
//   JSON.stringify(obj, Object.keys(obj).sort())

Дубликаты ключей

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

json
// Technically valid JSON, but behavior is UNDEFINED:
{
  "name": "Alice",
  "name": "Bob"
}

// Most parsers keep the LAST value ("Bob"),
// but some keep the first. Avoid duplicate keys!

// JSON Schema (draft 2019-09+) has 'uniqueKeys' to forbid them.
// JSON.parse in JS keeps the last value (object property override).
08

Вложенные структуры

Глубокая вложенность

JSON допускает произвольную глубину вложенности, но очень глубокие структуры ухудшают читаемость и могут достигать лимитов парсера (многие вводят ограничение, например 1000, для защиты от denial-of-service). Для глубоко иерархических данных предпочитайте плоские структуры с ID и ссылками.

json
{
  "a": {
    "b": {
      "c": {
        "d": {
          "e": { "value": 42 }
        }
      }
    }
  }
}

// Nesting depth is theoretically unlimited.
// Many parsers impose a limit (e.g., 1000) to prevent DoS.
// Deep nesting hurts readability—consider flattening or references.

Реальный пример

Реальный JSON смешивает объекты и массивы, моделируя сущности и их связи. Этот пример заказа вкладывает customer, items (массив объектов) и shipping. Используйте схему для документирования формы и держите вложенность умеренной для читаемости.

json
{
  "order": {
    "id": "ord-123",
    "customer": {
      "id": "cus-1",
      "name": "Alice",
      "email": "[email protected]"
    },
    "items": [
      { "sku": "A1", "qty": 2, "price": 9.99 },
      { "sku": "B2", "qty": 1, "price": 19.99 }
    ],
    "shipping": {
      "address": { "city": "NYC", "zip": "10001" },
      "method": "express"
    },
    "total": 39.97
  }
}

Древовидные структуры

Деревья моделируются рекурсивно: у каждого узла есть значение и массив дочерних узлов. Паттерн встречается в файловых системах, оргструктурах и AST. Следите за циклами: в JSON нет синтаксиса ссылок, поэтому циклические графы нужно представлять ID или плоским списком с указателями на родителя.

json
{
  "name": "root",
  "children": [
    {
      "name": "child-a",
      "children": [
        { "name": "grandchild-1", "children": [] },
        { "name": "grandchild-2", "children": [] }
      ]
    },
    { "name": "child-b", "children": [] }
  ]
}

// Recursive structures: a node contains an array of child nodes.

Доступ к вложенным значениям

Доступ к глубоко вложенным значениям грозит TypeError/KeyError, если промежуточных ключей нет. Используйте optional chaining (JS ?. и ??) или цепочку .get() с умолчаниями (Python). Библиотеки вроде lodash.get или jq упрощают глубокое извлечение и дают значения по умолчанию.

json
{
  "user": { "address": { "city": "NYC" } }
}

// JavaScript (optional chaining):
//   const city = data?.user?.address?.city ?? "unknown";

// Python:
//   city = data.get("user", {}).get("address", {}).get("city", "unknown")

// Deep access without guards throws on missing keys.
// Use optional chaining or a helper like lodash.get.

Разворачивание вложенных данных

Разворачивание вложенных объектов (например, 'user.name' вместо { user: { name } }) упрощает доступ для переменных окружения, полей форм и поисковых индексов. Цена — потеря структуры и сложность обратного преобразования. Используйте библиотеку (flat, lodash) для flatten/unflatten.

json
// Nested form:
{ "user": { "name": "Alice", "city": "NYC" } }

// Flattened form (dot notation):
{ "user.name": "Alice", "user.city": "NYC" }

// Flattened form (separate keys):
{ "userName": "Alice", "userCity": "NYC" }

// Use cases: environment variables, form fields, search indexing.
// Trade-off: simpler access vs. loss of structure.
09

JSON Schema

Основы схемы

JSON Schema — словарь JSON для описания и проверки документов JSON. Корень объявляет $schema (версию черновика) и type. Properties перечисляет поля с их типами; required перечисляет обязательные ключи. Валидаторы вроде Ajv (JS) или jsonschema (Python) проверяют соответствие.

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/user.json",
  "title": "User",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}

Проверка типов

Ключевое слово 'type' проверяет тип значения JSON: string, number, integer, boolean, null, array или object. Оно может быть одним типом или массивом (например, ['string', 'null'] для необязательной nullable-строки). 'integer' совпадает с числами без дробной части.

json
{
  "type": "object",
  "properties": {
    "name":   { "type": "string" },
    "age":    { "type": "integer" },
    "active": { "type": "boolean" },
    "score":  { "type": "number" },
    "tags":   { "type": "array", "items": { "type": "string" } },
    "meta":   { "type": "object" },
    "middle": { "type": ["string", "null"] }
  }
}

// 'type' can be a single type or an array of allowed types.

Ограничения строк

Ограничения строк: minLength, maxLength, pattern (regex), enum (допустимые значения) и format (смысловая подсказка вроде 'email', 'uri', 'date-time', 'ipv4'). 'format' по умолчанию только аннотация: валидаторы должны явно включить его проверку. Для строгой проверки регуляркой используйте pattern.

json
{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 254
    },
    "username": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_]{3,20}$",
      "minLength": 3,
      "maxLength": 20
    },
    "bio": { "type": "string", "maxLength": 500 }
  }
}

// 'format' is a semantic hint (email, uri, date, ipv4).
// 'pattern' is a regular expression.

Ограничения чисел

Ограничения чисел: minimum, maximum (включая границы), exclusiveMinimum, exclusiveMaximum и multipleOf. Для типа 'integer' значения не должны иметь дробной части. Сочетайте ограничения, чтобы задать диапазоны (например, рейтинг от 1 до 5).

json
{
  "type": "object",
  "properties": {
    "age":   { "type": "integer", "minimum": 0, "maximum": 150 },
    "price": { "type": "number", "minimum": 0, "exclusiveMinimum": 0 },
    "rating":{ "type": "integer", "minimum": 1, "maximum": 5 },
    "count": { "type": "integer", "multipleOf": 5 }
  }
}

// minimum/maximum are inclusive;
// exclusiveMinimum/exclusiveMaximum are exclusive.

Ограничения объектов и массивов

Ограничения массивов: items (схема элемента), minItems, maxItems, uniqueItems. Ограничения объектов: required (обязательные ключи), properties (схемы полей), additionalProperties (false запрещает лишние ключи, либо схема для них), minProperties, maxProperties.

json
{
  "type": "object",
  "properties": {
    "id":   { "type": "integer" },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "maxItems": 10,
      "uniqueItems": true
    }
  },
  "required": ["id"],
  "additionalProperties": false
}

// minItems/maxItems/uniqueItems constrain arrays.
// required lists mandatory keys; additionalProperties
// controls whether extra keys are allowed.

Продвинутая валидация

Продвинутый JSON Schema: oneOf/anyOf/allOf объединяют подсхемы; $ref ссылается на переиспользуемые определения; if/then/else применяет условную проверку; const требует точного значения; enum перечисляет допустимые значения. Это позволяет выражать богатые ограничения и переиспользуемые типы.

json
{
  "oneOf": [
    { "type": "string" },
    { "type": "integer" }
  ],
  "definitions": {
    "address": {
      "type": "object",
      "properties": { "city": { "type": "string" } }
    }
  },
  "properties": {
    "home": { "$ref": "#/definitions/address" },
    "work": { "$ref": "#/definitions/address" }
  },
  "if":   { "properties": { "type": { "const": "vip" } } },
  "then": { "required": ["discount"] }
}

// oneOf/anyOf/allOf combine schemas.
// $ref reuses definitions; if/then/else is conditional.
10

JSONPath

Синтаксис JSONPath

JSONPath — язык запросов к JSON, вдохновлённый XPath. '$' — корень, '.' выбирает ребёнка, '[index]' выбирает элемент массива, '*' — подстановочный знак, '..' — рекурсивный спуск. Реализации есть в библиотеках jsonpath-plus (JS) и jsonpath-ng (Python).

json
// JSONPath queries JSON like XPath queries XML.

// Sample data:
{
  "store": {
    "book": [
      { "category": "fiction", "price": 12.99 },
      { "category": "web",     "price": 29.99 }
    ]
  }
}

// Common JSONPath expressions:
$.store.book[0].category      // "fiction"
$.store.book[*].price         // [12.99, 29.99]
$..price                      // all prices anywhere
$.store..category             // all categories under store

Корень и дети

'$' ссылается на корень. '.' выбирает ребёнка по имени; '[]' — скобочная альтернатива для ключей с точками, пробелами и кавычками. '[index]' выбирает элемент массива (с нуля); некоторые реализации поддерживают отрицательные индексы для отсчёта с конца.

json
// '$' = root object/array
// '.' or '[]' = child

$.user.name              // dot notation
$['user']['name']        // bracket notation (use for special chars)
$.users[0]               // first element of users array
$.users[-1]              // last element (some implementations)

// Use bracket notation when keys contain dots, spaces, or quotes:
$['user.name']
$['first name']

Рекурсивный спуск

'..' (рекурсивный спуск) совпадает с ключом или элементом на любой глубине. '$..price' возвращает все значения 'price', где бы они ни находились. '$..*' возвращает каждый узел. Это бесценно для поиска в больших или глубоко вложенных JSON, когда точный путь неизвестен.

json
{
  "a": { "b": { "c": 1 }, "c": 2 }
}

// '..' searches at all depths:
$..c                      // [1, 2] (all 'c' keys anywhere)
$..a                      // all 'a' keys
$..*                      // every node (everything)

// Useful for finding a key without knowing the exact path:
$..price                  // every price, no matter how nested

Выражения фильтра

Фильтры используют [?(выражение)], где '@' означает текущий элемент. Поддерживаемые операторы зависят от реализации, но обычно включают ==, !=, <, <=, >, >=, && (и), || (или), иногда =~ для regex. Функции вроде length() и contains() добавляют возможностей.

json
// Filter with [?(expression)]:

$.store.book[?(@.price < 20)]            // books under 20
$.store.book[?(@.category == 'web')]     // web books
$.store.book[?(@.price < 30 && @.category == 'web')]

// '@' refers to the current item being filtered.
// Operators: == != < <= > >= && || =~ (regex in some impls)
// Functions: length(), contains(), matches()

Подстановочные знаки

'*' — подстановочный знак, совпадающий со всеми детьми объекта или всеми элементами массива. '$.users[*].name' возвращает 'name' каждого пользователя. '$..*' возвращает каждый узел. Результаты возвращаются массивом совпадений, даже если совпадение одно.

json
{
  "users": [
    { "name": "Alice", "age": 30 },
    { "name": "Bob",   "age": 25 }
  ]
}

// '*' matches all elements/children:
$.users[*]               // all user objects
$.users[*].name          // ["Alice", "Bob"]
$.users[0].*             // all values of first user: ["Alice", 30]
$..*                     // every node in the document

// Wildcards return arrays of matches.

Частые функции и примеры

Функции JSONPath зависят от реализации: часто есть length(), min(), max(), avg(), sum(), contains() и matches(). Сочетайте фильтры и рекурсивный спуск для мощных запросов. Для работы в CLI де-факто стандарт — jq с немного другим синтаксисом.

json
// length(): array length or string length
$.users.length()                    // number of users
$.store.book[?(@.title.length() > 10)]

// min(), max(), avg(), sum() (some implementations)
$.store.book..price.min()

// Realistic query: titles of cheap web books
$.store.book[?(@.price < 20 && @.category == 'web')].title

// Tools: jq (CLI), jsonpath-plus (JS), jsonpath-ng (Python),
//        Jayway (Java), GoJSONQ (Go)
11

JSON против XML и YAML

JSON и XML: синтаксис

JSON легче (нет закрывающих тегов, нативные типы для чисел, boolean и null) и напрямую отображается в структуры данных большинства языков. XML тяжелее, но богаче: атрибуты, пространства имён, смешанное содержимое, схемы (XSD) и трансформации (XSLT). JSON доминирует в веб-API; XML сохраняется в enterprise/SOAP.

json
// JSON:
{
  "name": "Alice",
  "age": 30,
  "hobbies": ["reading", "coding"]
}

<!-- XML: -->
<person>
  <name>Alice</name>
  <age>30</age>
  <hobbies>
    <hobby>reading</hobby>
    <hobby>coding</hobby>
  </hobbies>
</person>

// JSON: lighter, no closing tags, types (number/boolean/null).
// XML:  heavier, supports attributes, namespaces, mixed content.

JSON и YAML: синтаксис

YAML использует отступы вместо скобок и кавычек, поддерживает комментарии, многострочные строки и якоря/псевдонимы. JSON строже (кавычки обязательны, комментариев нет), но быстрее и распространённее. YAML — надмножество JSON: каждый валидный JSON-файл также валиден в YAML.

json
# YAML:
name: Alice
age: 30
hobbies:
  - reading
  - coding

// JSON (equivalent):
{
  "name": "Alice",
  "age": 30,
  "hobbies": ["reading", "coding"]
}

// YAML: no quotes/braces, indentation-based, supports comments.
// JSON: stricter, faster to parse, ubiquitous in APIs.

Конвертация JSON в YAML

Конвертировать JSON в YAML просто, так как YAML — надмножество JSON. Справляются yaml.dump в Python и js-yaml в Node. Результат использует отступы и в основном без кавычек. Комментарии и многострочные строки YAML не переносятся из JSON (в JSON их нет).

json
// JSON input:
{ "name": "Alice", "roles": ["admin", "user"] }

// YAML output:
name: Alice
roles:
  - admin
  - user

// Python:
//   import yaml, json
//   yaml.dump(json.loads(json_str), sort_keys=False)

// Node.js:
//   const yaml = require('js-yaml');
//   yaml.dump(JSON.parse(jsonStr));

Конвертация YAML в JSON

Конвертация YAML в JSON работает для простого YAML, но теряет особенности YAML: комментарии, якоря/псевдонимы, многодокументные потоки, теги и сложные ключи. Используйте yaml.safe_load, чтобы избежать выполнения произвольного кода из своих тегов. Результат — стандартный JSON.

json
# YAML input:
server:
  host: localhost
  port: 8080
  debug: true

// JSON output:
{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true
  }
}

// Python:
//   import yaml, json
//   json.dumps(yaml.safe_load(yaml_str), indent=2)

// Watch for YAML-specific features: anchors, tags, multi-docs.

Различия моделирования данных

JSON моделирует данные объектами и массивами — без атрибутов и пространств имён. XML добавляет атрибуты, пространства имён, смешанное содержимое и богатые схемы. YAML добавляет комментарии, якоря и многодокументность. TOML ориентирован на конфиги с таблицами. Выбирайте по потребностям: API (JSON), документы (XML), конфиги (YAML/TOML).

json
// JSON: objects and arrays, no attributes.
//   Attribute-style metadata needs a convention (e.g., @_prefix).

// XML: elements + attributes, namespaces, mixed content.
//   <book id="b1" category="web"><title>...</title></book>

// YAML: maps, sequences, scalars, anchors, multi-doc.
//   Supports comments and multi-line strings natively.

// TOML: tables + key/value, designed for config files.
//   Best for configuration; not ideal for nested data.

Когда какой формат

JSON — для веб-API и NoSQL-хранилищ (универсален, быстр). XML — для корпоративных сервисов, документоцентричных данных (SVG, XHTML) и богатых схем. YAML — для конфигов, написанных человеком (CI/CD, docker-compose), благодаря комментариям и читаемости. TOML — для небольших конфигов. Подбирайте формат под задачу.

json
// Use JSON when:
//   - building web/REST APIs (universal browser support)
//   - storing structured data (NoSQL databases)
//   - configuration with simple needs (package.json)

// Use XML when:
//   - enterprise/SOAP web services
//   - documents with mixed content (SVG, XHTML, DocBook)
//   - you need schemas, namespaces, or XSLT transforms

// Use YAML when:
//   - human-written config (CI/CD, docker-compose)
//   - you need comments and multi-line strings

// Use TOML when:
//   - small config files (Cargo, pyproject)
12

Разбор в JavaScript

JSON.parse

JSON.parse превращает строку JSON в значение JavaScript. Он принимает любое валидное значение JSON (объект, массив, строку, число, boolean, null). Невалидный JSON бросает SyntaxError. Всегда оборачивайте JSON.parse в try/catch при работе с недоверенным вводом.

json
// Parse a JSON string into a JavaScript value.
const json = '{"name":"Alice","age":30}';
const obj = JSON.parse(json);

console.log(obj.name); // "Alice"
console.log(obj.age);  // 30

// JSON.parse accepts a string only.
// Passing a number/boolean/object throws or coerces.
// JSON.parse("42")    === 42       (valid)
// JSON.parse("true")  === true     (valid)
// JSON.parse("null")  === null     (valid)
// JSON.parse(undefined) // throws SyntaxError

JSON.stringify

JSON.stringify превращает значение JavaScript в строку JSON. Функции, Symbol и undefined опускаются (в объектах) или становятся null (в массивах). BigInt бросает TypeError: сначала преобразуйте его в строку. Третий аргумент (space) включает pretty-print.

json
// Serialize a JavaScript value to a JSON string.
const obj = { name: "Alice", age: 30 };
const json = JSON.stringify(obj);
// '{"name":"Alice","age":30}'

// Pretty-print with 2-space indent:
JSON.stringify(obj, null, 2);
// {
//   "name": "Alice",
//   "age": 30
// }

// Functions, Symbols, and undefined are omitted.
// BigInt throws; use a replacer or String() first.

Функция reviver

Reviver в JSON.parse преобразует значения во время разбора. Он вызывается снизу вверх для каждой пары ключ/значение (включая корень с ключом ''). Верните преобразованное значение или undefined, чтобы опустить свойство. Полезно для разбора дат, BigInt и своих типов.

json
// JSON.parse accepts a 'reviver' to transform values.
const json = '{"date":"2024-01-15","count":"42"}';

const obj = JSON.parse(json, (key, value) => {
  if (key === "date") return new Date(value);
  if (key === "count") return Number(value);
  return value;
});

// obj.date is a Date object; obj.count is a number.

// Reviver is called bottom-up for every key, including the root.

Функция replacer

Replacer в JSON.stringify фильтрует или преобразует значения при сериализации. Как функция он вызывается для каждого ключа: верните undefined, чтобы опустить свойство. Как массив он работает белым списком включаемых ключей. Полезно для скрытия секретов и выбора полей.

json
// JSON.stringify accepts a 'replacer' to filter/transform.
const obj = { name: "Alice", password: "secret", age: 30 };

// Replacer as a function:
const safe = JSON.stringify(obj, (key, value) => {
  if (key === "password") return undefined; // omit
  return value;
});
// '{"name":"Alice","age":30}'

// Replacer as an array (allowlist of keys):
JSON.stringify(obj, ["name", "age"]);
// '{"name":"Alice","age":30}'

Pretty-print

Передайте аргумент space в JSON.stringify для pretty-print: число (глубина отступа) или строку (например, '\t'). Для стабильного порядка ключей (нужно для хеширования и подписи) сортируйте ключи перед преобразованием. Сочетайте с replacer для фильтрации полей при pretty-print.

json
const obj = { name: "Alice", age: 30 };

// Compact (default):
JSON.stringify(obj);
// '{"name":"Alice","age":30}'

// 2-space indent:
JSON.stringify(obj, null, 2);

// Tab indent:
JSON.stringify(obj, null, "\t");

// Combine replacer and indent:
JSON.stringify(obj, ["name", "age"], 2);

// To insert a stable key order, sort keys first:
const sorted = Object.keys(obj).sort()
  .reduce((acc, k) => (acc[k] = obj[k], acc), {});
JSON.stringify(sorted, null, 2);

Обработка ошибок

JSON.parse бросает SyntaxError на невалидном вводе — всегда оборачивайте в try/catch для недоверенных данных. Частые причины: завершающие запятые, одинарные кавычки, комментарии или обрезанный ввод. Для очень больших или глубоко вложенных JSON рассмотрите потоковый парсер или ограничение глубины для защиты от denial-of-service.

json
// Always wrap JSON.parse in try/catch for untrusted input.
function safeParse(str) {
  try {
    return { ok: true, value: JSON.parse(str) };
  } catch (e) {
    return { ok: false, error: e.message };
  }
}

// Common errors:
//   SyntaxError: Unexpected token
//   SyntaxError: Unexpected end of JSON input
//   (no undefined/NaN/Infinity accepted)

// For deeply nested untrusted JSON, limit depth to avoid DoS.
// Consider a streaming parser for very large files.
13

Разбор в Python

json.loads

json.loads разбирает строку JSON в объекты Python. Объекты JSON становятся dict, массивы — list, строки — str, числа автоматически int или float, true/false — True/False, null — None. 'loads' означает 'load string'.

json
import json

json_str = '{"name": "Alice", "age": 30}'
data = json.loads(json_str)

print(data["name"])  # Alice
print(data["age"])   # 30

# loads = "load string"
# Returns Python objects: dict, list, str, int/float, bool, None
# JSON true/false/null  ->  Python True/False/None
# JSON numbers          ->  int or float (auto)

json.dumps

json.dumps сериализует объект Python в строку JSON. Используйте indent для pretty-print, ensure_ascii=False, чтобы сохранить символы Unicode (вместо экранирования \uXXXX), и sort_keys=True для стабильного вывода. Python True/False/None отображаются в JSON true/false/null.

json
import json

data = {"name": "Alice", "age": 30, "active": True}

# Compact:
json.dumps(data)
# '{"name": "Alice", "age": 30, "active": true}'

# Pretty-printed:
json.dumps(data, indent=2, ensure_ascii=False)
# {
#   "name": "Alice",
#   "age": 30,
#   "active": true
# }

# ensure_ascii=False keeps Unicode characters readable.
# sort_keys=True produces stable output.

Разбор файлов

Для файлов используйте json.load (объект файла) и json.dump (объект файла); для строк — json.loads и json.dumps. Всегда открывайте файлы с encoding='utf-8', чтобы избежать платформенных умолчаний. Для больших файлов рассмотрите ijson (потоковый) или orjson (быстрее) ради производительности.

json
import json

# Read from a file:
with open("data.json", "r", encoding="utf-8") as f:
    data = json.load(f)

# Write to a file:
with open("out.json", "w", encoding="utf-8") as f:
    json.dump(data, f, indent=2, ensure_ascii=False)

# load/dump work on file objects; loads/dumps work on strings.
# Always specify encoding="utf-8" for portability.

Свои кодировщики

Наследуйтесь от json.JSONEncoder и переопределите default(), чтобы сериализовать типы, не поддерживаемые JSON нативно (datetime, set, Decimal, свои классы). Возвращайте сериализуемое в JSON представление. Для разбора напишите свой hook (object_hook), выполняющий обратное преобразование.

json
import json
from datetime import datetime, date

class CustomEncoder(json.JSONEncoder):
    def default(self, obj):
        if isinstance(obj, (datetime, date)):
            return obj.isoformat()
        if isinstance(obj, set):
            return sorted(obj)
        return super().default(obj)

data = {"now": datetime.now(), "tags": {"a", "b"}}
json.dumps(data, cls=CustomEncoder)
# '{"now": "2024-...", "tags": ["a", "b"]}'

# The default() method is called for objects json can't serialize.

Обработка ошибок

json.loads бросает json.JSONDecodeError на невалидном вводе с информацией о строке и колонке. Частые причины: завершающие запятые, одинарные кавычки, комментарии, NaN/Infinity (по умолчанию отклоняются) и управляющие символы в строках. Используйте parse_constant для обработки NaN/Infinity/-Infinity при необходимости.

json
import json

def safe_loads(s):
    try:
        return {"ok": True, "value": json.loads(s)}
    except json.JSONDecodeError as e:
        return {"ok": False, "error": str(e), "line": e.lineno, "col": e.colno}

# json.JSONDecodeError gives line and column of the error.
# Common causes: trailing commas, single quotes, comments,
#   NaN/Infinity (rejected by default), control chars in strings.

# To allow NaN/Infinity (non-standard):
json.loads('{"x": NaN}', parse_constant=lambda x: None)  # or float(x)

Decimal и DateTime

По умолчанию json разбирает все числа как float, теряя точность десятичных вроде денег. Передайте parse_float=Decimal, чтобы сохранить точность, и сериализуйте через default-hook, преобразующий Decimal обратно (в str для сохранения точности или float, если потери допустимы). Для точных денег используйте str.

json
import json
from decimal import Decimal
from datetime import datetime

# Decimal: parse_float keeps precision (default would lose it)
data = json.loads('{"price": 19.99}', parse_float=Decimal)
print(data["price"])        # Decimal('19.99')
print(data["price"] + Decimal("0.01"))  # 20.00 exact

# Serialize Decimal back:
def encode(obj):
    if isinstance(obj, Decimal):
        return float(obj)   # or str(obj) to keep precision
    raise TypeError

json.dumps({"price": Decimal("19.99")}, default=encode)

# parse_float=float is the default; use Decimal for money.
14

Разбор в Java

Основы Jackson

Jackson — самая популярная JSON-библиотека Java. ObjectMapper.readValue разбирает JSON в POJO; writeValueAsString сериализует их. Добавьте jackson-databind (плюс jackson-core и jackson-annotations) как зависимости. Jackson быстр, зрел и по умолчанию интегрирован в Spring Boot.

json
import com.fasterxml.jackson.databind.ObjectMapper;

ObjectMapper mapper = new ObjectMapper();

// Parse JSON to a Java object:
String json = "{\"name\":\"Alice\",\"age\":30}";
User user = mapper.readValue(json, User.class);

// Serialize a Java object:
String out = mapper.writeValueAsString(user);

// Pretty-print:
String pretty = mapper.writerWithDefaultPrettyPrinter()
                      .writeValueAsString(user);

// Jackson is the de facto JSON library for Java.
// Add: com.fasterxml.jackson.core:jackson-databind

Основы Gson

Gson — JSON-библиотека Google, проще Jackson для базового использования. Gson.fromJson разбирает; toJson сериализует. Используйте GsonBuilder для опций (pretty-print, сериализация null, свои адаптеры). Добавьте com.google.code.gson:gson как зависимость. Gson часто используется в Android.

json
import com.google.gson.Gson;

Gson gson = new Gson();

// Parse:
User user = gson.fromJson(json, User.class);

// Serialize:
String out = gson.toJson(user);

// Pretty-print:
Gson pretty = new GsonBuilder().setPrettyPrinting().create();
String s = pretty.toJson(user);

// Gson (by Google) is simpler than Jackson for basic use.
// Add: com.google.code.gson:gson

Древовидная модель JsonNode

JsonNode в Jackson — древовидная модель для навигации по JSON без POJO. Используйте get() (возвращает null, если ключа нет) или path() (возвращает безопасный «отсутствующий узел» для цепочек). asText/asInt/asBoolean имеют перегрузки со значением по умолчанию. Полезно, когда схема неизвестна или переменна.

json
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

ObjectMapper mapper = new ObjectMapper();
JsonNode root = mapper.readTree(json);

String name = root.get("name").asText();     // "Alice"
int age = root.get("age").asInt();            // 30
JsonNode hobbies = root.get("hobbies");       // array
for (JsonNode h : hobbies) {
    System.out.println(h.asText());
}

// get() returns null for missing keys; path() returns a
// 'missing node' that you can chain safely.
String city = root.path("address").path("city").asText("unknown");

Своя десериализация

Свой JsonDeserializer обрабатывает нестандартные кодировки JSON (например, '$19.99' для денег). Аннотируйте поле через @JsonDeserialize(using = ...) или зарегистрируйте SimpleModule для типа. Для своей сериализации используйте JsonSerializer. Так POJO остаются чистыми от логики разбора.

json
import com.fasterxml.jackson.databind.*;
import com.fasterxml.jackson.core.*;
import java.io.IOException;

public class MoneyDeserializer extends JsonDeserializer<Double> {
    @Override
    public Double deserialize(JsonParser p, DeserializationContext ctxt)
            throws IOException {
        String s = p.getText();           // e.g. "$19.99"
        return Double.parseDouble(s.replaceAll("[^0-9.]", ""));
    }
}

// Annotate the field:
//   @JsonDeserialize(using = MoneyDeserializer.class)
//   public double price;

// Or register a module for a type.

Потоковый API

Потоковый API Jackson (JsonParser/JsonGenerator) читает и пишет JSON токен за токеном с постоянной памятью — идеально для огромных файлов. Вы управляете циклом разбора и можете пропускать поддеревья через skipChildren(). Сочетайте с древовидной или POJO-моделью для нужных вам частей.

json
import com.fasterxml.jackson.core.*;

// Jackson streaming: low memory, fast, for huge files.
JsonFactory f = new JsonFactory();
try (JsonParser p = f.createParser(new File("huge.json"))) {
    while (p.nextToken() != JsonToken.END_OBJECT) {
        String field = p.getCurrentName();
        if ("name".equals(field)) {
            p.nextToken();
            System.out.println(p.getText());
        }
        // skip complex values you don't need:
        // p.skipChildren();
    }
}

// Use streaming for files that won't fit in memory.
15

Разбор в PHP

json_encode

json_encode сериализует значение PHP в JSON. Массивы PHP становятся объектами JSON (ассоциативные) или массивами (последовательные). Частые флаги: JSON_PRETTY_PRINT, JSON_UNESCAPED_UNICODE (читаемый Unicode), JSON_UNESCAPED_SLASHES (не экранировать /). Флаги объединяются оператором |.

json
<?php
$data = ["name" => "Alice", "age" => 30, "active" => true];

// Compact (default):
$json = json_encode($data);
// {"name":"Alice","age":30,"active":true}

// Pretty-print:
$pretty = json_encode($data, JSON_PRETTY_PRINT);

// Keep Unicode readable (don't escape to \uXXXX):
$unicode = json_encode($data, JSON_UNESCAPED_UNICODE);

// Combine flags with |:
json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE
           | JSON_UNESCAPED_SLASHES);

json_decode

json_decode разбирает JSON в PHP. Второй аргумент управляет результатом: true возвращает ассоциативные массивы, false (по умолчанию) — объекты stdClass. Выбирайте по стилю доступа ($arr['key'] против $obj->key). Массивы PHP с не последовательными ключами становятся объектами JSON.

json
<?php
$json = '{"name":"Alice","age":30,"hobbies":["reading"]}';

// Default: returns associative array OR object (stdClass)
$data = json_decode($json);
echo $data->name;            // Alice

// Force associative array:
$arr = json_decode($json, true);
echo $arr["name"];           // Alice

// The second argument (assoc) controls array vs object.
// PHP objects become stdClass instances by default.

Обработка ошибок

json_decode в PHP по умолчанию не бросает исключений: после разбора проверяйте json_last_error() и json_last_error_msg(). Передайте JSON_THROW_ON_ERROR (PHP 7.3+), чтобы он бросал JsonException, — это чище. Частые ошибки: завершающие запятые, одинарные кавычки и невалидный UTF-8.

json
<?php
$json = '{invalid json}';
$data = json_decode($json);

if (json_last_error() !== JSON_ERROR_NONE) {
    echo "Parse error: " . json_last_error_msg();
    // e.g., "Syntax error"
}

// PHP does not throw on JSON errors; check json_last_error().
// Common errors: trailing comma, single quotes, invalid UTF-8.

// To throw exceptions instead:
try {
    $data = json_decode($json, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo $e->getMessage();
}

Pretty-print и флаги

Частые флаги json_encode: JSON_PRETTY_PRINT (отступы), JSON_UNESCAPED_UNICODE (читаемый не-ASCII), JSON_UNESCAPED_SLASHES (не экранировать /), JSON_NUMERIC_CHECK (преобразовывать числовые строки в числа), JSON_THROW_ON_ERROR (бросать при ошибке). Объединяйте через |.

json
<?php
$data = ["path" => "C:\\Users", "url" => "https://x.com/"];

// Default escapes / and non-ASCII:
json_encode($data);
// {"path":"C:\\Users","url":"https:\/\/x.com\/"}

// Cleaner output:
json_encode($data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
           | JSON_PRETTY_PRINT);
// {
//     "path": "C:\\Users",
//     "url": "https://x.com/"
// }

// JSON_NUMERIC_CHECK converts numeric strings to numbers:
json_encode(["id" => "42"], JSON_NUMERIC_CHECK);  // {"id":42}

Своя сериализация

Реализуйте JsonSerializable и определите jsonSerialize(), чтобы управлять кодированием объекта. Это самый чистый способ скрыть поля (например, опустить password), переименовать ключи или вычислить производные значения при сериализации. Метод возвращает любую сериализуемую в JSON структуру.

json
<?php
class User implements JsonSerializable {
    public $name;
    public $password;

    public function __construct($name, $password) {
        $this->name = $name;
        $this->password = $password;
    }

    public function jsonSerialize(): mixed {
        return [
            "name" => $this->name,
            // omit password for security
        ];
    }
}

echo json_encode(new User("Alice", "secret"));
// {"name":"Alice"}

// JsonSerializable lets the class control its JSON form.
16

Спецификация JSON:API

Структура документа

JSON:API — спецификация для построения согласованных JSON-API. Документ имеет объект 'jsonapi' с версией верхнего уровня, основной ресурс 'data', необязательные связанные ресурсы 'included', 'meta' для нестандартной информации, 'links' для пагинации и 'errors' для ошибок. Медиатип — application/vnd.api+json.

json
{
  "jsonapi": { "version": "1.1" },
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API Basics"
    },
    "relationships": {
      "author": { "data": { "type": "people", "id": "9" } }
    }
  },
  "included": [
    { "type": "people", "id": "9", "attributes": { "name": "Jane" } }
  ]
}

// JSON:API is a convention for building JSON APIs.
// Top-level keys: jsonapi, data, errors, meta, links, included.

Объекты ресурсов

Объект ресурса JSON:API имеет 'type' (вид ресурса) и 'id' (строковый идентификатор), а также 'attributes' (данные) и необязательные 'relationships' (связи с другими ресурсами) и 'links' (URL вроде self). ID должны быть строками. type и id не должны появляться в attributes.

json
{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "Hello",
      "published": true,
      "views": 42
    },
    "links": {
      "self": "/articles/1"
    }
  }
}

// Every resource has a 'type' (string) and 'id' (string).
// 'attributes' holds data; 'relationships' holds links to others.
// 'id' and 'type' MUST NOT appear inside attributes.

Связи

Связи соединяют ресурс с другими через объекты идентификаторов ресурсов ({type, id}). Связи to-one используют один идентификатор; to-many — массив. Объект 'links' даёт 'self' (URL связи) и 'related' (URL связанного ресурса) для навигации.

json
{
  "data": {
    "type": "articles",
    "id": "1",
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "9" },
        "links": {
          "self": "/articles/1/relationships/author",
          "related": "/articles/1/author"
        }
      },
      "tags": {
        "data": [
          { "type": "tags", "id": "1" },
          { "type": "tags", "id": "2" }
        ]
      }
    }
  }
}

// to-one: data is a single resource identifier.
// to-many: data is an array of resource identifiers.

Meta и links

'meta' несёт нестандартную информацию: общее число, лимиты, предупреждения. 'links' даёт гипермедиа-навигацию: self, first, prev, next, last для пагинации и связанные URL. Для отсутствующей ссылки (например, prev на первой странице) используйте null.

json
{
  "meta": {
    "totalPages": 5,
    "currentPage": 1,
    "rateLimit": 100
  },
  "links": {
    "self": "/articles?page=1",
    "first": "/articles?page=1",
    "prev": null,
    "next": "/articles?page=2",
    "last": "/articles?page=5"
  },
  "data": [ /* ... */ ]
}

// meta: non-standard metadata (counts, rate limits, etc.).
// links: pagination and resource URLs.

Ошибки

Документы ошибок JSON:API имеют массив 'errors' верхнего уровня (и никакого 'data'). У каждого объекта ошибки необязательные поля: id, status (HTTP-код строкой), code (свой для приложения), title (краткое описание), detail (человеческое объяснение), source (указатель на неверное поле через JSON Pointer) и meta.

json
{
  "errors": [
    {
      "id": "err-123",
      "status": "404",
      "code": "NOT_FOUND",
      "title": "Resource Not Found",
      "detail": "Article 99 does not exist.",
      "source": { "pointer": "/data/attributes/id" },
      "meta": { "requestId": "abc-9" }
    }
  ]
}

// Errors is an array of error objects.
// status: HTTP status string; code: app-specific code.
// source.pointer: JSON Pointer to the offending field.
17

JSON5

Возможности JSON5

JSON5 — надмножество JSON, рассчитанное на конфиги, написанные человеком. Оно добавляет комментарии, строки без кавычек и в одинарных кавычках, завершающие запятые, hex/Infinity/NaN и ослабленные форматы чисел. JSON5 — не стандартный JSON: используйте парсер JSON5 (пакет json5 для npm) и конвертируйте в JSON для обмена.

json
// JSON5 is a superset of JSON with friendlier syntax.
{
  // line comments
  /* block comments */
  unquotedKey: "ok",            // unquoted keys
  "with space": "ok",            // quoted keys still allowed
  singleQuote: 'single',        // single-quoted strings
  trailing: [1, 2, 3,],         // trailing commas
  hex: 0x1F,                     // hexadecimal numbers
  inf: Infinity,                 // Infinity, -Infinity, NaN
  leadingDot: .5,                // leading decimal point
  trailingDot: 5.,               // trailing decimal point
  plus: +5,                      // leading plus
}

// JSON5 is NOT standard JSON—use a JSON5 parser.

Комментарии

JSON5 поддерживает строчные комментарии // и блочные /* */, которые стандартный JSON запрещает. Поэтому JSON5 идеален для конфигов, написанных человеком. settings.json в VS Code и tsconfig.json в TypeScript используют JSONC (JSON с комментариями) — похожее, но немного другое подмножество.

json
{
  // Single-line comment (like JS)
  "name": "Alice",

  /* Block comment
     spanning multiple lines */
  "age": 30,

  "active": true // end-of-line comment
}

// Standard JSON rejects comments.
// JSON5 supports // and /* */ comments everywhere.
// VS Code's settings.json and tsconfig.json use JSONC (a subset).

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

JSON5 допускает завершающие запятые после последнего элемента объектов и массивов. Стандартный JSON их отклоняет. Завершающие запятые уменьшают шум в диффах при добавлении и переупорядочивании полей (каждая строка может заканчиваться запятой). Многие современные языки и форматы конфигов это уже допускают.

json
{
  "a": 1,
  "b": 2,
  "c": 3,           // <-- trailing comma OK in JSON5
}

// Arrays too:
[1, 2, 3,]

// Standard JSON rejects trailing commas.
// JSON5 allows them, reducing diff noise when adding fields.

Строки без кавычек и в одинарных

JSON5 допускает ключи-идентификаторы без кавычек (по шаблону [A-Za-z_$][A-Za-z0-9_$]*) и строки как в одинарных, так и в двойных кавычках. Внутри одинарной строки экранируйте ' как \'; внутри двойной — " как \". Это повторяет синтаксис литералов объектов JavaScript ради читаемости.

json
{
  unquoted: "value",          // unquoted identifier key
  "quoted key": "value",       // quoted key (for special chars)
  single: 'single-quoted',     // single-quoted string value
  mixed: 'it\'s ok',           // escape single quote inside
  double: "she said \"hi\"",  // escape double quote inside
}

// Unquoted keys must be valid identifiers ([A-Za-z_$][A-Za-z0-9_$]*).
// Single and double quotes are both allowed for strings.

Числа и строки (расширенно)

JSON5 расширяет числа: шестнадцатеричные (0xFF), точка в начале или конце (.5, 5.), ведущий плюс (+5) и ключевые слова Infinity, -Infinity, NaN. Всё это стандартный JSON отклоняет. Строки JSON5 по-прежнему используют экранирования (\n) для переводов строк — «голых» многострочных строк нет.

json
{
  hex: 0xFF,                    // hexadecimal
  leadingDot: .5,               // .5 instead of 0.5
  trailingDot: 5.,              // 5. instead of 5.0
  leadingPlus: +5,              // +5 (standard JSON rejects +)
  infinity: Infinity,           // Infinity (not in standard JSON)
  negativeInfinity: -Infinity,
  nan: NaN,
  multiline: 'line1\nline2'    // escape sequences like JSON
}

// JSON5 does NOT support real multi-line strings or bareword NaN.
18

JSON Lines (JSONL)

Формат JSONL

JSON Lines (JSONL или NDJSON) — формат, где каждая строка является отдельным полным значением JSON. Внешнего массива нет. Это идеально для потоков, логов и больших наборов данных: можно обрабатывать построчно, не загружая файл целиком. Расширения: .jsonl, .ndjson.

json
// A JSON Lines file (.jsonl / .ndjson) is one JSON value per line:

{"name": "Alice", "age": 30}
{"name": "Bob", "age": 25}
{"name": "Carol", "age": 35}

// Rules:
//   - Each line is a COMPLETE, valid JSON value.
//   - Lines are separated by newlines (\n).
//   - No enclosing [ ] array.
//   - Each line is parsed independently.

Чтение JSONL

Читайте JSONL, перебирая строки и разбирая каждую через JSON.parse/loads. Так файл обрабатывается потоково с постоянной памятью — идеально для огромных данных. Пропускайте пустые строки. В Node.js используйте readline поверх файлового потока; в Python перебирайте объект файла напрямую. Загружать весь файл не нужно.

json
// JavaScript (Node.js) — line by line:
const fs = require("fs");
const readline = require("readline");

const rl = readline.createInterface({
  input: fs.createReadStream("data.jsonl"),
  crlfDelay: Infinity,
});

for await (const line of rl) {
  if (!line.trim()) continue;
  const obj = JSON.parse(line);
  console.log(obj.name);
}

// Python:
//   import json
//   with open("data.jsonl") as f:
//       for line in f:
//           obj = json.loads(line)

Запись JSONL

Пишите JSONL, сериализуя каждую запись через JSON.stringify/dumps (компактно, без отступов) и добавляя перевод строки. Для эффективности используйте поток записи (Node) или откройте файл в режиме записи (Python). Компактная форма держит строки короткими и разбираемыми; правило — одна запись на строку.

json
// JavaScript (Node.js):
const fs = require("fs");
const out = fs.createWriteStream("out.jsonl");
for (const obj of records) {
  out.write(JSON.stringify(obj) + "\n");
}
out.end();

// Python:
//   import json
//   with open("out.jsonl", "w") as f:
//       for obj in records:
//           f.write(json.dumps(obj) + "\n")

// One JSON per line; compact form (no indent) is conventional.

Сценарии использования

JSONL отлично подходит для лог-файлов, больших наборов данных, данных обучения ML, дампов баз и потоков событий только с добавлением. Каждая строка независима: можно дописывать без перезаписи, продолжать разбор после повреждённой строки и обрабатывать параллельно. Инструменты вроде jq и shell-конвейеры работают с ним естественно.

json
// JSONL is ideal for:
//   - log files (one event per line)
//   - large datasets (streaming, append-only)
//   - machine learning training data
//   - database exports/imports
//   - append-only event streams

// Example: log entry per line
{"ts": "2024-01-15T10:00:00Z", "level": "info", "msg": "started"}
{"ts": "2024-01-15T10:00:01Z", "level": "error", "msg": "failed"}

// Tools: jq, xargs, awk | json.loads — all work line-by-line.

JSONL против массива JSON

Массив JSON оборачивает записи в [ ] и требует загрузки (или осторожного потокового разбора) всего файла. JSONL кладёт одну запись на строку, обеспечивая настоящую потоковость, лёгкое дописывание и восстановление после повреждённых строк. Для больших или растущих наборов данных JSONL почти всегда лучший выбор.

json
// JSON Array (one big file):
[
  {"name": "Alice"},
  {"name": "Bob"},
  {"name": "Carol"}
]

// JSONL (one per line):
{"name": "Alice"}
{"name": "Bob"}
{"name": "Carol"}

// JSON Array: must load whole file to parse; hard to append.
// JSONL: streamable, appendable, resumable; slightly more
//        per-record overhead but far better for big files.
19

Безопасность

Риски JSONP

JSONP оборачивает JSON в JavaScript-колбэк, чтобы тег <script> мог получить межсайтовые данные в обход same-origin policy. Это опасно: любой сайт может прочитать ответ, инъекция колбэка включает XSS, а запросы несут cookie жертвы. Используйте CORS: JSONP устарел и небезопасен.

json
// JSONP (JSON with Padding) bypasses same-origin policy
// by wrapping JSON in a script callback:
callbackHandler({"secret": "data"});

// Loaded via <script src="https://api.example.com/data?callback=callbackHandler">

// RISKS:
//   - Any site can include the URL and read the response.
//   - XSS if the callback name is attacker-controlled.
//   - CSRF: the request is made with the victim's cookies.

// MODERN ALTERNATIVE: use CORS instead of JSONP.
// JSONP is legacy—avoid it for new APIs.

Защита от XSS

JSON, встроенный в HTML-теги <script>, может вызвать XSS: строка '</script>' завершает скрипт раньше времени. Кроме того, U+2028 и U+2029 (разделители строк и абзацев) валидны в строках JSON, но ломают JavaScript. Экранируйте <, >, &, U+2028, U+2029 при встраивании JSON в HTML или используйте библиотеку вроде serialize-javascript.

json
// JSON itself is data, not executable—BUT embedding it in
// HTML can cause XSS if not careful.

// BAD: output JSON inside <script> without escaping:
//   <script>
//     var data = {"name": "</script><script>alert(1)</script>"};
//   </script>

// GOOD: escape < and > (and &) when embedding in HTML:
const safe = JSON.stringify(data)
  .replace(/</g, "\\u003c")
  .replace(/>/g, "\\u003e")
  .replace(/&/g, "\\u0026")
  .replace(/\u2028/g, "\\u2028")
  .replace(/\u2029/g, "\\u2029");

// Or use a library: js-xss, serialize-javascript.

Загрязнение прототипа

Загрязнение прототипа (prototype pollution) происходит, когда недоверенный JSON с ключами вроде '__proto__' или 'constructor' сливается в объекты, отравляя Object.prototype и влияя на все объекты. Защита: Object.create(null), блокировка опасных ключей, Map для недоверенных данных, обновление библиотек слияния.

json
// Merging untrusted JSON into objects can pollute prototypes:
const evil = JSON.parse('{"__proto__": {"isAdmin": true}}');

// BAD merge (Object.assign does NOT pollute, but some libs do):
//   function merge(target, src) {
//     for (const k in src) target[k] = src[k];
//   }

// Attackers can set Object.prototype.isAdmin = true,
// affecting ALL objects.

// Defenses:
//   - Use Object.create(null) for parsed objects.
//   - Block keys like __proto__, constructor, prototype.
//   - Use Map instead of plain objects for untrusted data.
//   - Keep dependencies updated (some had merge() flaws).

Инъекции через JSON

Сам JSON устойчив к инъекциям, но сборка его конкатенацией строк опасна: пользовательский ввод может выйти за пределы структуры JSON. Всегда используйте настоящий сериализатор (JSON.stringify). То же ниже по стеку: параметризованные SQL-запросы, execFile с массивами аргументов и шаблонизаторы с экранированием HTML.

json
// JSON itself is not injectable, but building JSON by
// concatenation is dangerous:

// BAD: string concatenation
//   const json = '{"name": "' + userInput + '"}';
//   // userInput = '"); drop table; //'  ->  breaks out

// GOOD: always use a real serializer
const json = JSON.stringify({ name: userInput });

// For SQL: use parameterized queries, not JSON interpolation.
// For shell: use execFile with arg arrays, not string concat.
// For HTML: use textContent or a templating engine that escapes.

DoS через большой или глубокий JSON

DoS через JSON: огромные файлы исчерпывают RAM, глубокая вложенность переполняет стек парсера, а патологические структуры (аналог «billion laughs» для JSON) раздувают малый ввод. Защита: ограничить размер тела на прокси, ограничить глубину разбора, использовать потоковые парсеры для больших входов и задавать таймауты.

json
// Attackers can craft JSON to exhaust memory or CPU:
//
//   1. Huge file: 1 GB of '[1,1,1,...]' to exhaust RAM.
//   2. Deep nesting: '{"a":{"a":{"a":...}}}' (10000 levels)
//      to overflow the parser's stack.
//   3. 'Billion laughs': nested entity expansion (XML-era,
//      but JSON analogs exist with $ref in some libs).
//   4. Many keys: 10 million keys in one object.

// Defenses:
//   - Cap request body size at the server/reverse proxy.
//   - Limit parsing depth (Ajv, fast-json-parse options).
//   - Use streaming parsers (stream-json, oboe) for big input.
//   - Set timeouts on parsing.

Безопасный разбор

Безопасный разбор JSON: всегда используйте JSON.parse (никогда eval), проверяйте по схеме (Ajv, jsonschema) перед использованием, ограничивайте глубину и число ключей, блокируйте ключи __proto__ и рассмотрите разбор недоверенного ввода в Web Worker или песочнице. JSON.parse сам по себе безопасен от выполнения кода; риски — в том, как вы используете разобранные данные.

json
// 1. Validate with a schema before using untrusted JSON.
const Ajv = require("ajv");
const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(schema);
if (!validate(data)) throw new Error(ajv.errorsText(validate.errors));

// 2. Limit depth and key count when parsing.
// 3. Use reviver/replacer to coerce types safely.
// 4. Never eval() or Function('return ' + json) — use JSON.parse.
// 5. Disable dangerous features (e.g., __proto__ keys).
// 6. Parse untrusted JSON in a sandbox or worker if possible.

// JSON.parse is safe; eval is NOT.
20

Лучшие практики и инструменты

Schema-first

Проектируйте API в подходе schema-first: опишите JSON Schema, сгенерируйте типы языка из неё (typescript-json-schema, quicktype, jsonschema2pojo) и проверяйте запросы и ответы во время работы. Это рано ловит нарушения контракта, даёт генерацию кода и служит живой документацией.

json
// Define a JSON Schema before shipping an API.
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "name"],
  "properties": {
    "id":   { "type": "integer" },
    "name": { "type": "string", "minLength": 1, "maxLength": 100 }
  },
  "additionalProperties": false
}

// Generate types from the schema (TypeScript, Java, Go, ...).
// Validate both requests and responses against the schema.
// Publish the schema for clients (OpenAPI, JSON Schema).

Единый стиль имён

Выберите одно соглашение именования ключей и применяйте его последовательно: camelCase (большинство JSON-API и JS), snake_case (Python/Ruby-бэкенды, Google API) или PascalCase (.NET). Смешение стилей путает. Если фронтенд и бэкенд различаются, конвертируйте на одной границе, а не смешивайте в схеме.

json
// Pick ONE naming convention and apply it everywhere.

// camelCase (most JSON APIs, JavaScript ecosystem):
{ "firstName": "Alice", "lastName": "Smith" }

// snake_case (Python/Ruby backends, many Google APIs):
{ "first_name": "Alice", "last_name": "Smith" }

// kebab-case (rare in JSON, common in URLs/config):
{ "first-name": "Alice" }

// PascalCase (rare in JSON keys, common in C#/.NET types):
{ "FirstName": "Alice" }

// Avoid mixing; convert at the boundary if the front/back differ.

Версионирование

Версионируйте API с первого дня: в пути URL (/v1/), полем версии в payload, заголовком Accept (медиатип) или пространством имён (JSON-LD @context). Аддитивные изменения (новые необязательные поля) обычно не ломают клиентов; повышайте версию при удалении и переименовании полей или изменении семантики.

json
// 1. Version in the URL path:
//    https://api.example.com/v1/users

// 2. Version field in the payload:
{ "version": "1.0", "data": { ... } }

// 3. Accept header / media type:
//    Accept: application/vnd.example.v1+json

// 4. Namespace the JSON (JSON-LD, JSON:API 'type'):
{ "@context": "https://schema.org/v1", ... }

// Plan for evolution: add optional fields freely, but bump
// the version for breaking changes (removed/renamed fields,
// changed semantics or types).

Кодировка (UTF-8)

UTF-8 — кодировка по умолчанию и единственная широко рекомендуемая для JSON. Сохраняйте файлы в UTF-8 без BOM (некоторые парсеры его неверно обрабатывают), задавайте Content-Type с charset=utf-8 и Content-Length в байтах. В Python передавайте ensure_ascii=False, чтобы символы Unicode оставались читаемыми вместо \uXXXX.

json
// Always use UTF-8 for JSON.
//   - Save files as UTF-8 (no BOM).
//   - Set Content-Type: application/json; charset=utf-8.
//   - Set Content-Length in bytes (not characters).

// In Node.js:
res.setHeader("Content-Type", "application/json; charset=utf-8");
res.end(JSON.stringify(data));

// In Python:
import json
with open("out.json", "w", encoding="utf-8") as f:
    json.dump(data, f, ensure_ascii=False)

// ensure_ascii=False keeps Unicode readable in the file.

Советы по производительности

Для производительности: передавайте большие JSON потоком (ijson, stream-json, потоковый Jackson) вместо буферизации; используйте быстрые сериализаторы (orjson, fast-json-stringify); передавайте компактно и сжимайте gzip/brotli по HTTP; избегайте глубокой вложенности и огромных массивов; кешируйте разобранные результаты, чтобы не разбирать повторно.

json
// 1. Stream large JSON instead of buffering it all.
//    - Node: stream-json, JSONStream
//    - Python: ijson
//    - Java: Jackson streaming API

// 2. Use a fast serializer:
//    - Node: fast-json-stringify (schema-based), orjson (Python)
//    - Compile serializers from a schema for hot paths.

// 3. Compact JSON for transmission; pretty only for humans.

// 4. Avoid deep nesting and huge arrays when possible.

// 5. Compress with gzip/brotli over HTTP (huge savings).

// 6. Cache parsed results; don't re-parse the same payload.

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

Инструменты для JSON: онлайн-валидаторы (jsonlint.com, jsonschemavalidator.net), CLI (jq для запросов и форматирования, jsonschema для проверки), поддержка в редакторах (VS Code и JetBrains имеют встроенную проверку JSON и схем) и генераторы кода (quicktype создаёт типы TypeScript/Java/Go и др. из JSON или схемы).

json
// Online validators:
//   - https://jsonlint.com
//   - https://jsonformatter.org
//   - https://www.jsonschemavalidator.net

// CLI tools:
//   - jq          (filter, query, format JSON on the command line)
//   - jaq         (Rust jq clone, faster)
//   - jsonschema  (Python CLI for schema validation)
//   - ajv         (Node CLI/library for JSON Schema)

// Editor support:
//   - VS Code: built-in JSON + schema validation
//   - JetBrains: built-in JSON + schema support
//   - vim/emacs: plugins available

// Schema tools:
//   - quicktype   (generate types from JSON)
//   - typescript-json-schema
//   - jsonschema2pojo (Java)

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.