01
Use a versão publicada como origem
O lado antigo é a referência. Trocar os lados refaz o cálculo: remoção vira adição, mudando também a leitura das quebras. Confirme a direção antes de levar contagens para um PR.
Documentos GraphQL
comparar schemas GraphQLrevisar o contrato antes da entrega
Cole o SDL completo já publicado à esquerda e a versão proposta à direita. A direção altera o significado de remoção e adição.
comparar schemas GraphQL
SDL do schema antigo
SDL do schema novo
Diferenças
Insira dois schemas SDL completos ou carregue o exemplo.
Os dois SDL são analisados neste navegador. Não há requisições à API, upload, histórico salvo nem conteúdo inserido na URL.
Opções
O GraphQL.js classifica quebras e riscos potenciais. Outras mudanças estruturais e de descontinuação aparecem separadamente, sem promessa de segurança.
Cada SDL aceita até 100.000 caracteres, 20.000 tokens e 100 níveis de aninhamento. A comparação para após 8 segundos.
Insira dois schemas SDL completos ou carregue o exemplo.
Ao comparar schemas GraphQL em uma revisão, um diff textual pode destacar recuos e declarações em outra ordem, mas esconder o que afeta os clientes. Campos, tipos e argumentos são o contrato que precisa ser lido.
O relatório separa estrutura de classificação de risco. GraphQL.js não sinaliza toda adição ou anotação @deprecated como quebra; mesmo assim essas mudanças continuam listadas para que “sem alerta” não seja confundido com prova de segurança.
Por que comparar schemas GraphQL neste fluxo
Ver alterações reais sem ruído de formatação.
Encontre o caminho afetado
Os dois textos SDL são construídos como schemas e comparados por caminho de tipo, campo e argumento. Ao comparar schemas GraphQL assim, mudar a ordem das definições não gera falso positivo, e o campo removido aparece com seu nome.
Separe risco e descontinuação
Um novo valor de enum pode surpreender um cliente com casos exaustivos. Adicionar @deprecated, porém, não apaga o campo. Ao comparar schemas GraphQL, as duas situações e as adições comuns aparecem em grupos distintos.
Confirme a direção e a versão do relatório
02
Controle a comparação automática
O padrão aguarda cerca de 350 ms após editar. Se for colar um SDL grande, desative o automático e acione Comparar ou Ctrl/Cmd+Enter quando as duas versões estiverem prontas.
03
Corrija antes de exportar
Qualquer edição deixa o relatório anterior desatualizado e bloqueia cópia e download. O erro aponta o lado e, quando possível, linha e coluna. A tela mostra mais itens por lote, mas o arquivo inclui todos.
Estrutura e risco no mesmo relatório
Diferenças por elemento GraphQL
Tipos, campos, argumentos, inputs, enums, unions e diretivas são comparados por estrutura. Espaços e ordem das definições não contam como mudança de contrato.
Regras oficiais visíveis
GraphQL.js fornece as categorias de quebra e risco potencial, acompanhadas do código da regra. O restante aparece como outra mudança estrutural, sem rótulo automático de segurança. Mudanças incompatíveis ficam separadas das que pedem apenas investigação.
Histórico de descontinuação
O motivo de @deprecated novo ou alterado ganha registro próprio. Remover de fato um campo já descontinuado continua sendo uma quebra nas regras padrão.
O que duas versões SDL não revelam
- Schemas completos são obrigatórios
- Um fragmento de tipo sem raiz Query ou referência a tipo ausente não é schema válido. Ao comparar schemas GraphQL, a análise para e mostra o lado com erro, em vez de apresentar uma lista vazia enganosa.
- Impacto real exige dados de clientes
- Quebra significa que operações antigas podem deixar de funcionar; o navegador não sabe quais clientes usam o campo. A classificação estática não substitui métricas de uso ou testes dos consumidores.
- Somente SDL local
- A ferramenta não consulta URL, não executa query ou mutation e não envia arquivo. Introspection JSON é outro formato e precisa ser convertido para SDL completo antes da análise.
- Renomear parece remover e adicionar
- Dois snapshots não trazem intenção de migração. Mesmo quando o campo antigo já tinha @deprecated, removê-lo continua sendo um evento de compatibilidade. Campos descontinuados ainda podem estar em uso por clientes antigos.
Dúvidas ao comparar schemas GraphQL
Permitir null em um argumento de mutation quebra a compatibilidade?
Permitir null em um argumento de mutation antes obrigatório normalmente amplia as entradas aceitas. GraphQL.js não trata essa direção como quebra; torná-lo obrigatório pode rejeitar chamadas antigas sem o argumento.
Adicionar um valor enum no GraphQL quebra a compatibilidade?
Acrescentar um valor enum é risco potencial. A consulta existente pode continuar válida, mas um cliente que enumera todos os valores conhecidos talvez não lide com o novo caso.
Como renomear um tipo GraphQL sem quebrar clientes?
As duas versões SDL não indicam a intenção de renomear. Ao comparar schemas GraphQL, o tipo antigo aparece removido e o novo aparece adicionado; uma transição gradual precisa ser planejada na API.
É possível descontinuar uma mutation GraphQL?
Mutation é um campo do tipo raiz Mutation e pode receber @deprecated. A marca mantém chamadas antigas; a remoção posterior ainda é classificada como quebra pelas regras padrão.
Tornar nullable um campo não nulo quebra a compatibilidade?
Mudar uma resposta non-null para nullable altera suposições de clientes gerados e o GraphQL.js classifica isso como quebra. No sentido inverso, teste se o resolver nunca retorna null.
Seu documento gerou um resultado inesperado?
Comece a comparar schemas GraphQL antes da entrega
Coloque as duas versões SDL lado a lado, leia os riscos e demais mudanças e exporte o relatório atual.