01
Définir la version de référence
L’ancien SDL correspond au contrat déjà publié. Inverser les côtés transforme une suppression en ajout et relance le classement ; vérifiez ce sens avant d’interpréter le nombre de ruptures.
Documents GraphQL
comparaison de schémas GraphQLévaluer le contrat avant publication
Placez le SDL complet en production à gauche et la version proposée à droite. Le sens de comparaison détermine le risque.
comparaison de schémas GraphQL
Ancien schéma SDL
Nouveau schéma SDL
Différences
Saisissez deux schémas SDL complets ou chargez l’exemple.
Les deux SDL sont analysés dans ce navigateur. Aucune requête API, aucun téléversement, historique enregistré ou contenu placé dans l’URL.
Options
GraphQL.js classe les ruptures et les risques potentiels. Les autres écarts structurels et changements de dépréciation sont affichés sans être déclarés sûrs.
Chaque SDL est limité à 100 000 caractères, 20 000 tokens et 100 niveaux d’imbrication. La comparaison s’arrête après 8 secondes.
Saisissez deux schémas SDL complets ou chargez l’exemple.
Une comparaison de schémas GraphQL aide à relire une proposition d’API quand les définitions ont été réordonnées et que le diff texte devient bruyant. Les clients dépendent des types, champs et arguments, pas de l’indentation du fichier.
Le rapport distingue les changements structurels des règles de compatibilité. Un champ ajouté ou marqué @deprecated reste dans la liste même si GraphQL.js ne le classe ni comme rupture ni comme danger : absence d’alerte ne signifie pas sûreté démontrée.
Pourquoi choisir cette comparaison de schémas GraphQL
Retrouver les changements du contrat sans confondre mise en forme et rupture.
Suivre les chemins du schéma
La comparaison de schémas GraphQL construit les deux schémas depuis le SDL, puis associe types, champs et arguments par chemin. Un simple réordonnancement disparaît du rapport ; la suppression réelle d’un champ apparaît avec son ancien type.
Distinguer danger et dépréciation
Une valeur enum ajoutée peut surprendre un client qui énumère tous les cas. Ajouter @deprecated n’enlève pas le champ. La comparaison de schémas GraphQL affiche séparément ces faits et laisse les nouveautés non classées à examiner.
Lire le bon sens de changement et le bon rapport
02
Choisir le déclenchement
La comparaison automatique attend environ 350 ms après une modification. Pour coller un gros SDL, désactivez-la et lancez Comparer ou Ctrl/Cmd+Entrée une fois les deux versions prêtes.
03
Ne garder que le résultat à jour
Toute modification rend le rapport précédent périmé et bloque copie et téléchargement. Corrigez l’erreur indiquée sur le bon côté, avec sa ligne et sa colonne si disponibles, puis relancez. L’export contient toutes les lignes même si l’écran en montre 100.
Trois lectures d’un même changement
Différence structurelle utile
Types, champs, arguments, entrées, enums, unions et directives sont comparés comme éléments GraphQL. La position des définitions et les espaces ne deviennent pas de faux écarts.
Règles de compatibilité vérifiables
GraphQL.js fournit les catégories rupture et risque potentiel, avec un code de règle visible. Les autres modifications restent listées sans certificat implicite de compatibilité. Ces changements cassants sont distincts des risques simplement potentiels.
Dépréciation et export intégral
Une raison @deprecated ajoutée ou modifiée fait l’objet d’une ligne dédiée. Supprimer ensuite le champ déprécié reste une rupture selon les règles par défaut.
Ce que le SDL statique ne peut pas conclure
- Deux schémas complets et valides
- Un fragment isolé sans racine Query ou une référence à un type absent ne forme pas un schéma complet. La comparaison de schémas GraphQL interrompt le rapport et situe l’erreur au lieu d’afficher zéro différence.
- Pas de mesure de l’usage client
- Une rupture signale que des opérations existantes pourraient échouer. Le navigateur ne connaît ni le trafic ni les requêtes réellement exécutées ; examinez ces données à part pour mesurer l’impact.
- Pas d’URL ni de JSON d’introspection
- Seuls deux textes SDL sont acceptés. Aucun endpoint n’est contacté, aucune mutation n’est exécutée et aucun fichier n’est envoyé. Convertissez l’introspection JSON en SDL complet avant comparaison.
- Renommer ne crée pas un lien automatique
- Deux instantanés ne révèlent pas l’intention de migration. L’ancien nom apparaît supprimé et le nouveau ajouté ; @deprecated ne dispense pas la suppression de son classement de rupture. Les champs dépréciés restent utilisables avant leur suppression.
Questions sur la comparaison de schémas GraphQL
Accepter null dans un argument de mutation est-il un changement cassant ?
Autoriser null sur un argument de mutation auparavant obligatoire élargit en général les entrées admises. GraphQL.js ne classe pas ce sens comme rupture ; rendre l’argument obligatoire peut au contraire refuser d’anciens appels.
Ajouter une valeur à un enum GraphQL est-il un changement cassant ?
L’ajout d’une valeur enum est classé comme risque potentiel. Les requêtes peuvent rester valides, mais un client qui suppose connaître toutes les valeurs risque de mal gérer le nouveau cas.
Peut-on renommer un type GraphQL sans rompre la compatibilité ?
Les deux SDL ne portent aucune intention de renommage. La comparaison de schémas GraphQL montre une suppression et un ajout distincts ; une transition sans interruption exige un choix dans l’API.
Peut-on déprécier une mutation GraphQL ?
Une mutation est un champ du type racine Mutation : elle peut recevoir @deprecated. Ce marqueur laisse fonctionner les anciennes opérations, alors que la suppression ultérieure reste une rupture.
Rendre nullable un champ non nul rompt-il la compatibilité ?
Passer un champ retourné de non nul à nullable modifie les hypothèses des clients générés. GraphQL.js le signale comme rupture ; dans l’autre sens, vérifiez aussi que les résolveurs respectent la nouvelle promesse.
Un résultat inattendu avec votre document ?
Lancer une comparaison de schémas GraphQL
Rapprochez le SDL publié et le SDL proposé, lisez chaque catégorie puis exportez le rapport actuel.