Invoer

Validatie

Plak links een GraphQL-schema om hier de validatieresultaten te zien.

Wat is de GraphQL-validator?

Een schema dat terugkomt van een federation-composer, een codegenerator of een handmatige bewerking tijdens een code review heeft bij de eerste pass bijna altijd minstens één syntaxisprobleem. Een verdwaalde }, een niet-afgesloten beschrijvingsstring, een enum-lichaam dat is afgekapt toen iemand een half scherm SDL in een chat plakte — en voor je het weet barst het opstarten van je Apollo Server open met een parserfout die wijst naar regel 1, wat zelden is waar het echte probleem zit. Deze validator loopt het SDL token voor token door en wijst de echte regel aan.

Hij controleert structurele regels uit de GraphQL-specificatie van oktober 2021: elke {, ( en [ heeft een passende sluiter van de juiste soort nodig; beschrijvingen geschreven als """...""" moeten worden afgesloten; strings tussen aanhalingstekens binnen argumenten moeten op dezelfde regel sluiten. De validator controleert GEEN semantiek — hij vertelt je niet dat Query ontbreekt of dat een veld verwijst naar een niet-gedeclareerd type. Stuur het schema daarvoor door de referentie-implementatie graphql-js. Wat deze pagina goed doet is de syntaxis-pass en het stat-blok, zodat je in één oogopslag ziet of het schema dat je net hebt geplakt 14 types of 4 heeft, 187 velden of 12.

Alles draait in je browser. Geen upload, geen schema dat ergens wordt opgeslagen. Plakken, valideren, kopiëren.

Hoe je de GraphQL-validator gebruikt

Drie snelle stappen. De knoppen hieronder komen overeen met de echte knoppen op deze pagina.

Plak, upload of laad een voorbeeld

Plak een GraphQL-schema in het linker Invoer-paneel — de validatie loopt automatisch een fractie van een seconde nadat je stopt met typen, dus er is geen Valideer-knop. Klik Uploaden voor een .graphql-, .graphqls- of .gql-bestand, of druk op Voorbeeld om een realistisch e-commerce Order-schema te laden. Een typische plak ziet er zo uit:

type Order { id: ID! placedAt: DateTime! customer: Customer! items: [OrderItem!]! status: OrderStatus! } enum OrderStatus { PENDING PAID SHIPPED }

Zowel server-stijl-schema's (met extend type Query) als losse type-bestanden werken. Commentaar (#) en block-string-beschrijvingen ("""...""") worden afgehandeld zoals de GraphQL learn-schema-documentatie beschrijft.

Lees het stat-blok

Het rechterpaneel toont een groene banner als het schema schoon parset, een rode als dat niet zo is — en in beide gevallen krijg je een uitsplitsing van hoeveel type-, interface-, enum-, input-, union-, scalar- en directive-definities het schema declareert, plus het totale aantal velden, argumenten en beschrijvingen. Handig om een federation-merge op gezond verstand te checken of twee revisies van hetzelfde schema te vergelijken. De tellingen weerspiegelen wat de Relay GraphQL-specificatie de structurele onderdelen van een definitie noemt.

Repareren en opnieuw plakken

Als het schema ongeldig is, vertelt de banner je de exacte regel van het niet-uitgebalanceerde haakje of de niet-afgesloten string. Repareer het, plak het terug, kijk hoe de banner groen wordt. De Kopieer-knop rechts geeft je een klein JSON stat-rapport dat je in een PR-beschrijving of een chatbericht kunt droppen — handig wanneer je een teamgenoot wilt laten zien "ja het schema is prima, hier zijn de stats" zonder het SDL zelf te delen.

Wanneer je dit echt zou gebruiken

Pre-merge sanity-check

Voor je een federation-gateway-wijziging of een schema-stitching-update merget, plak je het samengestelde schema hier. Als de haakjesbalans scheef is of een beschrijving niet wordt afgesloten, zie je dat hier in twee seconden in plaats van in een CI-failure tien minuten later. Past goed bij het commando rover subgraph check voor de semantische kant.

Twee revisies diffen

Plak versie A, noteer de stat-cijfers (28 types, 142 velden, 6 enums). Plak versie B en vergelijk. Als de veldcounter met 40 omhoog springt maar er maar één nieuw type is toegevoegd, heeft iemand waarschijnlijk een fragment gedupliceerd. Het stat-blok is veel sneller dan door een diff van 2000 regels scrollen.

Een nieuwe contractor inwerken

Geef hem het schemabestand, wijs hem op deze pagina en zeg "als het rood wordt is je plak kapot; als de veldcounter ineens 800 lager is, heb je maar de helft gekopieerd." Bespaart je het heen-en-weer van "is dit alles?" voor hij überhaupt resolvers gaat schrijven.

Plakken vanuit chat

Slack en Discord houden ervan om backticks en aanhalingstekens te slopen wanneer ze lange berichten omwikkelen, dus een schema dat iemand in een thread plakt mist vaak een of twee sluithaakjes. Drop het hier eerst om erachter te komen voor je het in je IDE opent.

Veelgestelde vragen

Valideert hij semantiek, of alleen syntaxis?

Alleen syntaxis — haakjesbalans, string-afsluiting en een stat-walk over de tokenstroom. Hij controleert NIET of Query bestaat, of verwezen types zijn gedefinieerd, of argumenten matchen met hun directive-definities, of dat een veldtype geldig is. Voor volledige semantische validatie gebruik je de referentiebibliotheek graphql-js of de opstartchecks van je server.

Wordt mijn schema naar een server gestuurd?

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

Welke syntaxisproblemen vangt hij echt af?

Niet-passende { / ( / [ met het regelnummer waar de opener stond, verkeerd gematchte sluiters zoals ) waar } werd verwacht, niet-afgesloten "strings" of """block strings""", en losse karakters die niet bij de GraphQL-tokengrammatica horen.

Waarom toont mijn schema 0 types terwijl het duidelijk types heeft?

De stat-teller telt een definitie pas zodra zowel het sleutelwoord (type, interface enz.) ALS de lichaamshaakjes aanwezig zijn. Als je een schema plakt dat midden in een type is afgekapt, blijft de teller voor dat type op 0 staan tot je het lichaam afmaakt. De validator-banner zal in dat geval ook rood zijn en wijst naar de niet-passende opener.

Begrijpt hij block-string-beschrijvingen?

Ja. """An order placed by a customer.""" wordt herkend als een beschrijvings-token en geteld in de Beschrijvingen-stat. De validator legt niet vast waar beschrijvingen mogen verschijnen — dat is een stijlkeuze — maar de teller geeft je een snelle indruk van hoe goed gedocumenteerd het schema is.

Hoe groot mag het schema zijn dat ik plak?

Alles wat je browser comfortabel kan renderen. Schema's van een paar honderd types en duizenden velden valideren ruim binnen een seconde. Boven de 5 MB begint de Ace-editor zelf trager te worden, en dat is de bottleneck — niet de validator.

Andere GraphQL-tools

Validatie is maar één onderdeel van het werken met GraphQL. Deze tools doen de rest: