JSON Toolkit

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.

Intermediário~6 min de leituraPublicado em 2026-11-13Atualizado em 2026-11-13
Diagrama ilustrando a validação de arquivos de configuração YAML com JSON 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_load sem erro prova apenas que o arquivo é um YAML legal. Não prova que country: NO ainda é uma string — sob um parser YAML 1.1, já virou false muito 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:

  1. Fazer parse do arquivo YAML em objetos/arrays;
  2. Carregar o JSON Schema;
  3. 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

  1. A deriva de versão do parser acontece no parse. O schema vê o resultado do parse: o NO lido pelo PyYAML já é false, e o schema só consegue prender esse valor errado com type/pattern. O remédio de fundo continuam sendo as aspas; não espere que um schema repare um parser.
  2. 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.
  3. 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-duplicates do 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.