Symfony анонсировал JsonSchema: что это меняет для API
Анонсированный Symfony JsonSchema помогает получать описание JSON из PHP-типов, но не заменяет проектирование API. Сначала разделите входные и выходные поля, затем проверьте сгенерированную схему и серверные правила. Тип данных не отвечает сам по себе на вопрос, вправе ли пользователь изменить конкретный объект.
Анонс компонента не равен выпуску всего Symfony 8.2
20 октября 2026 года Symfony представил JsonSchema. На странице версии 8.2 при подготовке материала стоит Under development и ожидаемый выпуск в ноябре 2026. Поэтому здесь речь об анонсе и проверке нового компонента, а не о состоявшемся стабильном выпуске всего фреймворка.
В анонсе генератор связывается с PHP-типами, метаданными сериализации и ограничениями валидации. Это полезно для согласования документации с кодом. Но источник определения и фактическое выполнение HTTP-запроса остаются разными частями приложения.
Одной модели объекта недостаточно для двух направлений
В учебном API заявок клиент передаёт описание задачи, а сервер возвращает назначенный идентификатор и состояние обработки. Внутренняя заметка сотрудника вообще не должна появляться в публичном ответе. Это собственный пример контракта, не структура из официального блога.
Если просто взять любой внутренний класс и назвать полученную схему публичным контрактом, в ней могут оказаться лишние поля или неверное направление. Определите, что принимает конкретная операция и что она возвращает. В анонсе для этого описаны группы и направление Input/Output, а также выбор диалекта схемы.
| Слой учебного API | Что определяет | Что проверять | Чего слой сам не доказывает |
|---|---|---|---|
| PHP-тип внутренней модели | Представление объекта в коде | Какие свойства и метаданные используются | Право публиковать каждое свойство |
| Вход операции | Разрешённые поля запроса | Нет серверного состояния и внутренних заметок во входе | Пользователь имеет доступ к нужной заявке |
| Выход операции | Публичный результат | Идентификатор и состояние соответствуют принятому контракту | Запрос действительно выполнен в бизнес-процессе |
| Сгенерированная схема | Структурное описание выбранного направления | Поля, ограничения и диалект совпадают с ожиданием | Сервер уже применяет все проверки |
| Бизнес-обработка | Допустимость конкретного действия | Права, существование объекта и разрешённый переход | Описание схемы автоматически осталось актуальным |
Генерацию нужно сравнить с реальным обменом
Возьмите разрешённые учебные запрос и ответ для одной операции. Сопоставьте их со схемой именно этого направления и контекста сериализации. Ошибка в имени или составе поля проявится раньше, чем при передаче документации внешней команде.
Отдельно определите поведение при недопустимом значении и неизвестном поле. Не выводите его из одной красивой схемы: приложение должно действительно следовать согласованным правилам. Проверка генератора не заменяет проверки обработчика запроса.
При изменении публичного контракта сохраняйте прежний вариант для сравнения и объясняйте потребителям, что изменилось. Автоматически пересобранная документация может стать точнее кода, но это ещё не делает изменение совместимым с уже работающей интеграцией.
Требования компонента и фреймворка различаются
В composer.json ветки компонента указано PHP 8.2 или выше и зависимости, допускающие определённые версии компонентов 7.4 и 8.x. При этом страница полного Symfony 8.2 требует PHP 8.4.0+. Одно требование нельзя автоматически подставлять вместо другого.
Это не обещание установки пакета в любой старый проект. Перед решением проверяют доступную версию пакета, ограничения зависимостей и собственный lock-файл. Исходник ветки подтверждает заявленные требования, но сам по себе не является успешным разрешением зависимостей вашего приложения.
Какая приёмка нужна владельцу интеграции
- Выберите одну API-операцию и потребителя её данных.
- Опишите отдельно вход, выход и непубличные свойства.
- Согласуйте диалект и контекст генерации схемы.
- Сверьте результат с разрешёнными учебными запросом и ответом.
- Проверьте фактическое отклонение недопустимых данных и бизнес-ограничения.
- Сравните требования выбранного пакета с окружением проекта.
- Сохраните версию контракта и порядок обновления документации.
Критерий полезного пилота — не только полученный JSON-файл. Внешний разработчик должен понять, что отправить и что получить, а сервер должен подтвердить ту же договорённость. Если остаётся расхождение, сначала исправьте источник контракта или обработку, а не скрывайте его правкой описания вручную.
Для разработки API-интеграции передайте пример обмена и матрицу полей. В веб-приложении сохраните серверные проверки, а при доработке проекта сравните новый контракт с действующими потребителями. В рамках статьи зависимости не устанавливались и код анонса не запускался.
Вопросы и ответы
Что даёт генератор JSON Schema из PHP-типов?
Он помогает получить структурное описание данных на основе типов и метаданных. Полученную схему нужно сверить с направлением API и фактическим обменом.
JSON Schema заменяет серверную валидацию?
Само описание не доказывает, что обработчик применяет нужные проверки. Отдельно проверяйте ограничения данных, права пользователя и допустимость бизнес-действия.
Нужен ли полный Symfony 8.2 для проверки JsonSchema?
Требования отдельного компонента и всего фреймворка различаются. Сверьте доступный пакет и зависимости своего проекта; совместимость нельзя установить только по названию анонса.