01
Identifica la versión antigua
La izquierda debe reflejar el contrato vigente. Intercambiar lados vuelve a calcular el riesgo: una eliminación se convierte en alta y no debe interpretarse con la cifra anterior.
Documentos GraphQL
comparar esquemas GraphQLrevisar el contrato antes de publicar
Pon el SDL completo publicado a la izquierda y la propuesta a la derecha. El sentido decide qué se eliminó y qué se añadió.
comparar esquemas GraphQL
SDL del esquema anterior
SDL del esquema nuevo
Diferencias
Introduce dos esquemas SDL completos o carga el ejemplo.
Ambos SDL se analizan en este navegador. No se hacen peticiones API ni cargas, no se guarda historial y el contenido no entra en la URL.
Opciones
GraphQL.js clasifica cambios incompatibles y riesgos potenciales. Los demás cambios estructurales y de obsolescencia se muestran sin declarar que sean seguros.
Cada SDL admite 100.000 caracteres, 20.000 tokens y 100 niveles de anidación. La comparación se detiene a los 8 segundos.
Introduce dos esquemas SDL completos o carga el ejemplo.
Al comparar esquemas GraphQL antes de una publicación, una diferencia de texto puede distraer con espacios y definiciones reordenadas. Lo que necesitan los clientes es saber si cambió el contrato de tipos, campos o argumentos. Un diff de GraphQL basado en estructura evita ese ruido.
Este análisis separa la estructura de la clasificación de riesgos. GraphQL.js no llama incompatibles a todas las adiciones o marcas @deprecated, pero esos cambios siguen apareciendo para que el equipo no los confunda con una garantía de seguridad.
Por qué comparar esquemas GraphQL aquí
Las diferencias de formato no ocultan cambios reales en el contrato.
Localiza la ruta que cambió
La herramienta construye ambos esquemas a partir de SDL y compara rutas de tipos, campos y argumentos. Al comparar esquemas GraphQL de este modo, cambiar el orden de las definiciones no crea ruido y un campo eliminado conserva su identidad en el informe.
Separa incompatibilidad y obsolescencia
Añadir un valor enum puede afectar a clientes con casos exhaustivos. Marcar un campo con @deprecated no equivale a borrarlo. Al comparar esquemas GraphQL, ambos hechos y las nuevas altas se presentan en categorías distintas.
Revisar la dirección y la vigencia del resultado
02
Decide cuándo ejecutar
Por defecto la comparación espera unos 350 ms después de escribir. Si pegas un SDL largo, desactiva el modo automático y usa Comparar o Ctrl/Cmd+Intro cuando ambas versiones estén listas.
03
Exporta solo después de corregir
Cada edición deja obsoleto el informe y desactiva copiar y descargar. Corrige el error indicado en el esquema antiguo o nuevo y su línea y columna. Aunque se muestren 100 filas por vez, la exportación incluye todas.
Cambios visibles más allá del texto
Rutas estructurales
Tipos, campos, argumentos, entradas, enums, uniones y directivas se comparan como elementos GraphQL; espacios y orden no cuentan como modificaciones de API.
Categorías de GraphQL.js
Las reglas de la biblioteca determinan lo incompatible y lo potencialmente peligroso. El código de regla queda visible y las demás diferencias no reciben una etiqueta automática de seguridad.
Obsolescencia e informe completo
Las variaciones de @deprecated se registran aparte. Si se borra más tarde un campo obsoleto, la eliminación sigue siendo incompatible según la regla predeterminada.
Límites de una revisión estática de SDL
- Dos SDL completos y válidos
- Un tipo aislado sin raíz Query o una referencia a un tipo inexistente no forman un esquema completo. Al comparar esquemas GraphQL, un error detiene el informe y señala el lado y la posición disponible, sin fingir que no hubo diferencias.
- No se conocen las consultas de clientes
- Una marca incompatible indica que operaciones existentes podrían fallar. No se mide el tráfico ni se consultan los clientes reales, así que el impacto concreto requiere otra comprobación.
- Sin URL ni JSON de introspección
- Se aceptan únicamente dos textos SDL. No se contacta un endpoint, no se ejecutan consultas ni se suben archivos; transforma primero la introspección JSON a SDL completo.
- Un cambio de nombre no se adivina
- Con dos instantáneas no se conoce la intención de migración. Aparecen una eliminación y un alta; incluso un campo marcado @deprecated mantiene el riesgo de su eliminación. Los campos obsoletos siguen siendo parte del contrato hasta su eliminación real.
Preguntas al comparar esquemas GraphQL
¿Aceptar null en un argumento de mutación es un cambio incompatible?
Hacer nullable un argumento de mutación antes obligatorio suele ampliar las entradas permitidas, por lo que GraphQL.js no lo clasifica como incompatible en ese sentido. Exigirlo a la inversa sí puede rechazar llamadas previas.
¿Añadir un valor enum es un cambio incompatible en GraphQL?
GraphQL.js considera potencialmente peligroso añadir un valor enum. Las consultas antiguas pueden seguir siendo válidas, pero un cliente que cubre todos los casos conocidos podría no reconocer el nuevo.
¿Se puede renombrar un tipo GraphQL sin romper clientes?
Los SDL no expresan que un nombre sustituyó a otro. Al comparar esquemas GraphQL se muestran por separado la eliminación del tipo antiguo y la incorporación del nuevo; planifica una transición en la API si hace falta.
¿Es posible marcar una mutación GraphQL como obsoleta?
Una mutación es un campo del tipo raíz Mutation y admite @deprecated. Esa marca conserva las operaciones previas; borrar el campo después sigue siendo incompatible con las reglas normales.
¿Volver nullable un campo no nulo rompe la compatibilidad?
Volver nullable un campo de respuesta no nulo puede invalidar supuestos de tipos generados, y GraphQL.js lo marca incompatible. En el sentido contrario también hay que probar que el resolver cumpla la promesa.
¿Un documento da un resultado inesperado?
Volver a comparar esquemas GraphQL antes del despliegue
Coloca el SDL vigente y el propuesto, examina riesgos y otras diferencias y guarda el informe actualizado.