JSON: что это простыми словами и зачем он в приложении

Ты попросил Claude Code добавить рекорды в «Змейку», а он создал package.json, записал что-то в localStorage и упомянул JSON.parse. Эти слова выглядят как детали для программиста, но за ними стоит простая идея: приложению нужен понятный способ складывать данные и передавать их между разными частями. Разобравшись с JSON один раз, ты будешь увереннее читать код, находить ошибки и ставить ИИ точные задачи.

Что такое JSON простыми словами

JSON — это текстовый формат для хранения и передачи данных. Аббревиатура расшифровывается как JavaScript Object Notation, то есть «объектная запись JavaScript». Название связано с JavaScript, но сам формат используют почти все современные языки программирования и самые разные приложения.

Проще всего сравнить JSON с анкетой. В анкете есть поля и заполненные значения:

• имя — Vasya;
• рекорд — 120;
• звук включён — да.

В JSON та же информация записывается по правилу «ключ — значение»:

{
  "name": "Vasya",
  "score": 120,
  "soundEnabled": true
}

Ключ описывает, что хранится в поле: name, score, soundEnabled. Значение содержит сами данные: имя игрока, число очков, состояние звука. Двоеточие отделяет ключ от значения, а запятые разделяют поля.

JSON остаётся обычным текстом. Его можно открыть, прочитать, скопировать, отправить по сети или сохранить в файл. При этом строгие правила позволяют программе разобрать текст обратно на отдельные значения. Человек видит запись о Васе и его рекорде, а приложение получает объект, у которого можно запросить имя или количество очков.

Формат не выполняет команды и сам ничего не вычисляет. Строка "score": 120 только сообщает значение. JSON не решает, побил ли игрок рекорд, не рисует таблицу лидеров и не отправляет результат на сервер. Эту работу делает код, а JSON служит упаковкой для данных.

Как выглядит JSON: объект, массив и простые значения

JSON строится всего из нескольких типов значений. Их достаточно, чтобы описать профиль пользователя, настройки игры, список товаров, ответ сервера или содержимое формы.

Объект

Объект — набор пар «ключ — значение» внутри фигурных скобок. Вот короткая запись рекорда «Змейки»:

{"name": "Vasya", "score": 120}

Пробелы и переносы строк не меняют смысл, поэтому тот же объект можно оформить удобнее для чтения:

{
  "name": "Vasya",
  "score": 120
}

Ключи объекта всегда строки и всегда заключаются в двойные кавычки. Значения могут иметь разные типы.

Массив

Массив — упорядоченный список значений внутри квадратных скобок. Например, таблица рекордов содержит несколько объектов:

[
  {
    "name": "Vasya",
    "score": 120
  },
  {
    "name": "Lena",
    "score": 95
  },
  {
    "name": "Oleg",
    "score": 80
  }
]

Порядок элементов имеет значение. Первый результат находится на позиции 0, второй — на позиции 1. Такой счёт с нуля принят в JavaScript и многих других языках.

Строка

Строка — текст в двойных кавычках:

"Vasya"

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

"Игрок \"Vasya\""

Число

Число записывается без кавычек:

120

Дробная часть отделяется точкой, а не запятой:

12.5

Если написать "120", получится не число, а строка из трёх символов. На экране они выглядят похоже, но код обращается с ними по-разному. Например, число можно корректно складывать с другим числом, а строки JavaScript при некоторых операциях склеивает.

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

Значения true и false отвечают на вопрос «да или нет». Кавычки вокруг них не ставятся:

{
  "soundEnabled": true,
  "darkTheme": false
}

true удобно читать как «включено», а false — как «выключено». Строка "false" не равна логическому значению false: это просто текст из пяти букв.

Значение null

null означает, что значения сейчас нет. Например, игрок ещё не выбрал скин:

{
  "selectedSkin": null
}

Это не то же самое, что пустая строка "", число 0 или отсутствие самого поля. Пустая строка говорит: «поле есть, в нём текст нулевой длины». null говорит: «поле есть, но значение не задано».

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

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

{
  "player": {
    "name": "Vasya",
    "settings": {
      "soundEnabled": true,
      "speed": "normal"
    }
  },
  "scores": [120, 90, 75],
  "selectedSkin": null
}

Здесь объект settings вложен в player, а рядом расположен массив scores. Отступы помогают увидеть уровни и парные скобки.

Где новичок встречает JSON каждый день

Даже если ты никогда не создавал .json вручную, он уже окружает твой проект. Иногда файл виден в папке, иногда JSON незаметно передаётся по сети или лежит в хранилище браузера.

Ответы API

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

{
  "player": "Vasya",
  "score": 120,
  "position": 3
}

Браузер получает текст, превращает его в объект и показывает данные в интерфейсе. Подробнее сам принцип разобран в материале «Что такое API».

Файл package.json

В проектах на Node.js часто есть package.json. Он описывает проект: его имя, команды запуска и используемые пакеты. Упрощённый пример:

{
  "name": "snake-game",
  "private": true,
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}

Когда Claude Code устанавливает библиотеку или добавляет команду, он может изменить этот файл. Удалять незнакомые поля наугад не стоит: от них зависит установка и запуск проекта.

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

Настройки редактора

VS Code хранит многие настройки в файлах, похожих на JSON. Там могут быть размер шрифта, форматирование при сохранении и параметры отдельных расширений:

{
  "editor.fontSize": 16,
  "editor.formatOnSave": true
}

У VS Code встречается JSON with Comments, или JSONC, — расширенный вариант с комментариями. Это исключение конкретного инструмента, а не новое правило обычного JSON. Если скопировать настройку с комментарием в строгий .json или отправить её в API, разбор может завершиться ошибкой.

Файлы конфигурации

Конфигурация — набор настроек, по которым программа понимает, как ей работать. В JSON могут храниться адрес сервера, выбранная тема, доступные уровни или параметры сборки. Пример локальной конфигурации игры:

{
  "boardSize": 20,
  "initialSpeed": 140,
  "wallsEnabled": false
}

JSON удобен тем, что один и тот же файл читают человек, JavaScript, серверный код и вспомогательные инструменты.

localStorage

localStorage — встроенное хранилище браузера. Оно сохраняет данные для конкретного сайта между перезагрузками страницы. Но хранить умеет только строки. Если передать туда объект напрямую, данные не сохранятся в нужном виде. Поэтому объект сначала превращают в JSON-текст, а после чтения разбирают обратно.

Так «Змейка» запоминает рекорд, выбранный скин или настройки звука. Подробности и ограничения такого хранения собраны в статье «Как работает localStorage».

Сетевые и служебные данные

JSON можно увидеть в инструментах разработчика браузера, журналах работы приложения, экспортированных настройках и ответах вебхуков. Вебхук — автоматическое сообщение от одного сервиса другому после события, например после отправки формы. Тело такого сообщения часто приходит в JSON. Связь событий, запросов и данных подробнее показана в материале «Вебхук: что это и как работает».

Файл JSON: что это и чем открыть

Файл .json — обычный текстовый файл, содержимое которого записано по правилам JSON. Расширение после точки помогает операционной системе и редактору понять, какой это формат. Оно не превращает файл в программу и не делает его опасным само по себе.

Если поисковый запрос звучит как «JSON — что это, чем открыть», короткий ответ такой: подойдёт любой текстовый редактор. На Windows файл можно прочитать в Блокноте, на macOS — в текстовом редакторе в режиме обычного текста. Но для работы с проектом удобнее VS Code.

VS Code даёт несколько полезных подсказок:

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

Чтобы посмотреть содержимое, не нужны Excel, база данных или специальная платная программа. Достаточно установленного текстового редактора.

Большой JSON бывает неудобен для человека: одна строка растягивается на тысячи символов, а вложенные объекты теряются. Форматирование, которое иногда называют pretty print, добавляет переносы и отступы, не меняя данные. Минифицированная и отформатированная записи равнозначны:

{"name":"Vasya","score":120}

{
  "name": "Vasya",
  "score": 120
}

Почему в JSON нет комментариев

Стандартный JSON не поддерживает комментарии. Нельзя добавить пояснение через // или временно «закомментировать» поле:

{
  // Лучший результат игрока
  "score": 120
}

Для обычного парсера это неверный JSON. Строгость нужна для совместимости: отправитель и получатель должны одинаково понимать каждый символ, не договариваясь о дополнительных правилах.

Если пояснение нужно хранить вместе с данными, можно добавить обычное поле:

{
  "description": "Лучший результат игрока",
  "score": 120
}

Но такое поле становится частью данных. Приложение должно быть готово его принять или проигнорировать. Для внутренних конфигураций некоторые проекты выбирают JSONC, YAML или JavaScript-файл, где комментарии разрешены. Нельзя молча считать эти форматы обычным JSON: сначала проверь, что конкретный инструмент их поддерживает.

JSON в JavaScript: JSON.stringify и JSON.parse

В JavaScript есть встроенный объект JSON с двумя основными методами. JSON.stringify превращает значение JavaScript в JSON-текст. JSON.parse выполняет обратную операцию: читает JSON-текст и создаёт значение JavaScript.

Как сохранить рекорд через JSON.stringify

Допустим, в игре есть объект с именем игрока и количеством очков:

const record = {
  name: "Vasya",
  score: 120
};

Пока страница работает, этот объект находится в памяти. После закрытия вкладки он исчезнет. Чтобы записать его в localStorage, объект превращают в строку:

const record = {
  name: "Vasya",
  score: 120
};

const recordJson = JSON.stringify(record);
localStorage.setItem("snakeRecord", recordJson);

После JSON.stringify(record) переменная recordJson содержит строку:

{"name":"Vasya","score":120}

Можно записать короче, не создавая промежуточную переменную:

localStorage.setItem("snakeRecord", JSON.stringify(record));

stringify можно перевести как «превратить в строку». Он сам расставляет нужные двойные кавычки и запятые, поэтому собирать JSON вручную из кусочков текста обычно не нужно.

Как прочитать рекорд через JSON.parse

При следующем запуске игра получает строку из хранилища и разбирает её:

const savedRecord = localStorage.getItem("snakeRecord");
const record = JSON.parse(savedRecord);

console.log(record.name);
console.log(record.score);

После JSON.parse переменная record снова содержит объект. Теперь код может сравнить record.score с новым результатом.

Но у примера есть слабое место. Если ключ snakeRecord ещё не существует, localStorage.getItem вернёт null. Кроме того, старые или повреждённые данные могут оказаться неверным JSON. Безопаснее сначала проверить наличие строки, а ошибку разбора обработать:

const savedRecord = localStorage.getItem("snakeRecord");
let record = null;

if (savedRecord !== null) {
  try {
    record = JSON.parse(savedRecord);
  } catch (error) {
    console.error("Не удалось прочитать рекорд", error);
  }
}

try просит JavaScript попробовать выполнить опасный участок, а catch описывает, что делать при ошибке. Игра не обязана падать из-за одной испорченной записи: она может удалить некорректное значение, создать рекорд заново или показать понятное сообщение.

Что меняется при преобразовании

Не каждое значение JavaScript имеет прямое представление в JSON. В JSON нет функций, undefined, специальных объектов Date, а также отдельных типов для бесконечности и NaN. Поэтому преобразование иногда теряет информацию.

Например, дата после JSON.stringify обычно становится строкой. После JSON.parse она остаётся строкой, а не возвращается автоматически к объекту Date. Функции и поля со значением undefined в объекте могут исчезнуть. Для обычных рекордов, настроек и ответов API это не мешает, но ИИ должен учитывать ограничение при проектировании данных.

Если код написан на TypeScript, тип может описать ожидаемую форму объекта, но сам по себе не проверит данные, пришедшие с сервера во время работы. Разницу между подсказкой для разработчика и реальной проверкой полезно понимать отдельно; она разобрана в статье «TypeScript для новичка».

JSON parse: что это и почему возникает Unexpected token

JSON.parse — команда JavaScript, которая пытается разобрать строку как JSON. Если строка соответствует правилам, получается объект, массив или простое значение. Если встречается недопустимый символ, выполнение прерывается с ошибкой SyntaxError.

Сообщение Unexpected token переводится как «неожиданный символ» или «неожиданная часть записи». Парсер шёл по тексту и ожидал, например, ключ в двойных кавычках или закрывающую скобку, но увидел что-то другое. В разных версиях среды формулировка и указание позиции могут различаться, однако смысл один: переданный текст не удалось прочитать как JSON.

JSON parse error — это не отдельный вид файла и не проблема самого метода. Это сообщение о несовпадении ожиданий с реальными данными. Причину нужно искать в исходной строке и в месте, откуда она пришла.

Сервер вернул HTML вместо JSON

Одна из самых частых причин — приложение ожидало данные API, а получило HTML-страницу. Например, адрес запроса неверный, сервер показал страницу ошибки или перенаправил на форму входа. HTML часто начинается с <, поэтому сообщение может упоминать неожиданный символ <.

Проблема не исправляется заменой кавычек в JavaScript. Сначала нужно проверить сам ответ:

• какой адрес был запрошен;
• какой статус вернул сервер;
• что указано в заголовке Content-Type;
• какой текст находится в теле ответа;
• не произошёл ли переход на другую страницу.

Перед разбором ответа полезно убедиться, что запрос успешен:

const response = await fetch("/api/scores");

if (!response.ok) {
  throw new Error(`Сервер вернул статус ${response.status}`);
}

const data = await response.json();

Метод response.json() тоже разбирает JSON и тоже выдаст ошибку, если тело ответа оказалось другим текстом. Проверка response.ok отделяет сетевую или серверную проблему от дальнейшей работы с данными, хотя успешный статус сам по себе ещё не гарантирует правильный JSON.

В JSON стоит лишняя запятая

После последнего поля объекта или последнего элемента массива запятая запрещена:

{
  "name": "Vasya",
  "score": 120,
}

Нужно убрать последнюю запятую:

{
  "name": "Vasya",
  "score": 120
}

JavaScript в некоторых местах допускает хвостовые запятые, поэтому глаз привыкает считать их нормальными. JSON строже.

Использованы одинарные кавычки

Такой объект может быть допустимой записью внутри JavaScript, но это не JSON:

{'name': 'Vasya', 'score': 120}

Правильная JSON-запись использует двойные кавычки:

{"name": "Vasya", "score": 120}

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

Как быстро найти причину JSON parse error

Двигайся от фактов, а не меняй символы наугад:

1. Найди строку, которую получает JSON.parse. Временно выведи её перед разбором или посмотри ответ во вкладке Network инструментов разработчика.
2. Проверь первые символы. < часто указывает на HTML, пустая строка — на отсутствие тела ответа, обычный текст — на неверный формат ответа.
3. Посмотри позицию ошибки, если она указана. Счёт символов может быть неудобен, поэтому вставь данные в редактор с нумерацией строк и форматированием.
4. Проверь двойные кавычки, хвостовые запятые, ключи без кавычек и незакрытые скобки.
5. Уточни источник. Если неверные данные пришли с сервера, исправлять нужно ответ сервера или обработку ошибки, а не случайный символ в клиентском коде.
6. После исправления повтори запрос и убедись, что приложение разбирает именно новый ответ, а не старое значение из кэша или localStorage.

Не публикуй в онлайн-валидаторе токены доступа, пароли, персональные данные и полные ответы закрытого API. Для чувствительных данных используй локальную проверку.

Правила синтаксиса JSON, на которых спотыкаются

JSON короткий, но строгий. Большинство ошибок связано с несколькими правилами.

Ключи только в двойных кавычках

Неверно:

{
  name: "Vasya"
}

Верно:

{
  "name": "Vasya"
}

В объекте JavaScript кавычки вокруг простого ключа иногда можно опустить. В JSON — нельзя.

Строки только в двойных кавычках

Неверно:

{
  "name": 'Vasya'
}

Верно:

{
  "name": "Vasya"
}

Одинарная кавычка внутри обычного текста не мешает. Запрет касается ограничителей строки.

После последнего элемента нет запятой

Неверно:

[
  120,
  95,
]

Верно:

[
  120,
  95
]

То же правило действует для последнего поля объекта.

Скобки должны закрываться попарно

Объект начинается { и заканчивается }. Массив начинается [ и заканчивается ]. Вложенные структуры закрываются в обратном порядке:

{
  "player": {
    "name": "Vasya"
  },
  "scores": [120, 95]
}

Если редактор выделяет парную скобку, поставь курсор рядом с каждой открывающей скобкой и проверь, где находится соответствующая закрывающая.

Между ключом и значением нужно двоеточие

Неверно:

{
  "score" = 120
}

Верно:

{
  "score": 120
}

Знак равенства используется в коде для присваивания, но внутри JSON между ключом и значением стоит двоеточие.

Значения true, false и null пишутся без кавычек

{
  "soundEnabled": true,
  "gameOver": false,
  "selectedSkin": null
}

Слова пишутся строчными буквами. True, FALSE и None к JSON не относятся. Варианты в кавычках синтаксически допустимы, но будут строками, а не логическими или пустыми значениями.

В JSON нет undefined, функций и вычислений

Неверно:

{
  "nickname": undefined,
  "nextScore": 120 + 10
}

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

Переносы строк внутри текста экранируются

Нельзя физически разорвать строковое значение переносом. Для обозначения новой строки используют специальную последовательность \n:

{
  "message": "Первая строка\nВторая строка"
}

Обратная косая черта также помогает записать кавычку \" и саму обратную косую черту \\. Ручное экранирование быстро становится неудобным, поэтому JSON-текст лучше получать через JSON.stringify.

JSON и API: как приложение обменивается данными с сервером

Браузер и сервер работают отдельно. «Змейка» запущена у игрока, а общая таблица рекордов хранится на сервере. Чтобы договориться, обе стороны используют одинаково понятный формат данных — часто JSON.

Когда игрок заканчивает партию, приложение может отправить объект с именем и результатом:

{
  "name": "Vasya",
  "score": 120
}

В HTTP-запросе код сообщает, что тело записано как JSON, и превращает объект в строку:

const record = {
  name: "Vasya",
  score: 120
};

const response = await fetch("/api/scores", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify(record)
});

Заголовок Content-Type: application/json похож на надпись на упаковке: он сообщает получателю, в каком формате лежит содержимое. Сервер разбирает текст, проверяет поля и сохраняет результат. В ответ он тоже может вернуть JSON:

{
  "success": true,
  "position": 3
}

Клиент читает ответ:

if (!response.ok) {
  throw new Error(`Ошибка сервера: ${response.status}`);
}

const result = await response.json();
console.log(result.position);

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

Хороший контракт API отвечает на вопросы:

• какие поля обязательны;
• какого типа должно быть каждое значение;
• может ли значение быть null;
• что вернётся при успехе;
• как выглядит ответ с ошибкой;
• какие поля могут добавиться позже.

Если сервер вернул {"error":"Name is required"}, это корректный JSON, хотя операция завершилась неудачей. Синтаксическая корректность и смысловой успех — разные вещи. Точно так же {"score":"много"} может быть правильным JSON, но неправильными данными для таблицы, где score должен быть числом.

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

JSON против CSV, XML и YAML: когда какой формат использовать

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

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

Как проверить JSON на ошибки

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

Проверка в VS Code

Открой .json в VS Code и посмотри на подчёркивания и сообщения редактора. Если файл определён именно как JSON, редактор обычно сразу замечает лишнюю запятую, неверные кавычки или незакрытую скобку.

Отформатируй документ стандартной командой форматирования редактора. Если форматирование не выполняется, сначала исправь синтаксис. После успешного форматирования просмотри уровни вложенности: объект settings должен находиться у нужного игрока, а массив scores — закрываться в ожидаемом месте.

Онлайн-валидаторы

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

Не вставляй во внешний сервис:

• токены и ключи API;
• пароли и данные сессии;
• персональные данные пользователей;
• закрытые адреса и внутренние настройки;
• полный ответ рабочего сервера, если не уверен в его содержимом.

Для учебного объекта с Васей и 120 очками онлайн-проверка подходит. Для закрытых данных используй редактор или локальную команду.

Локальная проверка через Node.js

Если Node.js уже установлен, небольшую строку можно проверить в терминале командой node -e. Внешний сервис не нужен:

node -e 'JSON.parse("{\"name\":\"Vasya\",\"score\":120}"); console.log("JSON корректен")'

При корректном вводе команда напечатает:

JSON корректен

Если JSON неверный, Node.js завершит выполнение и покажет ошибку разбора. В разных терминалах Windows, macOS и Linux правила кавычек отличаются, поэтому длинный документ удобнее проверять из файла:

node -e 'JSON.parse(require("fs").readFileSync("data.json", "utf8")); console.log("JSON корректен")'

Команду запускают из папки, где находится data.json, либо указывают правильный путь. Она читает файл как текст и передаёт содержимое в JSON.parse. Для проекта с неизвестными скриптами такая проверка безопаснее запуска самого файла: JSON рассматривается как данные, а не как программа.

Проверка структуры данных

После синтаксиса проверь ожидания приложения. Для рекорда можно явно убедиться, что имя — непустая строка, а очки — конечное неотрицательное число:

function isValidRecord(value) {
  return (
    typeof value === "object" &&
    value !== null &&
    typeof value.name === "string" &&
    value.name.trim() !== "" &&
    typeof value.score === "number" &&
    Number.isFinite(value.score) &&
    value.score >= 0
  );
}

Эта функция не проверяет JSON-текст. Она проверяет уже разобранное значение. Правильная последовательность такая: получить строку, выполнить JSON.parse, затем проверить форму и допустимые значения.

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

Как просить ИИ работать с JSON-данными и что проверять

Фраза «сделай работу с JSON» слишком широкая. Claude Code придётся самому решить, откуда берутся данные, какие поля нужны и что делать при ошибке. Чем точнее задача, тем легче проверить результат без глубокого знания кода.

Хороший запрос содержит пять частей:

1. Источник данных: localStorage, файл, форма, API или вебхук.
2. Ожидаемую структуру: названия полей, их типы и пример.
3. Действие: сохранить, прочитать, изменить, отобразить или отправить.
4. Поведение при ошибке: запасное значение, сообщение пользователю или повторный запрос.
5. Ограничения: какие файлы менять, какие функции сохранить, нужны ли тесты.

Например:

Добавь в браузерную «Змейку» сохранение лучшего результата в localStorage под ключом snakeRecord.

Структура данных:
{
  "name": "Vasya",
  "score": 120
}

При сохранении используй JSON.stringify, при чтении — JSON.parse. Если ключа нет или JSON повреждён, игра должна запуститься без ошибки и считать, что рекорда пока нет. Не меняй правила движения змейки. Добавь проверку, что name — непустая строка, а score — неотрицательное конечное число. После изменений перечисли затронутые файлы и покажи, как вручную проверить три случая: корректная запись, отсутствующая запись, повреждённый JSON.

Такой запрос сообщает ИИ не только желаемую функцию, но и границы. Ты заранее определяешь, какое поведение считать правильным.

Проси показать пример входа и выхода

Если речь об API, приложи ожидаемый JSON или попроси ИИ сначала предложить контракт без изменения кода:

Сначала предложи JSON-структуру запроса и успешного ответа для сохранения рекорда. Для каждого поля укажи тип, обязательность и допустимость null. Код пока не меняй.

После согласования структуры можно поручать реализацию. Это уменьшает риск, что клиент отправляет playerName, а сервер ждёт name, или одна сторона считает score числом, а другая — строкой.

Проси обрабатывать плохие данные

ИИ часто хорошо реализует счастливый путь: сервер вернул ожидаемый объект, хранилище не повреждено, все поля на месте. Реальное приложение встречает пустые ответы, старые версии данных и ручное вмешательство пользователя.

Полезное дополнение к запросу:

Не доверяй данным после JSON.parse. Проверь структуру до использования. Обработай пустой ответ, синтаксически неверный JSON, отсутствие обязательного поля и неверный тип score. Для пользователя покажи понятное сообщение без технического стека ошибки, а подробность оставь в console.error.

Проверяй не красоту кода, а наблюдаемое поведение

После ответа ИИ пройди короткий чек-лист:

• объект перед записью превращается через JSON.stringify, а после чтения — через JSON.parse;
• отсутствующий ключ localStorage не ломает загрузку страницы;
• повреждённая строка обрабатывается через try...catch;
• код не склеивает JSON вручную из пользовательского ввода;
• после разбора проверяются типы обязательных полей;
• секреты и токены не записываются в клиентский JSON и localStorage;
• сообщение пользователю понятно без знания JavaScript;
• старые данные либо поддерживаются, либо безопасно сбрасываются;
• тесты и ручная проверка охватывают не только успешный случай.

Открой инструменты разработчика и посмотри фактическое значение в localStorage или ответ во вкладке Network. Сравни его с согласованным примером. Если ИИ утверждает, что всё работает, но не показывает результат проверки, попроси точные команды, входные данные и фактический вывод.

Не проси «починить Unexpected token» без исходных данных

Одно и то же сообщение появляется из-за HTML от сервера, хвостовой запятой, одинарных кавычек, обрезанного ответа и других причин. Передай ИИ:

• полный текст ошибки без секретов;
• участок кода с JSON.parse или response.json();
• первые безопасные символы исходного ответа;
• статус и Content-Type ответа;
• ожидаемый пример JSON;
• шаги, после которых возникает сбой.

Если ответ содержит секреты или персональные данные, замени значения нейтральными, сохранив скобки, кавычки и типы. Не удаляй символ около указанной позиции ошибки: именно он может быть причиной.

Проси минимальное изменение

Формулировка «исправь разбор JSON, не меняй формат API и соседние функции» защищает от ненужной переделки. После изменения попроси ИИ объяснить простыми словами:

• где данные становятся строкой;
• где строка превращается в объект;
• где проверяется структура;
• что увидит пользователь при ошибке.

Ты не обязан запоминать весь синтаксис, чтобы принять работу. Достаточно понимать путь данных и проверять заявленные случаи.

Короткий чек-лист перед работой с JSON

Перед сохранением файла, отправкой запроса или принятием правки от ИИ проверь:

• корневое значение — объект, массив или другое допустимое JSON-значение;
• ключи и строки заключены в двойные кавычки;
• после последнего поля и элемента нет запятой;
• все фигурные и квадратные скобки закрыты;
• логические значения и null написаны строчными буквами без кавычек;
• в данных нет undefined, функций, вычислений и комментариев;
• объект для localStorage прошёл через JSON.stringify;
• строка из localStorage разбирается через JSON.parse внутри безопасной обработки ошибки;
• после разбора проверяются обязательные поля и их типы;
• в JSON не попали ключи API, пароли и другие секреты.

JSON несложно читать: фигурные скобки обозначают объект, квадратные — список, а пары «ключ — значение» работают как поля анкеты. Основная трудность не в количестве правил, а в их строгости. Двойные кавычки, отсутствие хвостовой запятой и проверка данных после JSON.parse закрывают большую часть типичных проблем новичка.

Частые вопросы

JSON — это язык программирования?

Нет. JSON хранит и передаёт данные, но не содержит команд, условий или циклов. Код на JavaScript, Python или другом языке читает JSON и решает, что делать с полученными значениями.

Можно ли открыть файл JSON без специальной программы?

Да. Это обычный текст, поэтому подойдёт любой текстовый редактор. Для проекта удобнее VS Code: он подсвечивает структуру, показывает синтаксические ошибки и помогает форматировать документ.

Чем JSON отличается от объекта JavaScript?

JSON — строка по строгим правилам, а объект JavaScript — структура в памяти работающей программы. JSON.stringify превращает объект в JSON-текст, а JSON.parse превращает корректный JSON-текст обратно в значение JavaScript.

Что означает JSON parse error: Unexpected token?

Парсер встретил символ, которого не ожидал по правилам JSON. Частые причины — HTML вместо ответа API, одинарные кавычки, лишняя запятая или незакрытая скобка. Сначала посмотри исходную строку и позицию ошибки.

Почему нельзя писать комментарии в JSON?

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

Безопасно ли хранить данные в JSON и localStorage?

Для рекорда, темы или настроек — обычно да, если потеря или изменение этих данных не критичны. Пароли, токены и секретные ключи хранить там нельзя: пользователь и код страницы могут прочитать localStorage, а сам JSON ничего не шифрует.