GraphQL SDL: validar y formatear un esquema en línea

¿Por qué validar el SDL GraphQL antes de hacer merge?

Un esquema que no parsea bloquea la generación de clientes, hace fallar el arranque del servidor GraphQL y convierte la relectura en adivinanzas. Las causas habituales — llave faltante, tipo desconocido, raíz Query olvidada — se esconden en un diff SDL de 400 líneas. El validador SDL GraphQL FastMinify ejecuta buildSchema de GraphQL.js en el navegador: pega el documento de esquema y obtén un veredicto válido/inválido con línea y columna cuando GraphQL.js las proporciona. El formateo sigue en Beautify GraphQL (Prettier). No existe un slug format-graphql. El resto del cluster está en el hub de herramientas API. Si también mantienes contratos REST, encadena con la guía de validación OpenAPI.

Detectar errores de sintaxis SDL y tipos desconocidos antes de la CI

Línea y columna en las incidencias cuando GraphQL.js las señala

Stats del esquema: número de tipos, campos Query / Mutation / Subscription

100 % en el navegador — el esquema nunca se envía

Formatear queries y SDL por separado con Beautify GraphQL (Prettier)

Límites honestos y hábitos que se sostienen en review

Lo que validate-graphql no hace

Un veredicto válido significa que buildSchema de GraphQL.js aceptó el SDL pegado. No es una prueba de que la API se comporte correctamente en producción.

Sin ejecución de query o mutation — sin llamada a resolver, sin coerción de variables sobre datos en vivo

Sin introspección de un servidor en ejecución — pega el documento de esquema que tienes

Sin fetch de archivos .graphql remotos, includes o URL Git

Sin compose Federation / supergraph — un solo documento SDL por pegado

Máximo 512 KiB UTF-8 en el validador — los monolitos enormes se quedan en tooling local

Un archivo, un check local y luego la CI

La herramienta del navegador sirve el bucle rápido antes de git push. Los equipos siguen lanzando GraphQL.js, graphql-eslint o rover en CI como gate de merge.

Mantén un archivo de esquema (o un SDL empaquetado) para que el pegado coincida con lo que ve la CI

No trates FastMinify como un monitor de facturación o de uptime de tu endpoint GraphQL

Documenta si el repo usa un tipo Query por defecto o un schema { query: … } personalizado

Si también publicas OpenAPI, valida ese contrato por separado — consulta la guía OpenAPI

Para instancias JSON Schema, usa json-schema-validator — otro metamodelo

Hábitos de review que detectan las roturas reales

La mayoría de los incidentes SDL son restos de rename y raíces faltantes, no funcionalidades GraphQL exóticas.

Tras cada rename de tipo, pega el esquema completo — no solo el hunk

Exige una raíz Query (o una definición schema explícita) en la misma PR que los tipos nuevos

Embellece antes de pedir la review para que las listas de campos sean visibles en el diff de GitHub

Copia el error del validador en la descripción de la PR cuando los logs de CI sean ruidosos

Alinea las opciones de formateo (2 vs. 4 espacios) con la config Prettier del repo

SDL de esquema vs. queries: dos documentos, dos herramientas

Qué es realmente el SDL GraphQL

El Schema Definition Language (SDL) describe tipos, campos y raíces. Es el contrato que tus resolvers deben honrar — no una query ejecutable. FastMinify valida ese contrato con buildSchema de GraphQL.js, sin hablar con un servidor en vivo.

Tipos objeto, interfaces, enums, unions, escalares e input objects

Campos raíz en Query, Mutation y Subscription cuando esos tipos existen

El panel de resultados cuenta esos tipos y campos raíz tras un parse correcto

El SDL es un documento pegado — FastMinify no recupera archivos .graphql vía URL

Un veredicto válido significa que GraphQL.js aceptó el documento, no que los resolvers de prod coincidan

Queries, mutations y fragments no tienen cabida aquí

Un documento de operación (query, mutation, subscription, fragment) no es SDL de esquema. Pegarlo en el validador hace fallar buildSchema. Formatea esos documentos con Beautify GraphQL.

Validate GraphQL solo acepta SDL de esquema — buildSchema, sin ejecución de queries

Beautify GraphQL formatea SDL y documentos de operación vía el parser GraphQL de Prettier

El codegen y Apollo/Yoga necesitan un esquema válido; indentar una query no corrige un tipo desconocido

Sin ejecutor de queries ni introspección en vivo en FastMinify

Para JSON REST, usa el validador JSON — no entiende el SDL

La raíz Query suele ser obligatoria

GraphQL.js suele exigir un tipo raíz Query, salvo si tu definición schema nombra otro tipo de query. Un documento con solo type User { … } sin raíz query falla la mayoría de las veces — es esperado, no un bug de FastMinify.

Pegado mínimo válido: type Query { hello: String }

Raíz personalizada: schema { query: RootQuery } más type RootQuery { … }

Query ausente: sorpresa frecuente del «en mi editor pasa»

Los tipos no definidos fallan con un mensaje del tipo Unknown type "Foo" — a menudo con un número de línea

Algunos errores semánticos omiten las locations; el veredicto sigue siendo inválido

Validar vs. embellecer: no los inviertas

Validar responde a «¿este SDL de esquema lo acepta GraphQL.js?». Embellecer responde a «¿este GraphQL es legible?». La indentación nunca corrige un tipo desconocido.

Validar: buildSchema — válido o inválido, incidencias con línea/columna si están disponibles

Embellecer: Prettier — tabWidth 2 o 4, tabulaciones, printWidth 80 / 100 / 120

Las opciones Prettier de JavaScript (puntos y coma, quotes, trailing commas) no se aplican a GraphQL

Orden recomendado: validar el SDL → corregir los tipos → embellecer → abrir la PR

Beautify puede formatear una query que validate-graphql rechazará con razón como no-SDL

Validar y luego formatear: un workflow concreto

Usar el validador SDL GraphQL

Abre el validador GraphQL, pega un solo documento de esquema (máx. 512 KiB UTF-8) y espera el veredicto (debounce). El panel muestra Válido o Inválido, el primer error con línea y columna si se conocen, una acción de copiar el error, y las stats del esquema si el parse tiene éxito.

Pega solo SDL de esquema — no una query, no una URL de endpoint

Validación en vivo en el editor — sin subida, sin cuenta

Stats tras un parse correcto: tipos, campos Query, mutations, subscriptions

Copia el mensaje de error en la PR si necesitas una traza

Tope de 512 KiB — los esquemas muy grandes se quedan en local (GraphQL.js) o en CI

Formatear con Beautify GraphQL

El embellecedor GraphQL hace pretty-print de esquemas y operaciones con Prettier. Útil para diffs de review — no sustituye validate. Opciones: 2 o 4 espacios o tabulaciones, más el ancho de impresión. Todos los formateadores están en el hub de herramientas beautify.

SDL legible para humanos — campos anidados desplegados

El mismo motor Prettier que el resto de la familia de formateadores FastMinify

Los errores de sintaxis muestran un índice de línea — corrige y vuelve a intentar

Queries y fragments son bienvenidos aquí; no en validate-graphql

Encadena validate → beautify para que los reviewers vean un esquema tipado e indentado

Escenario — tipo desconocido en una pull request

Un compañero renombró Pet a Animal pero dejó pet(id: ID!): Pet en Query. La CI o el servidor fallan, con poco contexto en el overlay de GitHub.

Paso 1: pegar el esquema en validate-graphql

Abre validate-graphql. Un veredicto inválido con Unknown type "Pet" (y una línea si está disponible) señala el campo obsoleto.

Paso 2: corregir el nombre de tipo o restaurar el tipo

Renombra el tipo de retorno del campo a Animal o vuelve a añadir type Pet. Vuelve a pegar hasta que el panel muestre un esquema válido.

Paso 3: embellecer y hacer commit

Pasa el SDL corregido por beautify-graphql, copia o descarga y actualiza la PR. Los reviewers leen tipos, no un blob de una línea.

Escenario — SDL ilegible antes de una review de esquema

Un esquema generado o de aspecto minificado llega al repositorio. Los reviewers no ven qué campos están en Query frente a Mutation.

Paso 1: embellecer primero si ni siquiera puedes leerlo

Pega en beautify-graphql. Prettier despliega selecciones y cuerpos de tipos. Este paso no demuestra que el esquema sea válido.

Paso 2: validar el documento formateado

Copia el SDL indentado en validate-graphql. Comprueba que la raíz Query existe y que cada tipo nombrado está definido.

Paso 3: leer las baldosas de stats

El número de tipos y de campos raíz ayuda a detectar una Query vacía o mutations perdidas. Luego haz commit del archivo formateado.

Conclusión

Valida el SDL GraphQL en el navegador con buildSchema y luego formatea con Prettier — en local, sin enviar el esquema a ningún sitio. Este bucle atrapa tipos desconocidos y raíces Query faltantes antes de la CI o de un gateway. No sustituye un servidor en vivo, la introspección ni el compose federation. Para contratos REST, quédate en el hub API; para queries legibles, quédate en Beautify GraphQL.

Validar o formatear tu GraphQL ahora

Pega el SDL de esquema en validate-graphql antes de cada PR de esquema

No pegues queries en el validador — formatéalas en Beautify GraphQL

Espera una raíz Query salvo si tu definición schema nombra otra

Trata un veredicto válido como una aceptación de GraphQL.js, no como prueba de producción

Encadena validate → beautify y deja la CI como gate de merge