Schema A (oud)

Schema B (nieuw)

Diff

Plak een schema in elk paneel — de diff werkt bij tijdens het typen.

Wat is de GraphQL Schema Diff?

Elke API-wijziging breekt iemands client. Het eerste wat je nodig hebt voor je een schema-PR merget is een heldere lijst van wat er echt veranderd is — niet een GitHub-diff van 600 regels die whitespace, herformattering en echte wijzigingen tot één muur van rood en groen mengt. Plak je oude schema links, het nieuwe rechts, en deze tool geeft je drie lijsten: wat is toegevoegd, wat is verwijderd, en welke bestaande velden van type zijn veranderd. De schema's worden geparsed volgens de GraphQL-specificatie van oktober 2021, dus wat de tool als "type" of "veld" beschouwt komt overeen met wat je server eronder verstaat.

De diff is structureel, niet tekstueel. Velden binnen een type herordenen is onzichtbaar. SDL herformatteren is onzichtbaar. Een argument hernoemen verschijnt wel. Int naar Float wijzigen op Order.total verschijnt. Nieuwe enum-waarden zoals OrderStatus.REFUNDED verschijnen onder Toevoegingen. Een union-lid verwijderen verschijnt onder Verwijderingen. De outputstijl komt overeen met de categorisering die GraphQL Inspector en Apollo schema checks gebruiken, dus de workflow vertaalt naar die tools wanneer je de check uiteindelijk in CI zet.

Alles draait in je browser. Geen upload, niets gelogd. Veilig voor niet-uitgebrachte interne schema's.

Hoe gebruik je de GraphQL Schema Diff

Plakken, plakken, lezen. Er is geen Vergelijk-knop — de diff werkt bij tijdens het typen.

Plak het oude schema in paneel A

Drop het huidige productieschema in het linkerpaneel met label Schema A (oud). Klik Uploaden voor een .graphql-, .graphqls- of .gql-bestand, of druk op Voorbeeld om een gepaard starter-/iteratievoorbeeld te laden. Het schema hoeft niet mooi te zijn — opmaakverschillen worden genegeerd.

Plak het nieuwe schema in paneel B

Drop het kandidaat-schema (dat in je PR) in het rechterpaneel met label Schema B (nieuw). De tool tokeniseert beide schema's, loopt elke typedefinitie af, en herberekent de diff een fractie van een seconde nadat je stopt met typen. De semantiek van de referentieparser volgt graphql-js dicht genoeg dat wat hier verschijnt overeenkomt met wat je server zou zien.

Lees de drie lijsten

Het onderpaneel heeft drie secties. Toevoegingen (groen) lijst nieuwe types, nieuwe velden, nieuwe enum-waarden en nieuwe union-leden. Verwijderingen (rood) lijst dezelfde categorieën omgekeerd — dat zijn meestal de breaking changes, dus scan deze lijst eerst. Wijzigingen (oranje) lijst velden en argumenten waarvan het type is veranderd, zoals Order.total: Int → Float. Als de schema's gelijkwaardig zijn, krijg je een enkele groene banner die dat aangeeft.

Wanneer je dit echt zou gebruiken

PR-review

Een teamgenoot opent een PR die vijf nieuwe velden toevoegt en een argument hernoemt. De GitHub-diff is onleesbaar omdat hij het schema ook door een formatter heeft gehaald. Plak beide versies hier en krijg de echte wijzigingslijst — meestal drie of vier items lang, geen driehonderd. Reviewers kunnen ruziën over de echte semantiek in plaats van over inspringing.

Breaking changes oppakken

Een veld verwijderen, een returntype versmallen of een verplicht argument hernoemen zijn breaking changes voor clients in productie. De Verwijderingen- en Wijzigingenlijsten brengen ze direct boven. Draai de diff voor het mergen om te bevestigen dat de breaking change opzettelijk is. Diezelfde check hoort uiteindelijk in CI — zie de Apollo schema checks-docs voor de productieversie van deze workflow.

Onboarding-documentatie

Wanneer een nieuwe engineer vraagt "wat is er afgelopen sprint veranderd?", plak je de maandagversie en de vrijdagversie in de panelen en kopieer je de diff naar je sprintnotities. Sneller dan door commits scrollen en een stuk leesbaarder.

Federation Composition Sanity Check

Na het draaien van een gefedereerde composer als Apollo Rover plak je het vorige samengestelde schema en het nieuwe. De diff vertelt je of de compositie de wijziging heeft opgepakt die je verwachtte uit de subgraph-PR — of dat er ergens stilletjes iets veranderd is.

Veelgestelde vragen

Pakt de diff specifiek breaking changes?

Alles in de Verwijderingen- en Wijzigingenlijsten is potentieel breaking — een veld verwijderen, een returntype versmallen, een argument hernoemen. De tool classificeert niet elke wijziging als "breaking" vs "non-breaking" zoals GraphQL Inspector dat doet, maar de gestructureerde lijst maakt duidelijk welke je moet bekijken.

Wordt veldvolgorde als wijziging gezien?

Nee. Velden binnen een type herordenen is structureel identiek en wordt genegeerd. Hetzelfde voor het herordenen van enum-waarden, union-leden en argumenten. Alleen toegevoegde, verwijderde of typegewijzigde items worden gerapporteerd.

En beschrijvingen en commentaar?

Block-string-beschrijvingen en commentaar worden bij structuurvergelijking genegeerd. Een beschrijving aan een veld toevoegen verschijnt niet in de diff. Wil je doc-wijzigingen volgen, doe dat in de geformatteerde SDL-diff van je PR, niet hier.

Worden mijn schema's naar een server gestuurd?

Nee. Tokenizer en diff draaien volledig in je browser. Niets wordt geüpload, niets wordt gelogd. Veilig om interne of niet-uitgebrachte schema's te plakken.

Hoe groot mag het schema zijn dat ik plak?

De pagina limiteert elke invoer op 5 MB. Daarboven begint de Ace-editor zelf te haperen. Schema's van een paar honderd types zijn geen probleem.

Kan ik dit in CI draaien?

Voor lokale sanity checks voor het pushen van een PR is deze pagina prima. Voor CI-gates die de build laten falen op een breaking change gebruik je de specifieke GraphQL Inspector-CLI of Apollo schema checks — beide hebben goede exit-code-semantiek en policy-configuratie.

Andere GraphQL-tools

Diffen is maar één onderdeel van werken met GraphQL. Deze tools regelen de rest: