Validar YAML con JSON Schema: la red de seguridad de los archivos de configuración
En resumen: Un archivo YAML que parsea sin errores no es un archivo correcto: country: NO no es una cadena para un parser YAML 1.1, y version: 1.10 se convierte silenciosamente en el float 1.1. Esta guía explica por qué JSON Schema puede validar YAML, los caminos de CLI y editor para implantarlo, cómo un schema habría interceptado el incidente real del código de país noruego, y las tres limitaciones de la validación por schema.

Conclusión: YAML 1.2 es un superconjunto estricto de JSON, así que JSON Schema valida la estructura de datos tras el parseo, no el formato del archivo — escribe el schema una vez y cubre tanto los datos JSON como los YAML. Es exactamente por eso que puede interceptar incidentes en los que el parser cambia el tipo silenciosamente.
Un
yaml.safe_loadsin errores demuestra que el archivo es YAML legal. No demuestra quecountry: NOsiga siendo una cadena — bajo un parser YAML 1.1 ya esfalsemucho antes de que tu código vea el archivo.
Uno: parsear sin errores ≠ configuración correcta — primero, un incidente real
Un equipo de e-commerce añadió Noruega a sus países de entrega: una línea, NO, en una lista dentro de las group_vars de Ansible. Revisado, validado, desplegado. Una semana después: cero pedidos noruegos — el archivo JSON en los servidores contenía "DK", false, "SE". Ansible parsea sus archivos de variables con PyYAML, un parser YAML 1.1: NO era el booleano false desde la lectura del archivo, y el filtro to_json lo escribió fielmente. La plantilla renderizó, el JSON era válido, nadie se quejó — solo el servicio de checkout seguía rechazando a cada cliente noruego porque NO no estaba en la lista.
El punto común de estos incidentes: todas las herramientas sintácticas están en verde mientras la capa de datos ya está mal. La tabla siguiente muestra la deriva de tipos medida con PyYAML 6.0.3; los parsers YAML 1.2 corrigen solo una parte:
| Escribes | YAML 1.1 lee | YAML 1.2 lee | Querías |
|---|---|---|---|
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 o "0755" |
ports: ["22:22"] |
sexagesimal 1342 |
"22:22" |
"22:22" |
El remedio de fondo es poner comillas en toda cadena que parezca código. Pero las comillas dependen de la memoria humana; un schema depende de la verificación por la máquina — por eso el YAML merece un JSON Schema.
Dos: por qué JSON Schema puede gobernar el YAML
La especificación YAML 1.2 lo dice claramente: el objetivo principal de la 1.2 fue hacer de YAML un superconjunto estricto de JSON, y un parser 1.2 lee JSON ordinario sin cambios. Ambos formatos parsean a las mismas estructuras de datos, así que la extensión del archivo no significa nada para un validador. El pipeline completo son tres pasos:
- Parsear el archivo YAML a objetos/arrays;
- Cargar el JSON Schema;
- Validar los datos contra el schema — errores o aprobado.
Fíjate en que el paso uno no exige serializar el YAML a texto JSON y parsearlo otra vez; la librería YAML de tu lenguaje pasa la estructura directamente al validador. El propio schema también puede escribirse en YAML (yq -P schema.json > schema.yaml lo convierte en un comando), pero mantenerlo en JSON es la elección más segura: la compatibilidad de herramientas es mejor y todos los schemas del catálogo schemastore.org están en JSON.
Tres: tres caminos de CLI que funcionan hoy
Tomemos un config.yaml en el que el schema exige name y version, impone la forma semver y countries como array de cadenas de dos letras mayú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 -
# O check-jsonschema, que consume YAML directamente
pip install check-jsonschema
check-jsonschema --schemafile schema.json config.yaml
Los tres caminos solo difieren en el paso de parseo: los dos primeros son explícitos en dos líneas, el pipeline pasa en un flujo, y check-jsonschema hace la conversión YAML→JSON internamente. El archivo de schema es el mismo para los tres.
Cuatro: validación en tiempo real en el editor: modeline y SchemaStore
La extensión YAML de Red Hat (basada en yaml-language-server) suma unos 30 millones de instalaciones en VS Code y soporta JSON Schema draft-04/07/2019-09/2020-12. Tres formas de conectarla:
# Opción 1: la modeline — la primera línea del archivo apunta al schema
# yaml-language-server: $schema=./schema.json
name: checkout
// Opciones 2 y 3: .vscode/settings.json, por nombre de archivo o glob
{
"yaml.schemas": {
"./schema.json": ["config/*.yaml", "*.config.yaml"],
"https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
}
}
yaml.schemaStore.enable está activo por defecto: archivos comunes como package.json, los workflows de GitHub o docker-compose se asocian automáticamente al catálogo schemastore.org, sin ninguna configuración. Los campos description del schema se convierten en ayudas de autocompletado y tooltips, y las propiedades required ausentes se subrayan en rojo — los errores de configuración pasan de "debug después del deploy" a "en el instante en que escribes". Esto también explica por qué SchemaStore y no una "norma de schemas para YAML": YAML no tiene un estándar oficial de schemas, y JSON Schema es el estándar de facto.
Cinco: cómo un schema habría interceptado el problema noruego
Volvamos al incidente del NO de la primera sección. Demos a countries un schema a nivel de elementos:
{
"type": "object",
"required": ["name", "version", "countries"],
"properties": {
"countries": {
"type": "array",
"items": { "type": "string", "pattern": "^[A-Z]{2}$" }
}
}
}
El false que produce PyYAML no es una cadena, así que type: string falla de inmediato; aunque un parser lo hubiera leído como "no" en minúsculas, el pattern lo bloquea. Para ir más lejos, añade una lista blanca enum. El mismo schema corre en CI por los caminos de CLI de la sección tres y en el editor por la modeline de la sección cuatro — un único contrato en ambos extremos.
La división del trabajo con yamllint merece una frase: la regla truthy de yamllint (solo se aceptan true/false, cualquier otra grafia booleana se señala) gobierna el estilo de escritura e intercepta flag: yes en la capa de lint; JSON Schema gobierna la forma de los datos, sea cual sea el parser. El equipo del incidente acabó adoptando los tres: comillas en las cadenas, yamllint truthy en el pipeline y la aserción de cadenas de dos letras en la plantilla. Las dos capas de defensa no se solapan; se complementan.
Seis: validación en lote de manifiestos Kubernetes
La propia API de Kubernetes está descrita en OpenAPI, y el proyecto kubernetes-json-schema la convierte en JSON Schema estándar. Kubeconform usa ese registro para la validación en lote: en un portátil de 4 núcleos, 35.139 archivos y 50.714 recursos con kubeconform -ignore-missing-schemas -n 8 -summary terminan en 6,7 segundos, frente a 35 segundos de kubeval en la misma tarea. El gesto Helm estándar es renderizar primero, validar después:
helm template my-app ./charts/my-app > rendered.yaml
kubeconform -strict -summary -kubernetes-version 1.28.0 rendered.yaml
-strict rechaza los campos que el schema no define (los errores tipográficos se ven pronto); los recursos CRD se pueden ignorar con -ignore-missing-schemas o servir de un registro personalizado vía -schema-location.
Siete: lo que la validación por schema no puede hacer: tres límites
- La deriva de versión del parser ocurre en el parseo. El schema ve el resultado del parseo: el
NOleído por PyYAML ya esfalse, y el schema solo puede encerrar ese valor errado contype/pattern. El remedio de fondo siguen siendo las comillas; no esperes que un schema repare un parser. - Los errores lógicos están fuera del perímetro. Un error tipográfico en un selector o un selector K8s que apunta a un label inexistente — el schema conoce formas, no semántica. Eso es terreno de admission webhooks, políticas OPA o
kubectl apply --dry-run=server. - Las claves duplicadas ganan en silencio. Muchos parsers YAML aceptan claves duplicadas sin aviso (la última gana), así que el schema recibe datos que ya perdieron una clave. La regla
key-duplicatesde yamllint o los hooks de parseo siguen siendo los detectores.
Checklist antes del deploy: comillas en las cadenas tipo código → ejecutar yamllint (truthy + key-duplicates) → validación JSON Schema tanto en CI como en el editor → para recursos de clúster, pasar también --dry-run=server. Con estos cuatro pasos, el incidente noruego de la sección uno no sobrevive al segundo paso del pipeline.
FAQ
¿Puede JSON Schema validar archivos YAML directamente?
Sí — pero valida los datos en los que el archivo parsea, no el propio archivo. YAML 1.2 es un superconjunto estricto de JSON, ambos parsean a las mismas estructuras, así que un único schema sirve para JSON y YAML. Elige uno de los cuatro caminos — Python, Node, el pipeline yq o check-jsonschema — sin convertir formatos a mano.
¿Qué es SchemaStore y cómo se usa?
schemastore.org es un catálogo de JSON Schemas (catalog.json) que reúne schemas de cientos de archivos de configuración comunes: package.json, workflows de GitHub, docker-compose, etc. Los editores con soporte YAML/JSON asocian automáticamente los archivos a ese catálogo, o puedes mapear las URLs manualmente en yaml.schemas. También puedes enviar el schema de tu propio proyecto al catálogo.
¿Se solapan yamllint y JSON Schema?
No. yamllint comprueba el estilo de escritura (indentación, longitud de línea, truthy, claves duplicadas) a nivel de texto; JSON Schema comprueba la estructura de los datos (tipos, required, enums, patterns) a nivel de datos. La lista de correcciones del incidente noruego usó ambos: la regla truthy intercepta grafías como flag: yes, mientras que el schema intercepta un false que acabó en un array de cadenas.
Para Kubernetes: ¿kubeconform o kubectl dry-run?
Dos oficios distintos. Kubeconform es offline y en lote, sin clúster, y su lugar está en la CI para atrapar errores estructurales; dry-run=server habla con un servidor de API real y revela problemas de admission webhook y de quotas, pero exige acceso al clúster. La combinación estándar: kubeconform en la CI y luego una pasada --dry-run=server antes del deploy — mantén las dos capas.
Después de escribir tu schema, pega el JSON convertido de tu YAML en el validador JSON online para ver los errores primero; para escribir las palabras clave del schema, consulta la guía de JSON Schema; para mantener un schema vigilado por tests en CI, lee el testing de contratos JSON Schema; para la conversión diaria JSON↔YAML, usa el conversor JSON YAML XML.