Entrada

Validação

Cole um schema GraphQL à esquerda para ver os resultados da validação aqui.

O que é o Validador GraphQL?

Um schema que volta de um composer de federação, de um gerador de código ou de uma edição manual durante uma revisão quase sempre tem pelo menos um problema de sintaxe na primeira passada. Um } sobrando, uma string de descrição não terminada, um corpo de enum cortado quando alguém colou meia tela de SDL num chat — e quando você vê, a inicialização do seu Apollo Server explode com um erro de parser apontando para a linha 1, que raramente é onde está o problema real. Este validador percorre o SDL token por token e aponta para a linha verdadeira.

Ele verifica regras estruturais da especificação GraphQL de outubro de 2021: cada {, ( e [ precisa de um fechador correspondente do tipo certo; descrições escritas como """...""" têm que ser terminadas; strings entre aspas dentro de argumentos precisam fechar na mesma linha. O validador NÃO verifica semântica — ele não vai te dizer que Query está faltando ou que um campo referencia um tipo não declarado. Para isso, passe o schema pela implementação de referência graphql-js. O que esta página faz bem é a passada de sintaxe e o bloco de stats, para você ver de relance se o schema que acabou de colar tem 14 tipos ou 4, 187 campos ou 12.

Tudo roda no seu navegador. Sem upload, nenhum schema é guardado em lugar nenhum. Cole, valide, copie.

Como usar o Validador GraphQL

Três passos rápidos. Os botões abaixo correspondem aos botões reais desta página.

Cole, envie ou carregue um exemplo

Cole um schema GraphQL no painel Entrada à esquerda — a validação roda automaticamente uma fração de segundo depois de você parar de digitar, então não há botão Validar. Clique em Enviar para um arquivo .graphql, .graphqls ou .gql, ou em Exemplo para carregar um schema de Order de e-commerce realista. Uma colagem típica fica assim:

type Order { id: ID! placedAt: DateTime! customer: Customer! items: [OrderItem!]! status: OrderStatus! } enum OrderStatus { PENDING PAID SHIPPED }

Tanto schemas no estilo servidor (com extend type Query) quanto arquivos de tipos isolados funcionam. Comentários (#) e descrições em string de bloco ("""...""") são tratados do mesmo jeito que a documentação learn-schema do GraphQL descreve.

Leia o bloco de stats

O painel direito mostra um banner verde se o schema parsear limpinho, um vermelho se não — e em qualquer dos casos você ganha um detalhamento de quantas definições de type, interface, enum, input, union, scalar e directive o schema declara, mais o total de campos, argumentos e descrições. Útil pra checar a sanidade de um merge de federação ou comparar duas revisões do mesmo schema. As contagens espelham o que a especificação GraphQL do Relay chama de partes estruturais de uma definição.

Conserte e cole de novo

Se o schema for inválido, o banner te diz a linha exata da chave desbalanceada ou da string não terminada. Conserta, cola de volta, vê o banner ficar verde. O botão Copiar à direita te dá um pequeno relatório JSON de stats que você pode jogar na descrição de um PR ou numa mensagem de chat — útil quando você quer mostrar pra um colega "sim, o schema tá ok, aqui estão as stats" sem compartilhar o SDL em si.

Quando você usaria isso de verdade

Checagem antes do merge

Antes de mergear uma mudança no gateway de federação ou uma atualização de schema-stitching, cole o schema composto aqui. Se o balanço de chaves estiver torto ou uma descrição não fechar, você vê em dois segundos em vez de num CI quebrando dez minutos depois. Combina bem com o comando rover subgraph check pro lado semântico.

Diff de duas revisões

Cole a versão A, anote os números de stats (28 tipos, 142 campos, 6 enums). Cole a versão B e compare. Se a contagem de campos pulou em 40 mas só um tipo novo foi adicionado, alguém provavelmente duplicou um fragment. O bloco de stats é muito mais rápido do que rolar um diff de 2000 linhas.

Onboarding de um novo terceirizado

Entregue o arquivo do schema, aponte essa página e diga "se ficar vermelho, sua colagem tá quebrada; se a contagem de campos cair de repente em 800, você só copiou metade." Evita o vai-e-vem do "isso é tudo?" antes mesmo de começarem a escrever resolvers.

Colagem do chat

Slack e Discord adoram detonar backticks e aspas quando quebram mensagens longas, então um schema que alguém colou numa thread frequentemente perde uma ou duas chaves de fechamento. Joga aqui primeiro pra descobrir antes de abrir na sua IDE.

Perguntas frequentes

Ele valida semântica, ou só sintaxe?

Só sintaxe — balanço de chaves, terminação de strings e uma passada de stats sobre o stream de tokens. Ele NÃO checa se Query existe, se os tipos referenciados estão definidos, se argumentos batem com suas definições de diretiva ou se o tipo de um campo é válido. Pra validação semântica completa, use a biblioteca de referência graphql-js ou as checagens de inicialização do seu servidor.

Meu schema é enviado pra um servidor?

Não. A validação roda inteiramente no seu navegador. Nada é enviado, nada é registrado. Pode colar schemas internos ou não publicados sem medo.

Que problemas de sintaxe ele realmente pega?

{ / ( / [ sem par com o número da linha onde estava o abridor, fechadores trocados como ) onde se esperava }, "strings" ou """block strings""" não terminadas e caracteres soltos que não fazem parte da gramática de tokens GraphQL.

Por que meu schema mostra 0 tipos quando claramente tem tipos?

O contador de stats só conta uma definição quando tanto a palavra-chave (type, interface etc.) QUANTO as chaves do corpo estão presentes. Se você colou um schema cortado no meio de um tipo, a contagem desse tipo fica em 0 até você terminar o corpo. O banner do validador também vai estar vermelho nesse caso, apontando para o abridor sem par.

Ele entende descrições em string de bloco?

Sim. """An order placed by a customer.""" é reconhecido como um token de descrição e contado na stat Descrições. O validador não impõe onde as descrições aparecem — isso é uma escolha de estilo — mas a contagem te dá uma leitura rápida de quão documentado está o schema.

Que tamanho de schema posso colar?

Qualquer um que seu navegador renderize confortavelmente. Schemas com algumas centenas de tipos e vários milhares de campos validam bem abaixo de um segundo. Acima de 5 MB o próprio editor Ace começa a engasgar, que é o gargalo — não o validador.

Outras ferramentas GraphQL

A validação é só uma parte do trabalho com GraphQL. Estas ferramentas cuidam do resto: