Diff de esquemas GraphQL
Compara dos esquemas GraphQL — adiciones, eliminaciones y cambios de tipo a nivel de campo de un vistazo
Esquema A (antiguo)
Esquema B (nuevo)
Diff
¿Qué es el diff de esquemas GraphQL?
Cada cambio de API rompe el cliente de alguien. Lo primero que necesitas antes de mergear un PR de esquema es una lista clara de lo que realmente cambió — no un diff de GitHub de 600 líneas que mezcla espacios en blanco, reformateo y cambios reales en una sola pared de rojo y verde. Pega tu esquema antiguo a la izquierda, el nuevo a la derecha, y esta herramienta te entrega tres listas: lo que se añadió, lo que se eliminó y qué campos existentes cambiaron de tipo. Los esquemas se parsean según la especificación GraphQL de octubre de 2021, así que lo que la herramienta considera un "tipo" o un "campo" coincide con lo que tu servidor considera.
El diff es estructural, no textual. Reordenar campos dentro de un tipo es invisible. Reformatear el SDL es invisible. Renombrar un argumento aparece. Cambiar Int por Float en Order.total aparece. Nuevos valores de enum como OrderStatus.REFUNDED aparecen en adiciones. Eliminar un miembro de unión aparece en eliminaciones. El estilo de salida coincide con la categorización que usan GraphQL Inspector y Apollo schema checks, así que el flujo se traslada a esas herramientas cuando finalmente lleves la verificación a CI.
Todo corre en tu navegador. Sin subida, sin logs. Seguro para esquemas internos no publicados.
Cómo usar el diff de esquemas GraphQL
Pega, pega, lee. No hay botón Comparar — el diff se actualiza mientras escribes.
Pega el esquema antiguo en el panel A
Suelta el esquema de producción actual en el panel izquierdo etiquetado Esquema A (antiguo). Pulsa Subir para un archivo .graphql, .graphqls o .gql, o pulsa Ejemplo para cargar un par de inicio / iteración. El esquema no tiene que estar bonito — las diferencias de formato se ignoran.
Pega el nuevo esquema en el panel B
Suelta el esquema candidato (el del PR) en el panel derecho etiquetado Esquema B (nuevo). La herramienta tokeniza ambos esquemas, recorre cada definición de tipo y recalcula el diff una fracción de segundo después de que dejas de escribir. La semántica del parser de referencia sigue lo suficientemente cerca a graphql-js como para que lo que ves aquí sea lo que vería tu servidor.
Lee las tres listas
El panel inferior tiene tres secciones. Adiciones (verde) lista nuevos tipos, nuevos campos, nuevos valores de enum y nuevos miembros de unión. Eliminaciones (rojo) lista las mismas categorías a la inversa — suelen ser los cambios incompatibles, así que escanea esta lista primero. Cambios (ámbar) lista campos y argumentos cuyo tipo cambió, como Order.total: Int → Float. Si los esquemas son equivalentes, obtienes un único banner verde diciéndolo.
Cuándo usarlo de verdad
Revisión de PR
Un compañero abre un PR que añade cinco campos nuevos y renombra un argumento. El diff de GitHub es ilegible porque también pasó el esquema por un formateador. Pega ambas versiones aquí y obtén la lista real de cambios — normalmente de tres o cuatro elementos, no trescientos. Los revisores pueden discutir sobre la semántica real en lugar de discutir sobre la indentación.
Detectar cambios incompatibles
Eliminar un campo, estrechar un tipo de retorno o renombrar un argumento requerido son cambios incompatibles para los clientes en producción. Las listas de Eliminaciones y Cambios los muestran directamente. Ejecuta el diff antes de mergear para confirmar que el cambio incompatible es intencional. La misma verificación pertenece a CI eventualmente — consulta la documentación de Apollo schema checks para la versión productiva de este flujo.
Documentación de onboarding
Cuando un nuevo ingeniero pregunta "¿qué cambió el sprint pasado?", pega la versión del lunes y la del viernes en los paneles y copia el diff a tus notas de sprint. Más rápido que recorrer commits y mucho más legible.
Verificación de composición de federación
Después de ejecutar un compositor federado como Apollo Rover, pega el esquema compuesto anterior y el nuevo. El diff te dice si la composición captó el cambio que esperabas del PR del subgraph — o si algo cambió silenciosamente en otro lado.
Preguntas frecuentes
¿El diff detecta específicamente cambios incompatibles?
Cualquier cosa en las listas de Eliminaciones y Cambios es potencialmente incompatible — eliminar un campo, estrechar un tipo de retorno, renombrar un argumento. La herramienta no clasifica cada cambio como "incompatible" vs "no incompatible" como hace GraphQL Inspector, pero la lista estructurada deja claro cuáles mirar.
¿El orden de los campos cuenta como cambio?
No. Reordenar campos dentro de un tipo es estructuralmente idéntico y se ignora. Lo mismo para reordenar valores de enum, miembros de unión y argumentos. Solo se reportan elementos añadidos, eliminados o con tipo cambiado.
¿Qué pasa con descripciones y comentarios?
Las descripciones de tipo block-string y los comentarios se ignoran al comparar estructura. Añadir una descripción a un campo no aparece en el diff. Si quieres rastrear cambios de documentación, hazlo en el diff SDL formateado de tu PR, no aquí.
¿Mis esquemas se envían a un servidor?
No. El tokenizador y el diff corren completamente en tu navegador. Nada se sube, nada se loguea. Seguro para pegar esquemas internos o no publicados.
¿Qué tan grande puede ser el esquema que pego?
La página limita cada entrada a 5 MB. Más allá, el propio editor Ace empieza a ralentizarse. Esquemas de unos cientos de tipos no son problema.
¿Puedo correr esto en CI?
Para verificaciones locales antes de subir un PR, esta página sirve. Para puertas de CI que fallen el build ante un cambio incompatible, usa la CLI dedicada de GraphQL Inspector o Apollo schema checks — ambos tienen semántica adecuada de exit-code y configuración de políticas.
Otras herramientas GraphQL
Hacer diff es solo una parte de trabajar con GraphQL. Estas herramientas se encargan del resto: