Начало работы
Базовая структура
JSON поддерживает 6 типов данных: строка, число, логическое значение, null, массив и объект. Ключи должны быть строками в двойных кавычках. 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, если они нужны.
{
"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.
// 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'.
// 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 не рекомендуется.
// 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 — одно значение: обычно объект или массив, но и голое число или строка тоже допустимы.
// 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.Типы данных
Тип строка
Строки JSON — текст Unicode в двойных кавычках. Частые экранирования: \" (кавычка), \\ (обратная косая), \/ (слэш), \n, \t, \r, \b, \f и \uXXXX для любого символа Unicode. Одинарные кавычки как разделители строк не допускаются.
{
"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 или строки.
{
"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 как логических: преобразуйте их в коде приложения.
{
"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.
{
"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, включая смешанные типы и вложенные массивы и объекты. Пустые массивы [] допустимы. Порядок сохраняется и значим.
{
"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. Хотя объекты концептуально неупорядочены, большинство парсеров сохраняет порядок вставки; не полагайтесь на порядок для корректности.
{
"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.Строки
Основы строк
Строки JSON — последовательности символов Unicode в двойных кавычках. Прямой слэш можно экранировать (\/), но не обязательно: это полезно при встраивании JSON в теги <script>. Пустые строки допустимы.
{
"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). Любая другая последовательность после обратной косой невалидна.
{
"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 нужен в основном для надёжности или когда символ нельзя набрать.
{
"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 требует экранировать только \" и \\ (плюс управляющие символы). Литеральная обратная косая записывается как \\.
{
"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 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. Строгий парсер отклоняет всё это.
// 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\"" }Числа
Целые и дробные
В JSON один тип числа, покрывающий целые и дробные значения. Отдельного целочисленного типа на уровне синтаксиса нет: привязки языков могут отображать большие целые в int, long, float или decimal в зависимости от значения и библиотеки.
{
"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. Это необходимо для очень больших и очень малых чисел в научных данных.
{
"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.
{
"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) выводят их как расширения, но результат нестандартный и может быть отклонён строгими парсерами.
// 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), восьмеричные, подчёркивания, ведущий +, ведущие нули и точка без цифр с обеих сторон — всё это невалидно.
// 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 — строки надёжнее при передаче.
{
"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.Boolean и null
Логические значения
Логические значения JSON — голые ключевые слова true и false. 'true'/'false' в кавычках — строки. В JSON нет понятия truthy/falsy на уровне синтаксиса: 1, 0, yes, no, on, off — это строки или числа, а не boolean. Преобразуйте и х в коде приложения.
{
"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, когда поле есть, но без значения; опускайте ключ, когда поле неприменимо.
{
"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 должны документировать, какое соглашение используют для необязательных полей.
{
"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: их отсутствие заставляет клиентов угадывать значение по умолчанию.
{
"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 в нижнем регистре и без кавычек.
// 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 }Массивы
Основы массивов
Массивы 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]). Это допустимо, но часто говорит о слабой схеме. Однородные массивы (все строки, все объекты) проще проверять, документировать и потреблять. Используйте схему, чтобы задать типы элементов.
{
"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 не требует, чтобы вложенные массивы имели одинаковую длину (неровный массив валиден). Если нужна прямоугольная матрица, обеспечьте это схемой или кодом приложения.
{
"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'), чтобы проверить соответствие всех элементов.
{
"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.
{
"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 не проверяет типы элементов.
{
"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Объекты
Основы объектов
Объекты 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.
{
"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) вместо глубоких деревьев.
{
"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.Объект с массивами
Сочетание объектов (для именованных полей) и массивов (для упорядоченных списков) моделирует почти любые реальные данные. Частый паттерн — объект, оборачивающий массивы вложенных объектов (пользователь с заказами). Используйте схему для документирования и проверки формы.
{
"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) сохраняют порядок вставки, но не полагайтесь на это для корректности. Если порядок важен для хеширования или подписи, явно сортируйте ключи.
{
"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; линтеры и строгие парсеры могут их отклонять.
// 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).Вложенные структуры
Глубокая вложенность
JSON допускает произвольную глубину вложенности, но очень глубокие структуры ухудшают читаемость и могут достигать лимитов парсера (многие вводят ограничение, например 1000, для защиты от denial-of-service). Для глубоко иерархических данных предпочитайте плоские структуры с ID и ссылками.
{
"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. Используйте схему для документирования формы и держите вложенность умеренной для читаемости.
{
"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 или плоским списком с указателями на родителя.
{
"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 упрощают глубокое извлечение и дают значения по умолчанию.
{
"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.
// 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.JSON Schema
Основы схемы
JSON Schema — словарь JSON для описания и проверки документов JSON. Корень объявляет $schema (версию черновика) и type. Properties перечисляет поля с их типами; required перечисляет обязательные ключи. Валидаторы вроде Ajv (JS) или jsonschema (Python) проверяют соответствие.
{
"$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' совпадает с числами без дробной части.
{
"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.
{
"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).
{
"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.
{
"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 перечисляет допустимые значения. Это позволяет выражать богатые ограничения и переиспользуемые типы.
{
"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.JSONPath
Синтаксис JSONPath
JSONPath — язык запросов к JSON, вдохновлённый XPath. '$' — корень, '.' выбирает ребёнка, '[index]' выбирает элемент массива, '*' — подстановочный знак, '..' — рекурсивный спуск. Реализации есть в библиотеках jsonpath-plus (JS) и jsonpath-ng (Python).