Validador de GraphQL
Comprueba un esquema GraphQL en busca de problemas de sintaxis y mira un desglose de tipos, campos, enums y directivas
Entrada
Validación
¿Qué es el Validador de GraphQL?
Un esquema que sale de un compositor de federación, de un generador de código o de una edición a mano durante una revisión casi siempre tiene al menos un problema de sintaxis en la primera pasada. Un } de más, una cadena de descripción sin cerrar, un cuerpo de enum que se cortó cuando alguien copió media pantalla de SDL en un chat — y de pronto el arranque de tu Apollo Server revienta con un error del parser apuntando a la línea 1, que rara vez es donde está el problema real. Este validador recorre el SDL token a token y señala la línea de verdad.
Comprueba reglas estructurales de la especificación GraphQL de octubre de 2021: cada {, ( y [ necesita un cierre del tipo correcto; las descripciones escritas como """...""" tienen que cerrarse; las cadenas entre comillas dentro de los argumentos deben cerrarse en la misma línea. El validador NO comprueba la semántica — no te dirá que falta Query ni que un campo referencia un tipo no declarado. Para eso, pasa el esquema por la implementación de referencia graphql-js. Lo que esta página hace bien es la pasada de sintaxis y el bloque de estadísticas, para que veas de un vistazo si el esquema que acabas de pegar tiene 14 tipos o 4, 187 campos o 12.
Todo se ejecuta en tu navegador. Sin subidas, sin esquemas guardados en ninguna parte. Pegar, validar, copiar.
Cómo usar el Validador de GraphQL
Tres pasos rápidos. Los botones de abajo coinciden con los botones reales de esta página.
Pega, sube o carga un ejemplo
Pega un esquema GraphQL en el panel Entrada de la izquierda — la validación se ejecuta automáticamente una fracción de segundo después de que dejes de escribir, así que no hay botón Validar. Pulsa Subir para un archivo .graphql, .graphqls o .gql, o pulsa Ejemplo para cargar un esquema de Order de comercio electrónico realista. Un pegado típico se ve así:
type Order { id: ID! placedAt: DateTime! customer: Customer! items: [OrderItem!]! status: OrderStatus! } enum OrderStatus { PENDING PAID SHIPPED }Funcionan tanto los esquemas estilo servidor (con extend type Query) como los archivos de tipos sueltos. Los comentarios (#) y las descripciones de cadena de bloque ("""...""") se tratan igual que describen los documentos de aprendizaje del esquema GraphQL.
Lee el bloque de estadísticas
El panel derecho muestra una barra verde si el esquema se parsea limpiamente, una roja si no — y en cualquiera de los dos casos obtienes un desglose de cuántas definiciones de type, interface, enum, input, union, scalar y directive declara el esquema, además del recuento total de campos, argumentos y descripciones. Útil para verificar la cordura tras un merge de federación o comparar dos revisiones del mismo esquema. Los recuentos reflejan lo que la especificación GraphQL de Relay identifica como las piezas estructurales de una definición.
Corrige y vuelve a pegar
Si el esquema no es válido, la barra te indica la línea exacta de la llave desbalanceada o la cadena sin cerrar. Arréglalo, pégalo de nuevo y mira cómo la barra se pone verde. El botón Copiar de la derecha te da un pequeño informe de estadísticas en JSON que puedes pegar en la descripción de un PR o en un mensaje de chat — práctico cuando quieres mostrarle a un compañero "sí, el esquema está bien, aquí están las estadísticas" sin compartir el SDL.
Cuándo lo usarías de verdad
Comprobación previa al merge
Antes de hacer merge de un cambio en el gateway de federación o de una actualización de schema-stitching, pega aquí el esquema compuesto. Si el balance de llaves está mal o una descripción no cierra, lo verás en dos segundos en lugar de en un fallo de CI diez minutos después. Combina bien con el comando rover subgraph check para el lado semántico.
Diffing entre dos revisiones
Pega la versión A, anota las cifras (28 tipos, 142 campos, 6 enums). Pega la versión B y compara. Si el recuento de campos saltó en 40 pero solo se añadió un tipo nuevo, probablemente alguien duplicó un fragmento. El bloque de estadísticas es mucho más rápido que scrollear un diff de 2000 líneas.
Onboarding de un nuevo contratista
Pásale el archivo del esquema, mándale a esta página y dile "si se pone roja, tu pegado está roto; si el recuento de campos es de repente 800 menos, solo copiaste la mitad". Te ahorra el ida y vuelta de "¿esto es todo?" antes de que siquiera empiecen a escribir resolvers.
Pegado desde el chat
A Slack y Discord les encanta destrozar las comillas y los backticks cuando envuelven mensajes largos, así que un esquema que alguien pegó en un hilo a menudo pierde una o dos llaves de cierre. Suéltalo aquí primero para enterarte antes de abrirlo en tu IDE.
Preguntas frecuentes
¿Valida semántica o solo sintaxis?
Solo sintaxis — balance de llaves, terminación de cadenas y un recorrido estadístico sobre el flujo de tokens. NO comprueba que Query exista, que los tipos referenciados estén definidos, que los argumentos casen con sus definiciones de directiva ni que un tipo de campo sea válido. Para una validación semántica completa, usa la biblioteca de referencia graphql-js o las comprobaciones de arranque de tu servidor.
¿Se envía mi esquema a algún servidor?
No. La validación se ejecuta enteramente en tu navegador. No se sube nada, no se registra nada. Es seguro pegar esquemas internos o no publicados.
¿Qué problemas de sintaxis va a detectar?
{ / ( / [ sin pareja con el número de línea donde estaba el abridor, cierres mal emparejados como ) donde se esperaba }, "strings" o """block strings""" sin cerrar, y caracteres sueltos que no forman parte de la gramática de tokens de GraphQL.
¿Por qué mi esquema muestra 0 tipos cuando claramente tiene tipos?
El contador solo cuenta una definición cuando están presentes su palabra clave (type, interface, etc.) Y las llaves de su cuerpo. Si pegaste un esquema truncado a mitad de tipo, el recuento de ese tipo se queda en 0 hasta que termines el cuerpo. La barra del validador también estará roja en ese caso, apuntando al abridor sin cerrar.
¿Entiende las descripciones de cadena de bloque?
Sí. """An order placed by a customer.""" se reconoce como un token de descripción y se cuenta en la estadística de Descripciones. El validador no impone dónde aparecen las descripciones — eso es una decisión de estilo — pero el recuento te da una lectura rápida de cómo de documentado está el esquema.
¿Cómo de grande puede ser el esquema que pego?
Lo que tu navegador renderice cómodamente. Esquemas con varios cientos de tipos y varios miles de campos se validan en bastante menos de un segundo. A partir de 5 MB el propio editor Ace empieza a ralentizarse, que es el cuello de botella — no el validador.
Otras herramientas de GraphQL
La validación es solo una parte de trabajar con GraphQL. Estas herramientas se ocupan del resto: