Schéma A (ancien)

Schéma B (nouveau)

Diff

Collez un schéma dans chaque panneau — le diff se met à jour pendant que vous tapez.

Qu'est-ce que le diff de schémas GraphQL ?

Chaque changement d'API casse le client de quelqu'un. La première chose dont vous avez besoin avant de merger une PR de schéma est une liste claire de ce qui a réellement changé — pas un diff GitHub de 600 lignes qui mélange espaces, reformatage et vrais changements en un mur de rouge et vert. Collez votre ancien schéma à gauche, le nouveau à droite, et cet outil vous donne trois listes : ce qui a été ajouté, ce qui a été supprimé, et quels champs existants ont changé de type. Les schémas sont parsés selon la spécification GraphQL d'octobre 2021, donc ce que l'outil considère comme un "type" ou un "champ" correspond à ce que votre serveur considère.

Le diff est structurel, pas textuel. Réorganiser les champs à l'intérieur d'un type est invisible. Reformater le SDL est invisible. Renommer un argument apparaît. Passer Int à Float sur Order.total apparaît. De nouvelles valeurs d'enum comme OrderStatus.REFUNDED apparaissent dans les ajouts. Supprimer un membre d'union apparaît dans les suppressions. Le style de sortie correspond à la catégorisation utilisée par GraphQL Inspector et Apollo schema checks, donc le workflow se transpose à ces outils quand vous finirez par mettre la vérification dans la CI.

Tout tourne dans votre navigateur. Pas d'upload, rien de loggé. Sûr pour des schémas internes non publiés.

Comment utiliser le diff de schémas GraphQL

Coller, coller, lire. Pas de bouton Comparer — le diff se met à jour pendant que vous tapez.

Collez l'ancien schéma dans le panneau A

Déposez le schéma de production actuel dans le panneau de gauche étiqueté Schéma A (ancien). Cliquez sur Importer pour un fichier .graphql, .graphqls ou .gql, ou cliquez sur Exemple pour charger une paire starter / itération. Le schéma n'a pas besoin d'être joli — les différences de formatage sont ignorées.

Collez le nouveau schéma dans le panneau B

Déposez le schéma candidat (celui de votre PR) dans le panneau de droite étiqueté Schéma B (nouveau). L'outil tokenise les deux schémas, parcourt chaque définition de type et recalcule le diff une fraction de seconde après que vous arrêtez de taper. La sémantique du parser de référence suit graphql-js d'assez près pour que ce qui s'affiche ici soit ce que votre serveur verrait.

Lisez les trois listes

Le panneau du bas a trois sections. Ajouts (vert) liste les nouveaux types, nouveaux champs, nouvelles valeurs d'enum et nouveaux membres d'union. Suppressions (rouge) liste les mêmes catégories à l'envers — ce sont en général les breaking changes, donc scannez cette liste en premier. Modifications (ambre) liste les champs et arguments dont le type a changé, comme Order.total: Int → Float. Si les schémas sont équivalents, vous obtenez une bannière verte le confirmant.

Quand vous l'utiliseriez vraiment

Revue de PR

Un coéquipier ouvre une PR qui ajoute cinq nouveaux champs et renomme un argument. Le diff GitHub est illisible parce qu'il a aussi passé le schéma dans un formateur. Collez les deux versions ici et obtenez la vraie liste de changements — généralement trois ou quatre éléments, pas trois cents. Les relecteurs peuvent débattre de la sémantique réelle au lieu de débattre de l'indentation.

Repérer les breaking changes

Supprimer un champ, restreindre un type de retour ou renommer un argument requis sont des breaking changes pour les clients en production. Les listes Suppressions et Modifications les font remonter directement. Lancez le diff avant de merger pour confirmer que le breaking change est intentionnel. La même vérification a sa place en CI à terme — voir la doc Apollo schema checks pour la version production de ce workflow.

Documentation d'onboarding

Quand un nouvel ingénieur demande "qu'est-ce qui a changé le sprint dernier ?", collez la version de lundi et celle de vendredi dans les panneaux et copiez le diff dans vos notes de sprint. Plus rapide que de scroller dans les commits et beaucoup plus lisible.

Sanity check de composition fédérée

Après avoir lancé un compositeur fédéré comme Apollo Rover, collez l'ancien schéma composé et le nouveau. Le diff vous dit si la composition a bien pris le changement attendu de la PR du subgraph — ou si autre chose a changé silencieusement ailleurs.

Questions fréquentes

Le diff repère-t-il spécifiquement les breaking changes ?

Tout ce qui est dans les listes Suppressions et Modifications est potentiellement breaking — supprimer un champ, restreindre un type de retour, renommer un argument. L'outil ne classe pas chaque changement comme "breaking" vs "non breaking" comme le fait GraphQL Inspector, mais la liste structurée rend évident quoi regarder.

L'ordre des champs est-il considéré comme un changement ?

Non. Réorganiser les champs à l'intérieur d'un type est structurellement identique et est ignoré. Pareil pour réorganiser les valeurs d'enum, les membres d'union et les arguments. Seuls les éléments ajoutés, supprimés ou avec changement de type sont reportés.

Et les descriptions et commentaires ?

Les descriptions block-string et les commentaires sont ignorés lors de la comparaison structurelle. Ajouter une description à un champ n'apparaît pas dans le diff. Si vous voulez suivre les changements de doc, faites-le dans le diff SDL formaté de votre PR, pas ici.

Mes schémas sont-ils envoyés à un serveur ?

Non. Le tokeniseur et le diff tournent entièrement dans votre navigateur. Rien n'est uploadé, rien n'est loggé. Sûr pour coller des schémas internes ou non publiés.

Quelle taille de schéma puis-je coller ?

La page limite chaque entrée à 5 Mo. Au-delà, l'éditeur Ace lui-même commence à ramer. Des schémas de quelques centaines de types ne posent pas problème.

Puis-je faire tourner ça en CI ?

Pour des sanity checks locaux avant de pousser une PR, cette page convient. Pour des gates CI qui fassent échouer le build sur un breaking change, utilisez la CLI dédiée GraphQL Inspector ou Apollo schema checks — les deux ont une vraie sémantique d'exit-code et de configuration de politique.

Autres outils GraphQL

Faire des diffs n'est qu'une partie du travail avec GraphQL. Ces outils s'occupent du reste :

Diff de schémas GraphQL