GraphQL SDL : valider et formater un schéma en ligne

Pourquoi valider le SDL GraphQL avant de merger ?

Un schéma qui ne parse pas bloque la génération de clients, fait échouer le démarrage du serveur GraphQL et transforme la relecture en devinettes. Les causes habituelles — accolade manquante, type inconnu, racine Query oubliée — se cachent dans un diff SDL de 400 lignes. Le validateur SDL GraphQL FastMinify exécute buildSchema de GraphQL.js dans le navigateur : collez le document de schéma, obtenez un verdict valide/invalide avec ligne et colonne lorsque GraphQL.js les fournit. Le formatage reste sur Beautify GraphQL (Prettier). Il n'existe pas de slug format-graphql. Le reste du cluster est sur le hub outils API. Si vous maintenez aussi des contrats REST, enchaînez avec le guide de validation OpenAPI.

Repérer les erreurs de syntaxe SDL et les types inconnus avant la CI

Ligne et colonne sur les issues lorsque GraphQL.js les signale

Stats du schéma : nombre de types, champs Query / Mutation / Subscription

100 % dans le navigateur — le schéma n'est jamais envoyé

Formater requêtes et SDL à part avec Beautify GraphQL (Prettier)

Limites honnêtes et habitudes qui tiennent en revue

Ce que validate-graphql ne fait pas

Un verdict valide signifie que buildSchema de GraphQL.js a accepté le SDL collé. Ce n'est pas une preuve que l'API se comporte correctement en production.

Pas d'exécution de query ou mutation — pas d'appel de resolver, pas de coercition de variables sur des données live

Pas d'introspection d'un serveur en cours d'exécution — collez le document de schéma que vous possédez

Pas de fetch de fichiers .graphql distants, d'includes ou d'URL Git

Pas de compose Federation / supergraph — un seul document SDL par collage

Maximum 512 Kio UTF-8 sur le validateur — les monolithes énormes restent en outillage local

Un fichier, un check local, puis la CI

L'outil navigateur sert la boucle rapide avant git push. Les équipes lancent toujours GraphQL.js, graphql-eslint ou rover en CI comme gate de merge.

Gardez un fichier de schéma (ou un SDL bundlé) pour que le collage corresponde à ce que la CI voit

Ne traitez pas FastMinify comme un moniteur de facturation ou d'uptime de votre endpoint GraphQL

Documentez si le repo utilise un type Query par défaut ou un schema { query: … } personnalisé

Si vous publiez aussi de l'OpenAPI, validez ce contrat à part — voir le guide OpenAPI

Pour des instances JSON Schema, utilisez json-schema-validator — autre méta-modèle

Habitudes de revue qui attrapent les vrais cassages

La plupart des incidents SDL sont des restes de rename et des racines manquantes, pas des fonctionnalités GraphQL exotiques.

Après chaque rename de type, collez le schéma complet — pas seulement le hunk

Exigez une racine Query (ou une définition schema explicite) dans la même PR que les nouveaux types

Beautifiez avant de demander la revue pour que les listes de champs soient visibles dans le diff GitHub

Copiez l'erreur du validateur dans la description de PR quand les logs CI sont bruyants

Alignez les options de formatage (2 vs 4 espaces) sur la config Prettier du repo

SDL de schéma vs requêtes : deux documents, deux outils

Ce qu'est réellement le SDL GraphQL

Le Schema Definition Language (SDL) décrit types, champs et racines. C'est le contrat que vos resolvers doivent honorer — pas une requête exécutable. FastMinify valide ce contrat avec buildSchema de GraphQL.js, sans parler à un serveur en live.

Types objet, interfaces, enums, unions, scalaires et input objects

Champs racines sur Query, Mutation et Subscription lorsque ces types existent

Le panneau de résultats compte ces types et champs racines après un parse réussi

Le SDL est un document collé — FastMinify ne récupère pas de fichiers .graphql via URL

Un verdict valide signifie que GraphQL.js a accepté le document, pas que les resolvers de prod correspondent

Requêtes, mutations et fragments n'ont pas leur place ici

Un document d'opération (query, mutation, subscription, fragment) n'est pas du SDL de schéma. Le coller dans le validateur fait échouer buildSchema. Formatez ces documents avec Beautify GraphQL.

Validate GraphQL n'accepte que le SDL de schéma — buildSchema, pas d'exécution de requêtes

Beautify GraphQL formate SDL et documents d'opération via le parser GraphQL de Prettier

Le codegen et Apollo/Yoga ont besoin d'un schéma valide ; indenter une query ne corrige pas un type inconnu

Pas d'exécuteur de requêtes ni d'introspection live sur FastMinify

Pour du JSON REST, utilisez le validateur JSON — il ne comprend pas le SDL

La racine Query est en général obligatoire

GraphQL.js exige en général un type racine Query, sauf si votre définition schema nomme un autre type de query. Un document avec seulement type User { … } sans racine query échoue le plus souvent — c'est attendu, pas un bug FastMinify.

Collage minimal valide : type Query { hello: String }

Racine personnalisée : schema { query: RootQuery } plus type RootQuery { … }

Query manquante : surprise fréquente du « ça passe dans mon éditeur »

Les types non définis échouent avec un message du type Unknown type "Foo" — souvent avec un numéro de ligne

Certaines erreurs sémantiques omettent les locations ; le verdict reste invalide

Valider vs beautifier : ne les inversez pas

Valider répond à « ce SDL de schéma est-il accepté par GraphQL.js ? ». Beautifier répond à « ce GraphQL est-il lisible ? ». L'indentation ne corrige jamais un type inconnu.

Valider : buildSchema — valide ou invalide, issues avec ligne/colonne si disponibles

Beautifier : Prettier — tabWidth 2 ou 4, tabulations, printWidth 80 / 100 / 120

Les options Prettier JavaScript (points-virgules, quotes, trailing commas) ne s'appliquent pas au GraphQL

Ordre recommandé : valider le SDL → corriger les types → beautifier → ouvrir la PR

Beautify peut formater une query que validate-graphql rejettera à juste titre comme non-SDL

Valider puis formater : un workflow concret

Utiliser le validateur SDL GraphQL

Ouvrez le validateur GraphQL, collez un seul document de schéma (max 512 Kio UTF-8) et attendez le verdict (debounce). Le panneau affiche Valide ou Invalide, la première erreur avec ligne et colonne si connues, une action copier l'erreur, et les stats du schéma si le parse réussit.

Collez uniquement du SDL de schéma — pas une query, pas une URL d'endpoint

Validation live dans l'éditeur — pas d'upload, pas de compte

Stats après un bon parse : types, champs Query, mutations, subscriptions

Copiez le message d'erreur dans la PR si vous avez besoin d'une trace

Plafond 512 Kio — les très gros schémas restent en local (GraphQL.js) ou en CI

Formater avec Beautify GraphQL

Le beautifier GraphQL pretty-print schémas et opérations avec Prettier. Utile pour les diffs de review — il ne remplace pas validate. Options : 2 ou 4 espaces ou tabulations, plus la largeur d'impression. Tous les formateurs sont sur le hub outils beautify.

SDL lisible pour les humains — champs imbriqués déroulés

Même moteur Prettier que le reste de la famille de formateurs FastMinify

Les erreurs de syntaxe affichent un indice de ligne — corrigez et réessayez

Queries et fragments sont les bienvenus ici ; pas sur validate-graphql

Enchaînez validate → beautify pour que les reviewers voient un schéma typé et indenté

Scénario — Type inconnu dans une pull request

Un coéquipier a renommé Pet en Animal mais a laissé pet(id: ID!): Pet sur Query. La CI ou le serveur échoue, avec peu de contexte dans l'overlay GitHub.

Étape 1 : coller le schéma dans validate-graphql

Ouvrez validate-graphql. Un verdict invalide avec Unknown type "Pet" (et une ligne si disponible) pointe le champ périmé.

Étape 2 : corriger le nom de type ou restaurer le type

Renommez le type de retour du champ en Animal ou réajoutez type Pet. Recollez jusqu'à ce que le panneau affiche un schéma valide.

Étape 3 : beautifier et committer

Passez le SDL corrigé dans beautify-graphql, copiez ou téléchargez, mettez à jour la PR. Les reviewers lisent des types, pas un blob d'une ligne.

Scénario — SDL illisible avant une revue de schéma

Un schéma généré ou d'allure minifiée arrive dans le dépôt. Les reviewers ne voient pas quels champs sont sur Query versus Mutation.

Étape 1 : beautifier d'abord si vous ne pouvez même pas le lire

Collez dans beautify-graphql. Prettier déroule sélections et corps de types. Cette étape ne prouve pas que le schéma est valide.

Étape 2 : valider le document formaté

Copiez le SDL indenté dans validate-graphql. Vérifiez que la racine Query existe et que chaque type nommé est défini.

Étape 3 : lire les tuiles de stats

Le nombre de types et de champs racines aide à repérer une Query vide ou des mutations perdues. Puis commitez le fichier formaté.

Conclusion

Validez le SDL GraphQL dans le navigateur avec buildSchema, puis formatez avec Prettier — en local, sans envoyer le schéma nulle part. Cette boucle attrape types inconnus et racines Query manquantes avant la CI ou une gateway. Elle ne remplace pas un serveur en live, l'introspection, ni le compose federation. Pour les contrats REST, restez sur le hub API ; pour des queries lisibles, restez sur Beautify GraphQL.

Validez ou formatez votre GraphQL maintenant

Collez le SDL de schéma dans validate-graphql avant chaque PR de schéma

Ne collez pas de queries dans le validateur — formatez-les sur Beautify GraphQL

Attendez-vous à une racine Query sauf si votre définition schema en nomme une autre

Traitez un verdict valide comme une acceptation GraphQL.js, pas une preuve de production

Enchaînez validate → beautify, puis gardez la CI comme gate de merge