JSON Toolkit

Validare YAML con JSON Schema: la rete di sicurezza dei file di configurazione

In sintesi: Un file YAML che fa parse senza errori non è un file corretto: country: NO non è una stringa per un parser YAML 1.1, e version: 1.10 diventa silenziosamente il float 1.1. Questa guida spiega perché JSON Schema può validare il YAML, le vie CLI ed editor per impostarlo, come uno schema avrebbe intercettato il vero incidente del codice paese norvegese, e le tre limitazioni della validazione tramite schema.

Intermedio~6 min di letturaPubblicato il 2026-11-13Aggiornato il 2026-11-13
Schema che illustra la validazione dei file di configurazione YAML con JSON Schema

Conclusione: YAML 1.2 è un superinsieme stretto di JSON, quindi JSON Schema valida la struttura dei dati dopo il parse, non il formato del file — scrivi lo schema una volta e copre sia i dati JSON sia quelli YAML. È esattamente per questo che riesce a intercettare gli incidenti in cui il parser cambia il tipo in silenzio.

Un yaml.safe_load senza errori prova solo che il file è YAML legale. Non prova che country: NO sia ancora una stringa — sotto un parser YAML 1.1 è già false molto prima che il tuo codice veda il file.

Uno: parse senza errori ≠ configurazione corretta — prima, un incidente reale

Un team e-commerce ha aggiunto la Norvegia ai paesi di consegna: una riga, NO, in una lista dentro le group_vars di Ansible. Revisionato, validato, deployato. Una settimana dopo: zero ordini norvegesi — il file JSON sui server conteneva "DK", false, "SE". Ansible fa il parse dei suoi file di variabili con PyYAML, un parser YAML 1.1: NO era il booleano false già alla lettura del file, e il filtro to_json l'ha scritto fedelmente. Il template si è renderizzato, il JSON era valido, nessuno si è lamentato — solo il servizio checkout continuava a rifiutare ogni cliente norvegese perché NO non era nella lista.

Il punto comune di questi incidenti: tutti gli strumenti sintattici sono verdi mentre lo strato dati è già sbagliato. La tabella qui sotto mostra la deriva dei tipi misurata con PyYAML 6.0.3; i parser YAML 1.2 ne correggono solo una parte:

Scrivi YAML 1.1 legge YAML 1.2 legge Volevi
country: NO false "NO" "NO"
version: 1.10 float 1.1 float 1.1 "1.10"
zip: 02134 ottale 1116 decimale 2134 "02134"
mode: 0755 decimale 493 decimale 755 493 o "0755"
ports: ["22:22"] sessagesimale 1342 "22:22" "22:22"

Il rimedio di fondo è mettere le virgolette su ogni stringa che sembra codice. Ma le virgolette poggiano sulla memoria umana; uno schema poggia sulla verifica della macchina — ecco perché il YAML merita un JSON Schema.

Due: perché JSON Schema può governare il YAML

La specifica YAML 1.2 lo dice chiaramente: l'obiettivo principale della 1.2 era rendere YAML un superinsieme stretto di JSON, e un parser 1.2 legge JSON ordinario senza modifiche. I due formati fanno parse verso le stesse strutture dati, quindi l'estensione del file non significa nulla per un validatore. L'intera pipeline sono tre passi:

  1. Fare il parse del file YAML in oggetti/array;
  2. Caricare il JSON Schema;
  3. Validare i dati contro lo schema — errori o passaggio.

Nota che il passo uno non richiede di serializzare il YAML in testo JSON e fare di nuovo il parse; la libreria YAML del tuo linguaggio passa la struttura direttamente al validatore. Lo schema stesso si può anche scrivere in YAML (yq -P schema.json > schema.yaml lo converte in un comando), ma tenerlo in JSON è la scelta più sicura: la compatibilità degli strumenti è migliore e tutti gli schemi del catalogo schemastore.org sono JSON.

Tre: tre vie CLI che funzionano già oggi

Prendiamo un config.yaml in cui lo schema esige name e version, impone la forma semver e countries come array di stringhe di due lettere maiuscole:

# 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 -
# Oppure check-jsonschema, che consuma YAML direttamente
pip install check-jsonschema
check-jsonschema --schemafile schema.json config.yaml

Le tre vie differiscono solo nel passo di parse: le prime due sono esplicite in due righe, la pipeline passa in un unico flusso, e check-jsonschema fa la conversione YAML→JSON internamente. Il file di schema è lo stesso per tutte e tre.

Quattro: validazione in tempo reale nell'editor: modeline e SchemaStore

L'estensione YAML di Red Hat (basata su yaml-language-server) conta circa 30 milioni di installazioni su VS Code e supporta JSON Schema draft-04/07/2019-09/2020-12. Tre modi per collegarla:

# Opzione 1: la modeline — la prima riga del file punta allo schema
# yaml-language-server: $schema=./schema.json
name: checkout
// Opzioni 2 e 3: .vscode/settings.json, per nome file o glob
{
  "yaml.schemas": {
    "./schema.json": ["config/*.yaml", "*.config.yaml"],
    "https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
  }
}

yaml.schemaStore.enable è attivo di default: i file comuni come package.json, i workflow GitHub o docker-compose vengono associati automaticamente al catalogo schemastore.org, senza alcuna configurazione. I campi description dello schema diventano aiuti di autocompletamento e tooltip, e le proprietà required mancanti vengono sottolineate in rosso — gli errori di configurazione passano da "debug dopo il deploy" a "nell'istante in cui digiti". Questo spiega anche perché SchemaStore e non una "norma di schemi per YAML": YAML non ha uno standard ufficiale di schemi, e JSON Schema è lo standard de facto.

Cinque: come uno schema avrebbe intercettato il problema norvegese

Torniamo all'incidente del NO della prima sezione. Diamo a countries uno schema a livello di elemento:

{
  "type": "object",
  "required": ["name", "version", "countries"],
  "properties": {
    "countries": {
      "type": "array",
      "items": { "type": "string", "pattern": "^[A-Z]{2}$" }
    }
  }
}

Il false prodotto da PyYAML non è una stringa, quindi type: string fallisce subito; anche se un parser l'avesse letto come "no" in minuscolo, il pattern lo blocca. Per andare oltre, aggiungi una whitelist enum. Lo stesso schema gira in CI tramite le vie CLI della sezione tre e nell'editor tramite la modeline della sezione quattro — un unico contratto alle due estremità.

La divisione del lavoro con yamllint merita una frase: la regola truthy di yamllint (accettati solo true/false, ogni altra ortografia booleana viene segnalata) governa lo stile di scrittura e intercetta flag: yes al livello di lint; JSON Schema governa la forma dei dati, qualunque sia il parser. Il team dell'incidente ha finito per adottare tutti e tre: virgolette sulle stringhe, yamllint truthy nella pipeline e l'asserzione di stringhe di due lettere nel template. I due strati di difesa non si sovrappongono; si completano.

Sei: validazione in batch dei manifesti Kubernetes

L'API Kubernetes stessa è descritta in OpenAPI, e il progetto kubernetes-json-schema la converte in JSON Schema standard. Kubeconform usa questo registro per la validazione in batch: su un laptop a 4 core, 35.139 file e 50.714 risorse con kubeconform -ignore-missing-schemas -n 8 -summary si completano in 6,7 secondi, contro 35 secondi di kubeval sullo stesso compito. Il gesto Helm standard è rendere prima, validare dopo:

helm template my-app ./charts/my-app > rendered.yaml
kubeconform -strict -summary -kubernetes-version 1.28.0 rendered.yaml

-strict scarta i campi non definiti dallo schema (i refusi si vedono presto); le risorse CRD si possono ignorare con -ignore-missing-schemas o servire da un registro personalizzato via -schema-location.

Sette: cosa la validazione tramite schema non può fare: tre limiti

  1. La deriva di versione del parser avviene al parse. Lo schema vede il risultato del parse: il NO letto da PyYAML è già false, e lo schema può solo rinchiudere quel valore sbagliato con type/pattern. Il rimedio di fondo restano le virgolette; non aspettarti che uno schema ripari un parser.
  2. Gli errori logici sono fuori perimetro. Un refuso in un selector o un selector K8s che punta a un label inesistente — lo schema conosce le forme, non la semantica. È terreno di admission webhooks, policy OPA o kubectl apply --dry-run=server.
  3. Le chiavi duplicate vincono in silenzio. Molti parser YAML accettano chiavi duplicate senza avviso (vince l'ultima), quindi lo schema riceve dati che hanno già perso una chiave. La regola key-duplicates di yamllint o gli hook di parse restano i rilevatori.

Checklist prima del deploy: virgolette sulle stringhe tipo codice → lanciare yamllint (truthy + key-duplicates) → validazione JSON Schema sia in CI sia nell'editor → per le risorse di cluster, passare anche --dry-run=server. Con questi quattro passi, l'incidente norvegese della sezione uno non sopravvive al secondo passo della pipeline.

FAQ

JSON Schema può validare direttamente i file YAML?

Sì — ma valida i dati in cui il file fa parse, non il file stesso. YAML 1.2 è un superinsieme stretto di JSON, entrambi fanno parse verso le stesse strutture, quindi un solo schema serve per JSON e YAML. Scegli una delle quattro vie — Python, Node, la pipeline yq o check-jsonschema — senza convertire i formati a mano.

Cos'è SchemaStore e come si usa?

schemastore.org è un catalogo di JSON Schema (catalog.json) che raccoglie gli schemi di centinaia di file di configurazione comuni: package.json, workflow GitHub, docker-compose ecc. Gli editor con supporto YAML/JSON associano automaticamente i file a questo catalogo, oppure puoi mappare le URL manualmente in yaml.schemas. Puoi anche sottoporre lo schema del tuo progetto al catalogo.

yamllint e JSON Schema si sovrappongono?

No. yamllint verifica lo stile di scrittura (indentazione, lunghezza delle righe, truthy, chiavi duplicate) al livello del testo; JSON Schema verifica la struttura dei dati (tipi, required, enum, pattern) al livello dei dati. La lista di correzioni dell'incidente norvegese ha usato entrambi: la regola truthy intercetta ortografie come flag: yes, mentre lo schema intercetta un false finito in un array di stringhe.

Per Kubernetes: kubeconform o kubectl dry-run?

Due mestieri diversi. Kubeconform è offline e in batch, senza cluster, e il suo posto è in CI per beccare gli errori strutturali; dry-run=server parla con un vero server API e rivela problemi di admission webhook e di quote, ma richiede l'accesso al cluster. La combinazione standard: kubeconform in CI, poi un giro --dry-run=server prima del deploy — tieni entrambi gli strati.


Dopo aver scritto il tuo schema, incolla il JSON convertito dal tuo YAML nel validatore JSON online per vedere prima gli errori; per scrivere le parole chiave dello schema, consulta la guida JSON Schema; per tenere uno schema sorvegliato da test in CI, leggi il contract testing JSON Schema; per la conversione quotidiana JSON↔YAML, usa il convertitore JSON YAML XML.