Symfony 8.2 : JSON Schema généré depuis vos types PHP

Ce qui se passe

JSON Schema décrit la forme de données JSON. OpenAPI s'en sert pour documenter les corps de requête et de réponse d'une API, et les agents IA pour savoir quels arguments attendent les outils qu'ils appellent, par exemple sur un serveur MCP. Symfony 8.2 ajoute un composant JsonSchema qui génère ces schémas depuis des types PHP. Son moteur provient du paquet json-schema d'API Platform, amputé de ce qui est propre à API Platform. Contribution d'Antoine Bluchet, pull request #66685.

Comment ça marche

Le générateur transforme un type TypeInfo en schéma. Il lit les propriétés de la classe avec PropertyInfo, ce qui fait suivre au schéma les métadonnées du serializer (groupes, convertisseur de noms, maps de discriminants) et les contraintes de validation. Deux exemples donnés par le billet : NotBlank devient minLength: 1, et une propriété sans valeur par défaut est obligatoire.

OpenAPI : un même objet n'a pas la même forme en entrée et en sortie (l'id est renvoyé, jamais envoyé), et chaque version d'OpenAPI a sa variante de JSON Schema. La classe Configuration règle donc :

• dialect : OpenAPI 3.1 ou 3.0, à la place de JSON Schema 2020-12 ;
• groups : ne garder que certains groupes de sérialisation ;
• direction : Direction::Input pour ce que l'API reçoit, Direction::Output pour ce qu'elle renvoie.

Pour un document OpenAPI complet, passer le même SchemaDocument à chaque appel de generate() partage les définitions entre schémas.

Outils d'agents : l'entrée d'un outil est l'ensemble des paramètres de la méthode PHP qui l'implémente. generateForParameters() les décrit avec leurs types, valeurs par défaut, descriptions @param (il faut alors phpstan/phpdoc-parser) et le nouvel attribut #[JsonSchemaConstraint]. Sans valeur par défaut, un paramètre est obligatoire. Les paramètres objet sont rangés en définitions référencées par $ref ; flatten() les remet en ligne et donne le schéma autonome qu'attendent en général les clients MCP et les fournisseurs de modèles. allowExtraAttributes: false refuse les propriétés inconnues.

Dans une application Symfony

Aucune configuration : on installe le composant et on injecte le générateur. Avec le Serializer et le Validator activés, il suit leur mapping ainsi que les options datetime_format et uid_normalization_format du contexte par défaut du serializer, pour que les schémas collent au JSON réellement produit. Les services qui implémentent les interfaces d'extension du composant sont autoconfigurés.

Ce qu'il faut savoir

• Le composant exige seulement PHP 8.2 et fonctionne avec les composants Symfony 7.4 : un projet qui supporte d'anciennes versions, comme Symfony AI, peut l'utiliser tout de suite.
• La 8.2 n'est pas sortie, et le billet renvoie vers une pull request pour la documentation (symfony-docs #23348).
• Les exemples de code du billet ne figurent pas dans la matière lue pour cette fiche : les noms ci-dessus sont ceux cités dans le texte, la syntaxe exacte est à prendre dans la documentation.

Source : Symfony, 20 octobre 2026. Source en anglais.