Validar YAML com JSON Schema: a rede de segurança dos arquivos de configuração
Resumo: Um arquivo YAML que faz parse sem erro não é um arquivo correto: country: NO não é uma string para um parser YAML 1.1, e version: 1.10 vira silenciosamente o float 1.1. Este guia explica por que o JSON Schema pode validar YAML, os caminhos de CLI e editor para implantar, como um schema teria detectado o incidente real do código de país norueguês, e as três limitações da validação por schema.

Conclusão: YAML 1.2 é um superconjunto estrito de JSON, então o JSON Schema valida a estrutura de dados após o parse, não o formato do arquivo — escreva o schema uma vez e ele cobre tanto os dados JSON quanto os YAML. É exatamente por isso que ele consegue interceptar incidentes em que o parser muda o tipo silenciosamente.
Um
yaml.safe_loadsem erro prova apenas que o arquivo é um YAML legal. Não prova quecountry: NOainda é uma string — sob um parser YAML 1.1, já viroufalsemuito antes de o seu código ver o arquivo.
Um: parse sem erro ≠ configuração correta — primeiro, um incidente real
Uma equipe de e-commerce adicionou a Noruega aos países de entrega: uma linha, NO, numa lista nas group_vars do Ansible. Revisado, validado, implantado. Uma semana depois: zero pedidos noruegueses — o arquivo JSON nos servidores continha "DK", false, "SE". O Ansible faz parse de seus arquivos de variáveis com PyYAML, um parser YAML 1.1: NO virou o booleano false já na leitura do arquivo, e o filtro to_json escreveu fielmente. O template renderizou, o JSON era válido, ninguém reclamou — só o serviço de checkout continuava recusando todo cliente norueguês, pois NO não estava na lista.
O ponto comum desses incidentes: todas as ferramentas sintáticas estão verdes enquanto a camada de dados já está errada. A tabela abaixo mostra a deriva de tipos medida com PyYAML 6.0.3; os parsers YAML 1.2 corrigem apenas parte:
| Você escreve | YAML 1.1 lê | YAML 1.2 lê | Você queria |
|---|---|---|---|
country: NO |
false |
"NO" |
"NO" |
version: 1.10 |
float 1.1 |
float 1.1 |
"1.10" |
zip: 02134 |
octal 1116 |
decimal 2134 |
"02134" |
mode: 0755 |
decimal 493 |
decimal 755 |
493 ou "0755" |
ports: ["22:22"] |
sexagesimal 1342 |
"22:22" |
"22:22" |
O remédio de fundo é colocar aspas em toda string que pareça código. Mas as aspas dependem da memória humana; um schema depende da verificação pela máquina — é por isso que o YAML merece um JSON Schema.
Dois: por que o JSON Schema pode governar o YAML
A especificação YAML 1.2 diz claramente: o objetivo principal da 1.2 foi tornar o YAML um superconjunto estrito de JSON, e um parser 1.2 lê JSON comum sem alteração. Os dois formatos fazem parse para as mesmas estruturas de dados, logo a extensão do arquivo não tem significado para um validador. O pipeline inteiro são três passos:
- Fazer parse do arquivo YAML em objetos/arrays;
- Carregar o JSON Schema;
- Validar os dados contra o schema — erros ou passagem.
Note que o passo um não exige serializar o YAML em texto JSON e fazer parse de novo; a biblioteca YAML da sua linguagem passa a estrutura direto ao validador. O próprio schema também pode ser escrito em YAML (yq -P schema.json > schema.yaml converte em um comando), mas mantê-lo em JSON é a escolha mais segura: a compatibilidade de ferramentas é melhor e todos os schemas do catálogo schemastore.org estão em JSON.
Três: três caminhos de CLI que funcionam hoje
Tomemos um config.yaml em que o schema exige name e version, impõe o formato semver e countries como array de strings de duas letras maiúsculas:
# config.yaml
name: checkout
version: "1.4.2"
countries:
- DK
- NO
- SE
Python (jsonschema + PyYAML):
import json, yaml
from jsonschema import validate
data = yaml.safe_load(open("config.yaml", encoding="utf-8"))
schema = json.load(open("schema.json", encoding="utf-8"))
validate(instance=data, schema=schema)
Node (js-yaml + Ajv):
import Ajv from "ajv";
import yaml from "js-yaml";
import fs from "fs";
const schema = JSON.parse(fs.readFileSync("schema.json", "utf8"));
const data = yaml.load(fs.readFileSync("config.yaml", "utf8"));
const validate = new Ajv().compile(schema);
if (!validate(data)) console.error(validate.errors);
Pipeline pura (yq + ajv-cli):
yq -o=json config.yaml | ajv validate -s schema.json -d -
# Ou check-jsonschema, que consome YAML diretamente
pip install check-jsonschema
check-jsonschema --schemafile schema.json config.yaml
Os três caminhos diferem apenas no passo de parse: os dois primeiros são explícitos em duas linhas, o pipeline passa num fluxo só, e o check-jsonschema faz a conversão YAML→JSON internamente. O arquivo de schema é o mesmo para os três.
Quatro: validação em tempo real no editor: modeline e SchemaStore
A extensão YAML da Red Hat (baseada no yaml-language-server) tem cerca de 30 milhões de instalações no VS Code e suporta JSON Schema draft-04/07/2019-09/2020-12. Três formas de conectá-la:
# Opção 1: a modeline — a primeira linha do arquivo aponta para o schema
# yaml-language-server: $schema=./schema.json
name: checkout
// Opções 2 e 3: .vscode/settings.json, por nome de arquivo ou glob
{
"yaml.schemas": {
"./schema.json": ["config/*.yaml", "*.config.yaml"],
"https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
}
}
yaml.schemaStore.enable vem ativado por padrão: arquivos comuns como package.json, workflows do GitHub ou docker-compose são vinculados automaticamente ao catálogo schemastore.org, sem nenhuma configuração. Os campos description do schema viram auxílios de autocompletar e tooltips, e as propriedades required ausentes ficam sublinhadas em vermelho — os erros de configuração passam de "debug depois do deploy" para "no instante em que você digita". Isso também explica por que SchemaStore e não uma "norma de schema para YAML": o YAML não tem um padrão oficial de schema, e o JSON Schema é o padrão de fato.
Cinco: como um schema teria detectado o problema norueguês
Voltemos ao incidente do NO da primeira seção. Dêmos a countries um schema no nível dos elementos:
{
"type": "object",
"required": ["name", "version", "countries"],
"properties": {
"countries": {
"type": "array",
"items": { "type": "string", "pattern": "^[A-Z]{2}$" }
}
}
}
O false produzido pelo PyYAML não é uma string, então type: string falha imediatamente; mesmo que um parser o tivesse lido como "no" em minúsculas, o pattern barraria. Para ir além, adicione uma allowlist enum. O mesmo schema roda em CI pelos caminhos de CLI da seção três e no editor pela modeline da seção quatro — um único contrato nas duas pontas.
A divisão de trabalho com o yamllint merece uma frase: a regra truthy do yamllint (só true/false aceitos, qualquer outra grafia booleana é sinalizada) governa o estilo de escrita e intercepta flag: yes na camada de lint; o JSON Schema governa a forma dos dados, independente do parser. A equipe do incidente acabou adotando os três: aspas nas strings, yamllint truthy no pipeline e a asserção de strings de duas letras no template. As duas camadas de defesa não se sobrepõem; elas se complementam.
Seis: validação em lote dos manifestos Kubernetes
A própria API do Kubernetes é descrita em OpenAPI, e o projeto kubernetes-json-schema a converte em JSON Schema padrão. O Kubeconform usa esse registro para validação em lote: num notebook de 4 núcleos, 35.139 arquivos e 50.714 recursos com kubeconform -ignore-missing-schemas -n 8 -summary terminam em 6,7 segundos, contra 35 segundos do kubeval na mesma tarefa. O gesto Helm padrão é renderizar primeiro, validar depois:
helm template my-app ./charts/my-app > rendered.yaml
kubeconform -strict -summary -kubernetes-version 1.28.0 rendered.yaml
-strict rejeita campos não definidos pelo schema (os erros de digitação aparecem cedo); recursos CRD podem ser ignorados com -ignore-missing-schemas ou servidos por um registro personalizado via -schema-location.
Sete: o que a validação por schema não pode fazer: três limites
- A deriva de versão do parser acontece no parse. O schema vê o resultado do parse: o
NOlido pelo PyYAML já éfalse, e o schema só consegue prender esse valor errado comtype/pattern. O remédio de fundo continuam sendo as aspas; não espere que um schema repare um parser. - Erros lógicos estão fora do perímetro. Um erro de digitação em um selector ou um selector K8s apontando para um label inexistente — o schema conhece formas, não semântica. Isso é terreno de admission webhooks, políticas OPA ou
kubectl apply --dry-run=server. - Chaves duplicadas ganham em silêncio. Muitos parsers YAML aceitam chaves duplicadas sem aviso (a última vence), então o schema recebe dados que já perderam uma chave. A regra
key-duplicatesdo yamllint ou hooks de parse continuam sendo os detectores.
Checklist antes do deploy: aspas nas strings que parecem código → rodar yamllint (truthy + key-duplicates) → validação JSON Schema tanto na CI quanto no editor → para recursos de cluster, passar também --dry-run=server. Com esses quatro passos, o incidente norueguês da seção um não sobrevive ao segundo passo do pipeline.
FAQ
O JSON Schema pode validar arquivos YAML diretamente?
Sim — mas ele valida os dados nos quais o arquivo faz parse, não o próprio arquivo. YAML 1.2 é um superconjunto estrito de JSON, ambos fazem parse para as mesmas estruturas, então um único schema serve para JSON e YAML. Escolha um dos quatro caminhos — Python, Node, o pipeline yq ou check-jsonschema — sem converter formatos à mão.
O que é SchemaStore e como usá-lo?
schemastore.org é um catálogo de JSON Schemas (catalog.json) que reúne schemas de centenas de arquivos de configuração comuns: package.json, workflows do GitHub, docker-compose etc. Editores com suporte a YAML/JSON vinculam automaticamente os arquivos a esse catálogo, ou você pode mapear as URLs manualmente em yaml.schemas. Você também pode submeter o schema do seu próprio projeto ao catálogo.
yamllint e JSON Schema se sobrepõem?
Não. O yamllint verifica o estilo de escrita (indentação, comprimento de linha, truthy, chaves duplicadas) no nível de texto; o JSON Schema verifica a estrutura dos dados (tipos, required, enums, patterns) no nível dos dados. A lista de correções do incidente norueguês usou ambos: a regra truthy intercepta grafias como flag: yes, enquanto o schema intercepta um false que parou num array de strings.
Para Kubernetes: kubeconform ou kubectl dry-run?
Dois ofícios diferentes. O Kubeconform é offline e em lote, sem cluster, e tem lugar na CI para pegar erros estruturais; o dry-run=server conversa com um servidor de API real e revela problemas de admission webhook e quotas, mas exige acesso ao cluster. A combinação padrão: kubeconform na CI e depois uma passada --dry-run=server antes do deploy — mantenha as duas camadas.
Depois de escrever seu schema, cole o JSON convertido do seu YAML no validador JSON online para ver os erros primeiro; para escrever as palavras-chave do schema, veja o guia de JSON Schema; para manter um schema vigiado por testes na CI, leia o teste de contrato JSON Schema; para a conversão diária de JSON↔YAML, use o conversor JSON YAML XML.