Claude JSON: структурированный вывод и проверка схемы

Claude может вернуть JSON в чате, Claude Code или API, но надёжность и назначение этих режимов различаются. Для ручного черновика достаточно чата. Для скрипта в терминале нужен машинный формат Claude Code. Для программного контракта используйте Structured Outputs в API с JSON Schema. В любом варианте отдельно проверяйте синтаксис, схему и смысл данных.

Карта результата

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

• Чат подходит для ручной работы и прототипа.
• Claude Code подходит для командной строки и автоматизации в репозитории.
• API Structured Outputs подходит для контракта между сервисами.
• JSON Schema описывает форму, но не подтверждает фактическую верность.
• Любые команды, пути, URL и действия из ответа требуют отдельной проверки.
• Сырой ответ сохраняется только без секретов и персональных данных.

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

Чем различаются чат, Claude Code и API

В обычном чате можно попросить вернуть только JSON и дать пример. Это ускоряет черновик, но интерфейс чата не является договором для вашей программы: ответ нужно скопировать и проверить локальным парсером. Не стройте интеграцию на удалении Markdown-ограждений регулярным выражением.

В Claude Code флаг --output-format json возвращает результат команды в JSON-обёртке, а --json-schema задаёт схему структурированного результата. Оба режима описаны в официальной справке CLI и руководстве по программному запуску Claude Code. Это удобный путь для локального скрипта или шага CI, если среда уже авторизована.

В API Anthropic Structured Outputs схема передаётся через output_config.format с типом json_schema. Текущая документация Structured Outputs описывает соответствие вывода поддерживаемой схеме, но перечисляет ограничения поддерживаемого подмножества JSON Schema. Перед внедрением проверьте свою схему на выбранной модели.

Составьте минимальную JSON Schema

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

{
  "type": "object",
  "properties": {
    "summary": {"type": "string"},
    "risk": {"type": "string", "enum": ["low", "medium", "high"]},
    "needs_review": {"type": "boolean"}
  },
  "required": ["summary", "risk", "needs_review"],
  "additionalProperties": false
}

Безопасный пример описывает форму короткого отчёта. Он не определяет, как вычисляется риск. Это намеренное разделение: модель выбирает значение, схема проверяет допустимый вариант, а ваше приложение решает, можно ли доверять выбору и что с ним делать.

По теме: Claude для вайбкодинга: проект по шагам в 2026

Получите JSON в Claude Code

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

claude -p "Суммируй входной текст и оцени, нужна ли ручная проверка" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"summary":{"type":"string"},"risk":{"type":"string","enum":["low","medium","high"]},"needs_review":{"type":"boolean"}},"required":["summary","risk","needs_review"],"additionalProperties":false}'

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

Используйте Structured Outputs в API

В API передайте ту же схему в output_config.format. Укажите поддерживаемый идентификатор модели из актуальной документации, а не копируйте случайное имя из старого примера. Ниже показан каркас, в котором секрет берётся из окружения библиотекой, а не записывается в код.

from anthropic import Anthropic

client = Anthropic()
schema = {
    "type": "object",
    "properties": {
        "summary": {"type": "string"},
        "risk": {"type": "string", "enum": ["low", "medium", "high"]},
        "needs_review": {"type": "boolean"},
    },
    "required": ["summary", "risk", "needs_review"],
    "additionalProperties": False,
}

response = client.messages.create(
    model="YOUR_SUPPORTED_MODEL_ID",
    max_tokens=1000,
    messages=[{"role": "user", "content": "Верни структурированный отчёт"}],
    output_config={"format": {"type": "json_schema", "schema": schema}},
)

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

Трёхступенчатая проверка

Практический элемент 1, обязательный шлюз. Этап 1 проверяет транспорт и синтаксис: команда завершилась успешно, ответ не пустой, JSON разбирается стандартным парсером. Этап 2 проверяет структуру: объект соответствует вашей JSON Schema, нет лишних ключей, обязательные поля присутствуют. Этап 3 проверяет смысл: значения допустимы для конкретной задачи и не запускают опасное действие без подтверждения.

1. Проверьте код ответа HTTP или код завершения процесса.
2. Ограничьте размер входа до разбора.
3. Разберите JSON стандартной библиотекой без выполнения содержимого.
4. Провалидируйте объект той же схемой на своей стороне.
5. Проверьте диапазоны, существование идентификаторов и разрешённые переходы состояний.
6. Маршрутизируйте сомнительные результаты на ручную проверку.
7. Запишите причину отказа без входных секретов.

Пример смысловой проверки: поле risk входит в перечисление, но модель могла выбрать low для текста с явной угрозой. Схема пропустит объект, потому что форма верна. Бизнес-правило должно сверить критические признаки или потребовать человека для решений с последствиями.

По теме: Claude Context: как управлять чатом, Projects и Claude Code

Диагностика частых сбоев

• Парсер видит текст до фигурной скобки: вы используете обычный чат или текстовый режим вместо штатного структурированного вывода.
• Схема отклоняется до запроса: упростите её и проверьте ограничения поддерживаемого подмножества.
• Ответ обрезан: уменьшите объём полей, входной контекст или пересмотрите лимит вывода.
• CLI возвращает JSON, но скрипт не находит поле: зафиксируйте реальную обёртку тестом для установленной версии.
• Схема проходит, а данные неверны: проблема на третьем этапе, добавьте бизнес-правило или ручную проверку.
• Повторный запрос меняет ключи: запретите лишние свойства и сделайте обязательные поля явными.

Практический элемент 2, набор контрактных тестов. Храните минимум четыре фикстуры: обычный ответ, пустая строка, лишний ключ и значение на границе. Запускайте их после обновления SDK, CLI, модели или схемы. Такой тест ловит несовместимость раньше, чем рабочие данные попадут в следующий процесс.

Безопасность и ограничения

Не считайте JSON безопасным кодом. Строка может содержать путь, команду, SQL, HTML или URL. Применяйте списки разрешённых действий, нормализацию путей, параметризованные запросы и подтверждение для внешних изменений. Строгий режим инструментов Anthropic помогает проверять входы инструментов; его границы описаны в официальной документации strict tool use.

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

Если вы начинаете автоматизацию, сначала разберите что такое Claude CLI. Для интеграции сервиса полезно сравнить Claude Tools и API, а формулировку задачи проверить по материалу промпты для Claude.

По теме: Claude VS Code: как установить и проверить расширение в 2026

Чек-лист перед подключением

• Канал выбран по тому, кто читает результат: человек или программа.
• Схема минимальна и проходит официальный поддерживаемый режим.
• Лишние свойства запрещены, обязательные поля перечислены.
• Ответ разбирается и валидируется вашей библиотекой.
• Смысловые ограничения проверяются отдельно от схемы.
• Опасные действия требуют подтверждения.
• Есть контрактные тесты и журнал причин отказа.

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

Достаточно ли написать в промпте «верни только JSON»?

Для ручного черновика иногда достаточно. Для автоматизации используйте штатный структурированный режим и всё равно проверяйте ответ своим парсером.

Гарантирует ли JSON Schema правильные факты?

Нет. Схема проверяет структуру и ограничения значений, но не подтверждает истинность содержания.

Что выбрать для локального скрипта?

Если Claude Code уже установлен и авторизован, начните с печатного режима, --output-format json и --json-schema. Для отдельного сервиса обычно удобнее API.