Il Problema Norway di YAML e le Differenze JSON ↔ YAML che gli Sviluppatori Devono Conoscere

Era un deployment Helm di routine. Il team aveva passato due giorni a ottimizzare un file values.yaml per un rollout multi-regione. Il chart template stava generando un ConfigMap Kubernetes con metadati di localizzazione — incluso il codice paese per il loro data center norvegese. Qualcuno aveva digitato country: NO e fatto il commit. La pipeline CI era passata. Il deployment era andato in produzione.

Poi sono arrivati gli alert.

Il ConfigMap conteneva country: false invece di country: "NO". Ogni servizio downstream che leggeva il campo country riceveva un booleano invece di una stringa. Il confronto tra stringhe era saltato. La logica di routing era caduta su un default. Il traffico che avrebbe dovuto restare in Norvegia finiva elaborato dall’endpoint regionale sbagliato.

La causa radice era una singola stringa senza virgolette in un file YAML. YAML 1.1 — la versione usata praticamente da tutti gli strumenti Kubernetes — tratta NO come il booleano false. Tratta YES, ON, OFF, Y, N, no, yes, on, off, y, n e una dozzina di altre varianti nello stesso modo. Nessun avviso. Nessun errore. Silenziosamente sbagliato.

JSON non ha questo problema. {"country": "NO"} è sempre una stringa. La coercizione implicita dei tipi di YAML è allo stesso tempo la sua più grande comodità e il suo footgun più pericoloso.

Questa guida copre il quadro completo: perché esiste il problema Norway, cosa è cambiato in YAML 1.2 (e perché la maggior parte degli strumenti lo ignora), come scegliere le giuste strategie di virgolettamento, le regole di indentazione che fanno inciampare i principianti, le trappole della precisione numerica e quattro scenari di conversione reali dai manifest Kubernetes ai piani Terraform. Quando hai bisogno di appiattire un valore JSON in YAML senza questa trappola, il nostro convertitore JSON in YAML mette automaticamente tra virgolette le stringhe problematiche per Norway.

JSON vs YAML — Quando Usare Quale

Prima di immergersi nel problema Norway, è utile capire per cosa è ottimizzato ciascun formato. Non sono intercambiabili — ciascuno ha un centro di progettazione che lo rende la scelta migliore in contesti specifici.

Dimensione	JSON	YAML
Sintassi	Rigorosa — parentesi graffe, virgolette, virgole obbligatorie	Flessibile — basata sull’indentazione, punteggiatura minimale
Sistema di tipi	Esplicito: stringa, numero, booleano, null, array, oggetto	Implicito — YAML 1.1 inferisce i tipi dalla forma del valore
Leggibilità	Comodo per gli sviluppatori, verificabile dalle macchine	Comodo per gli umani, facile da modificare a mano
Requisito virgolette	Le stringhe sono sempre tra virgolette	La maggior parte degli scalari può non averle (la fonte di Norway)
Commenti	Non supportati	Supportati con `#`
Uso principale	API, scambio dati, sistemi di configurazione moderni	Kubernetes, Docker Compose, Ansible, pipeline CI
Analisi sorprendenti	Nessuna — analisi rigorosa	Sì — Norway, ottale, timestamp
Enforcement dello schema	Ecosistema JSON Schema	YAML Schema (meno strumenti)

JSON vince quando i tuoi dati attraversano i confini tra sistemi — REST API, code di messaggi, serializzazione di database. Le macchine li analizzano, le macchine li generano, e la sintassi rigorosa rende la validazione semplice. Usa un Formattatore JSON per validare la struttura prima di inviarla.

YAML vince quando gli umani sono gli autori principali. Manifest Kubernetes, workflow GitHub Actions, Helm chart, playbook Ansible — questi sono file che gli sviluppatori leggono e modificano decine di volte. La punteggiatura ridotta e il supporto per i commenti li rendono genuinamente più manutenibili dei loro equivalenti JSON.

Il problema sorge al confine: quando uno strumento genera JSON (come kubectl get deploy -o json o terraform show -json) e un umano ha bisogno di mettere sotto controllo versione o modificare il risultato come YAML. Quella conversione è dove vive il problema Norway. Il nostro convertitore YAML in JSON gestisce la direzione inversa quando hai bisogno di tornare indietro.

Il Problema Norway — Approfondimento

Il problema Norway non è un bug. È una funzionalità della specifica YAML 1.1 che si comporta esattamente come progettato. Capire perché è stato progettato in questo modo — e perché così tanti sistemi implementano ancora la 1.1 — è la chiave per evitarlo.

Perché “no”, “yes”, “on”, “off”, “y”, “n” Vengono Mal Interpretati

La specifica YAML 1.1 definiva un tipo booleano ampio che era pensato per essere comodo per gli umani. Riconosceva tutti i seguenti come true o false:

Vero: y, Y, yes, Yes, YES, true, True, TRUE, on, On, ON

Falso: n, N, no, No, NO, false, False, FALSE, off, Off, OFF

L’intenzione era buona: i file di configurazione spesso usano yes/no invece di true/false in inglese, e YAML voleva supportare il modo naturale in cui le persone scrivono la configurazione. Il problema è che yes, no, on, off, y e n sono anche valori stringa perfettamente legittimi che significano qualcosa di completamente diverso nella maggior parte delle applicazioni.

Ecco il mismatch in YAML concreto:

# YAML 1.1 (quello che la maggior parte dei parser implementa)
country: NO        # analizzato come: country: false   ← PERICOLO
enabled: yes       # analizzato come: enabled: true
restart: off       # analizzato come: restart: false
language: y        # analizzato come: language: true
shell: n           # analizzato come: shell: false

# Corretto — le virgolette esplicite sovrascrivono l'inferenza del tipo
country: "NO"      # analizzato come: country: "NO"    ← sicuro
enabled: "yes"     # analizzato come: enabled: "yes"
restart: "off"     # analizzato come: restart: "off"
language: "y"      # analizzato come: language: "y"
shell: "n"         # analizzato come: shell: "n"

E il confronto con JSON:

{"country": "NO"}

In JSON, NO tra virgolette è sempre e incondizionatamente una stringa. Non c’è inferenza implicita del tipo. La rigidità che rende JSON verbose è anche ciò che lo rende sicuro.

Oltre alla coercizione booleana, YAML 1.1 converte anche implicitamente:

123e4 → il numero 1230000 (notazione scientifica)
0x1A → il numero 26 (esadecimale)
0755 → il numero 493 (ottale — questo rompe le stringhe dei permessi dei file Unix)
2024-05-04 → un oggetto data in molti parser (non solo una stringa)
1_000_000 → il numero 1000000 (separatore con underscore)

Il problema Norway è davvero solo il membro più famoso di un’intera famiglia di coercizioni implicite dei tipi in YAML.

YAML 1.1 vs 1.2 — Cosa è Cambiato

YAML 1.2 è stato pubblicato nel 2009 — quattro anni dopo YAML 1.1. Il suo obiettivo principale era portare YAML in stretta conformità con JSON (dato che JSON è in realtà un sottoinsieme valido di YAML 1.2) e ridurre le conversioni implicite dei tipi sorprendenti.

In YAML 1.2:

Il booleano è ristretto esattamente a true e false (con distinzione tra maiuscole e minuscole). Fine. yes, no, on, off sono stringhe semplici.
I letterali ottali richiedono il prefisso 0o (0o755) — la vecchia forma 0755 è una stringa.
I timestamp non vengono analizzati implicitamente — 2024-05-04 rimane una stringa a meno che non lo si tagghi esplicitamente.
La specifica stessa è un superset di JSON, il che significa che ogni documento JSON valido è YAML 1.2 valido.

Sulla carta, YAML 1.2 risolve completamente il problema Norway. In pratica, l’ecosistema si è quasi per nulla mosso.

Libreria	Specifica predefinita	Rischio Norway
PyYAML (Python)	YAML 1.1	Sì — `yaml.safe_load` analizza ancora `NO` come `False`
ruamel.yaml (Python)	YAML 1.2 (opzionale)	Configurabile — più sicuro di default
js-yaml (Node.js)	YAML 1.1	Sì nelle versioni precedenti; le versioni più recenti hanno l’opzione `FAILSAFE_SCHEMA`
eemeli/yaml (Node.js)	YAML 1.2	No — 1.2 di default, o selezionabile esplicitamente tramite versione
gopkg.in/yaml.v2 (Go)	YAML 1.1	Sì
gopkg.in/yaml.v3 (Go)	YAML 1.2	Significativamente più sicuro
Kubernetes / Helm	YAML 1.1 (tramite Go yaml.v2)	Sì — storico, molto difficile da migrare
Ansible	YAML 1.1 (tramite PyYAML)	Sì

Il motivo per cui la migrazione è lenta è la compatibilità con le versioni precedenti. I sistemi che si sono affidati al parsing di yes/no come booleani per un decennio non possono cambiare silenziosamente quel comportamento senza rompere le configurazioni esistenti. Kubernetes in particolare è un’installazione base massiccia dove cambiare la semantica del parsing YAML sarebbe un cambiamento di rottura a livello di cluster.

La conclusione pratica: assumi la semantica YAML 1.1 in qualsiasi strumento che non hai configurato esplicitamente diversamente. Metti sempre tra virgolette le stringhe che potrebbero essere mal lette come booleani, timestamp o numeri.

Come i Sistemi di Produzione Vengono Colpiti

Il codice paese della Norvegia è l’esempio più citato perché è controintuitivo — NO sembra un’abbreviazione ovvia, non un booleano. Ma il pattern si ripete in molti scenari del mondo reale:

Codici aeroporto IATA. L’aeroporto norvegese Harstad/Narvik ha il codice EVE. Sicuro. Oslo Gardermoen è OSL. Anche sicuro. Ma qualsiasi applicazione che usa YAML per memorizzare codici aeroporto regionali è a un codice rotta no di distanza da un booleano false in produzione.

Nomi di variabili d’ambiente. ON è un valore di variabile d’ambiente perfettamente valido che significa «abilitato» in alcuni sistemi legacy. OFF è la sua controparte. Migrare le configurazioni da script shell a YAML senza mettere tra virgolette questi valori introduce una coercizione silenziosa del tipo.

Campi utente email. Un utente il cui nome o username è letteralmente n, y o una qualsiasi delle parole trigger verrà serializzato in modo errato se l’applicazione produce YAML senza il virgolettamento corretto. Questo è particolarmente insidioso perché fallisce solo per un sottoinsieme di utenti.

Policy di restart di Docker Compose. Il valore "no" del campo restart_policy significa «non riavviare». Se perde le virgolette in un round-trip YAML, il valore diventa false, e Docker Compose potrebbe interpretarlo come «nessuna policy di restart specificata» o lanciare un errore di validazione — in entrambi i casi, il comportamento di restart del container è sbagliato.

Campo shell: di GitHub Actions. I valori validi di shell sono bash, pwsh, python, sh, cmd, powershell. Nessuno di questi è una parola Norway. Ma qualcuno che digita shell: yes o shell: on come segnaposto durante la modifica di una bozza potrebbe sorprendersi quando YAML lo trasforma in un booleano prima che il validatore lo veda anche.

La soluzione in tutti i casi è la stessa: metti tra virgolette le stringhe che sono semanticamente stringhe, indipendentemente dal fatto che un umano le riconosca come parole chiave. Il nostro convertitore JSON in YAML lo applica automaticamente — qualsiasi valore nell’elenco di parole Norway viene messo tra virgolette nell’output.

Strategia di Virgolettamento delle Stringhe

Una volta capito perché le parole Norway creano problemi, la soluzione è scegliere la giusta strategia di virgolettamento per il tuo caso d’uso. YAML supporta tre modalità, ognuna con diversi compromessi.

Auto vs Doppio vs Singolo

Virgolette Auto (consigliato per la maggior parte delle conversioni) lascia che sia la libreria a decidere quando le virgolette sono necessarie. I valori che verrebbero mal letti senza virgolette — parole Norway, numeri, timestamp, stringhe che sembrano sintassi YAML — vengono messe automaticamente tra virgolette. Tutto il resto rimane come scalare semplice. Produce l’output più leggibile restando sicuro.

# Output modalità Auto
name: Alice          # semplice — nessuna ambiguità
country: "NO"        # tra virgolette — parola Norway
age: 30              # semplice — numero non ambiguo
created: "2024-05-04" # tra virgolette — altrimenti verrebbe analizzato come data
port: "8080"         # dipende dalla libreria — alcune mettono tra virgolette stringhe che sembrano numeri

Stringhe con doppi apici racchiudono tutti i valori stringa tra virgolette doppie. È esplicito e verificabile — qualsiasi lettore può vedere che tutti questi valori sono stringhe senza ragionare sulla specifica. Il compromesso è la verbosità e la leggibilità ridotta, specialmente per configurazioni profondamente nidificate.

# Modalità doppi apici
name: "Alice"
country: "NO"
replicas: "3"         # anche i numeri diventano stringhe — può causare errori di schema

Attenzione: se il tuo schema di destinazione si aspetta un numero e lo serializzi come stringa tra virgolette, il parser YAML lo tipizzerà correttamente come stringa, ma Kubernetes o un altro consumatore rigido potrebbe rifiutare il campo come tipo sbagliato.

Stringhe con singoli apici sono una funzionalità solo YAML — JSON non ha sintassi con virgolette singole. Le virgolette singole sono letterali: nessuna sequenza di escape al loro interno. L’unico caso speciale è che una virgoletta singola all’interno di una stringa tra virgolette singole deve essere raddoppiata (''). Le virgolette singole sono ideali per stringhe che contengono backslash o caratteri speciali che richiederebbero l’escape nei doppi apici.

# Modalità singoli apici
pattern: 'C:\Users\alice\Documents'  # nessun escape necessario
regex: '\d+\.\d+'                    # backslash letterali

Per le conversioni da JSON a YAML destinate a tornare in JSON, preferisci la modalità Auto o Doppio. Le stringhe con virgolette singole introducono una sintassi specifica di YAML che richiede un parser YAML-aware al ritorno.

Scalari a Blocchi (| e >)

La sintassi degli scalari a blocchi di YAML è genuinamente utile per le stringhe multi-riga — qualcosa che JSON gestisce in modo scomodo con sequenze di escape \n.

Scalare a blocco letterale | preserva i newline esattamente:

# Blocco letterale — newline preservati
script: |
  #!/bin/bash
  set -euo pipefail
  echo "Starting deployment"
  kubectl apply -f manifest.yaml

# Rappresentazione JSON equivalente (illeggibile)
# {"script": "#!/bin/bash\nset -euo pipefail\necho \"Starting deployment\"\nkubectl apply -f manifest.yaml\n"}

Scalare a blocco ripiegato > unisce le righe con spazi, trasformando ogni newline in uno spazio (tranne le righe vuote, che diventano newline):

# Blocco ripiegato — i newline diventano spazi
description: >
  Questo servizio gestisce l'autenticazione
  per l'intera piattaforma. Supporta
  OAuth2, SAML e autenticazione con chiave API.

# Risultato: "Questo servizio gestisce l'autenticazione per l'intera piattaforma. Supporta OAuth2, SAML e autenticazione con chiave API.\n"

Gli scalari a blocchi brillano per incorporare certificati TLS, script shell multi-riga o query SQL nelle configurazioni YAML — scenari in cui l’equivalente JSON sarebbe una lunga riga escapata che nessun umano può leggere.

Durante la conversione da JSON a YAML, la maggior parte dei convertitori (incluso il nostro) usa la modalità Auto e rappresenta le stringhe multi-riga con scalari a blocchi solo quando rileva newline incorporati. Le stringhe su singola riga ottengono scalari flow (tra virgolette o semplici). Usa il nostro convertitore JSON in YAML per vedere l’output prima di committarlo in un manifest.

Indentazione — 2 vs 4 Spazi, Tab Proibiti

Le regole di indentazione di YAML sono più rigide di quanto sembrino. La specifica ha una regola assoluta e una convenzione che varia per ecosistema.

La regola assoluta: i tab sono proibiti. Ogni livello di indentazione deve usare spazi. Un carattere tab in un file YAML è un errore di analisi nella maggior parte dei parser:

# SBAGLIATO — i tab causano errori di analisi
apiVersion: apps/v1
kind: Deployment
metadata:
	name: my-app     # ← carattere tab qui → ParseError

# CORRETTO — solo spazi
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app      # ← due spazi

Il messaggio di errore che vedrai varia per libreria. In PyYAML di Python:

yaml.scanner.ScannerError: while scanning for the next token
found character '\t' that cannot start any token

In yaml.v3 di Go:

yaml: line 4: found character that cannot start any token

Configura il tuo editor per espandere i tab in spazi per i file YAML. In VS Code, aggiungi alle impostazioni del workspace: "[yaml]": { "editor.insertSpaces": true, "editor.tabSize": 2 }.

La convenzione: 2 vs 4 spazi. Entrambi sono validi. Le convenzioni dell’ecosistema differiscono:

Ecosistema	Convenzione	Motivo
Manifest Kubernetes	2 spazi	Docs ed esempi ufficiali usano 2
Helm chart	2 spazi	Segue la convenzione K8s
Docker Compose	2 spazi	Esempi delle specifiche Compose ufficiali
GitHub Actions	2 spazi	Esempi di workflow ufficiali
Playbook Ansible	2 spazi	Documentazione ufficiale
Configurazioni tradizionali	4 spazi	Corrisponde al default di JSON beautify

Per qualsiasi file che verrà consumato da Kubernetes o Docker Compose, usa 2 spazi. Per i file di configurazione standalone che verranno letti solo dagli umani e da strumenti personalizzati, entrambi funzionano — sii solo coerente all’interno di un file. Il nostro convertitore JSON in YAML usa di default l’indentazione a 2 spazi e ti permette di passare a 4 per i progetti che lo preferiscono.

Un’altra regola: gli elementi figli devono essere indentati più del loro genitore, ma il numero di spazi aggiuntivi può essere qualsiasi numero intero positivo (1, 2, 3, 4…) — purché sia coerente all’interno di un blocco. In pratica, usa sempre 2 o 4 per la leggibilità.

Gestione dei Numeri tra JSON ↔ YAML

Entrambi i formati supportano i numeri, ma i casi limite differiscono abbastanza da causare bug in produzione.

Perdita di Precisione per i Numeri Grandi

Il tipo Number di JavaScript è un float IEEE 754 a 64 bit. Può rappresentare gli interi esattamente fino a 2^53 − 1 = 9.007.199.254.740.991. Oltre quel limite, la precisione degli interi va persa:

// Perdita di precisione in JavaScript — non è un problema YAML, ma riguarda l'analisi JSON
JSON.parse('{"v": 9007199254740993}').v
// → 9007199254740992   (il 3 è diventato 2 — un bit perso)

// Sicuro — entro il range 2^53
JSON.parse('{"v": 9007199254740991}').v
// → 9007199254740991   (esatto)

Questo è importante per la conversione da JSON a YAML in ambienti JavaScript perché la precisione è già persa prima che inizi la serializzazione YAML. Il campo metadata.resourceVersion di Kubernetes è un campo stringa specificamente perché le versioni delle risorse possono superare il range degli interi sicuri. Altri campi che sembrano numeri piccoli — observedGeneration, componenti di uid — sono più sicuri, ma qualsiasi campo int64 in una risposta K8s è potenzialmente interessato.

Soluzioni alternative:

Usa Python o Go per le pipeline di conversione che coinvolgono numeri grandi — entrambi gestiscono nativamente gli interi arbitrari.
In Node.js, usa un parser JSON che supporta BigInt: JSON.parse(text, (_, v) => typeof v === 'number' && !Number.isSafeInteger(v) ? BigInt(v) : v).
Per i campi che devono fare il round-trip senza perdita, serializzali come stringhe alla sorgente.
Quando si esamina il YAML convertito, cerca campi come resourceVersion, generation e valori derivati da timestamp.

Stranezze con Ottale ed Esadecimale

YAML 1.1 tratta alcune stringhe simili a numeri come interi non-decimali:

# Sorprese nell'analisi YAML 1.1
permissions: 0755   # analizzato come ottale 493, non decimale 755
value: 0x1A         # analizzato come esadecimale 26, non stringa "0x1A"

# Comportamento YAML 1.2
permissions: 0755   # rimane come intero 755 (decimale) — l'ottale richiede il prefisso 0o
permissions: 0o755  # analizzato come ottale 493 sia in 1.1 che in 1.2

# Sicuro per entrambe le specifiche — metti tra virgolette qualsiasi valore con zero iniziale
permissions: "0755"  # sempre la stringa "0755"

La trappola ottale è particolarmente pericolosa per i permessi dei file Unix, i componenti di indirizzi IP con zeri iniziali (alcuni dispositivi di rete) e qualsiasi codice numerico che usa gli zeri iniziali per il padding (codici postali, codici prodotto). Metti sempre tra virgolette questi valori quando scrivi YAML a mano, o assicurati che il tuo convertitore lo faccia — il nostro convertitore JSON in YAML rileva le stringhe numeriche dal JSON e ne preserva il tipo stringa.

Conversioni nel Mondo Reale

Il problema Norway e le strategie di virgolettamento diventano concreti quando li applichi a scenari di conversione reali.

Manifest Kubernetes da JSON

Il workflow canonico: kubectl get deploy my-app -o json ti dà l’oggetto live come JSON. Vuoi ripulirlo (rimuovere status, creationTimestamp, managed fields) e fare il check-in in git come manifest YAML.

JSON sorgente (abbreviato):

{
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  "metadata": {
    "name": "my-app",
    "namespace": "production",
    "labels": {
      "app": "my-app",
      "region": "NO"
    }
  },
  "spec": {
    "replicas": 3,
    "selector": {
      "matchLabels": { "app": "my-app" }
    },
    "template": {
      "spec": {
        "containers": [{
          "name": "app",
          "image": "registry.example.com/my-app:v1.2.3",
          "env": [
            { "name": "REGION", "value": "NO" },
            { "name": "ENABLE_FEATURE", "value": "yes" }
          ]
        }]
      }
    }
  }
}

Output YAML atteso (con protezione Norway):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: production
  labels:
    app: my-app
    region: "NO"          # tra virgolette — parola Norway
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    spec:
      containers:
        - name: app
          image: registry.example.com/my-app:v1.2.3
          env:
            - name: REGION
              value: "NO"           # tra virgolette — parola Norway
            - name: ENABLE_FEATURE
              value: "yes"          # tra virgolette — parola Norway

Nota che replicas: 3 viene lasciato senza virgolette — è un intero legittimo che Kubernetes si aspetta come numero. Le parole Norway nei labels e nei valori env sono tra virgolette. Un convertitore ingenuo che non gestisce i booleani YAML 1.1 produrrebbe silenziosamente region: false e value: false.

Dopo la conversione, valida con: kubectl apply --dry-run=client -f manifest.yaml. Questo rileva gli errori di schema senza toccare il cluster.

Prova la conversione nel nostro convertitore JSON in YAML — incolla il JSON qui sopra e vedi immediatamente l’output Norway-safe. Usa il nostro convertitore YAML in JSON per verificare il round-trip.

Docker Compose da JSON

Le pipeline CI/CD a volte generano configurazioni Docker Compose programmaticamente da un archivio di configurazione JSON, poi le scrivono su disco come YAML per la lettura degli sviluppatori.

Trappola critica — policy di restart:

{"restart_policy": "no"}

In Compose, restart_policy: "no" è un valore valido che significa «non riavviare mai il container». Senza virgolette in YAML, questo diventa restart_policy: false, che Docker Compose potrebbe trattare come la stessa semantica (falsy = no restart) o rifiutare con un errore di validazione del tipo — il comportamento varia per versione di Compose. Il virgolettamento è obbligatorio.

Attenzione anche a: deploy.restart_policy.condition: "on-failure" di Compose v3 — il valore on-failure contiene la parola on, ma è con trattino e non è nella lista di trigger, quindi è effettivamente sicuro. Tuttavia, condition: on (senza il -failure) creerebbe un mismatch. Metti tra virgolette i valori delle variabili d’ambiente nel blocco environment: se potrebbero essere parole Norway.

Valida i file Compose dopo la conversione: docker-compose config analizza e ri-emette la forma canonica, evidenziando gli errori di tipo.

Workflow GitHub Actions

I workflow GitHub Actions sono file YAML modificati a mano dagli sviluppatori. Lo scenario di conversione più comune è leggere i dati del workflow dall’API GitHub (che restituisce JSON) e convertirli in un file YAML locale per la modifica.

I campi chiave da controllare:

# SICURO — nessuna parola Norway nelle azioni GitHub Actions standard
on:                        # "on" è una chiave YAML qui, non un valore — gestito diversamente
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: |
          npm install
          npm test
        env:
          NODE_ENV: production   # sicuro — non è una parola Norway
          DEBUG: "off"           # parola Norway nel valore — necessita virgolette

Nota: on: come chiave YAML è speciale — il problema Norway si applica ai valori, non alle chiavi. Ma on come valore (come DEBUG: on) attiverebbe la coercizione. Il blocco env: merita particolare attenzione perché i valori delle variabili d’ambiente sono stringhe, ma molti di essi sono flag brevi che potrebbero collidere con le parole Norway.

Per i workflow che includono specificazioni shell:, i valori validi (bash, pwsh, sh, python) sono tutti al sicuro dalla coercizione Norway. I valori personalizzati dovrebbero essere messi preventivamente tra virgolette.

Piano Terraform JSON → YAML

terraform show -json tfplan > plan.json produce una rappresentazione JSON dettagliata di ciò che Terraform pianifica di creare, modificare o distruggere. Convertirla in YAML la rende più leggibile per le revisioni delle pull request e gli audit di conformità.

terraform plan -out=tfplan
terraform show -json tfplan > plan.json
# Poi converti con il nostro strumento o una libreria

Il JSON del piano Terraform è complesso e profondo. Preoccupazioni principali durante la conversione:

ID interi grandi. Gli ID delle risorse cloud (ID account AWS, numeri di progetto GCP) e i valori degli attributi computati possono essere numeri grandi. Converti tramite Python o Go per evitare la perdita di precisione float64.
Stringhe di vincoli di versione. Terraform usa ~>, >=, <= nei vincoli di versione dei provider. Questi sono valori stringa che YAML gestisce correttamente purché non siano parole Norway — ma ~> è sicuro.
Valori di configurazione del provider. Gli output del piano Terraform possono includere valori di configurazione per le risorse. Se un campo booleano ha come default false ed è rappresentato come "no" in qualche schema del provider, questo è un rischio Norway al ritorno verso YAML.
Il blocco .sensitive_values. I valori sensibili sono redatti come booleani true nel JSON del piano. Questi sopravvivono alla conversione pulitamente poiché true non è una parola Norway in nessuna versione YAML.

La conversione da Terraform a YAML è principalmente per la revisione umana, non per essere ridata a Terraform. Non usare manifest YAML come input per Terraform — il formato nativo di Terraform è HCL, e il suo formato di input JSON è specifico e documentato separatamente.

Esempi di Codice — 4 Linguaggi

Node.js (eemeli/yaml + js-yaml)

L’ecosistema Node.js ha due librerie YAML dominanti con una gestione di Norway significativamente diversa:

// eemeli/yaml — consigliato, YAML 1.2 di default, Norway-safe
import { stringify } from 'yaml';
import { readFileSync } from 'fs';

const jsonInput = readFileSync('input.json', 'utf8');
const data = JSON.parse(jsonInput);

// Default: YAML 1.2 — "NO" rimane "NO", nessuna coercizione booleana
const yamlOutput = stringify(data);
console.log(yamlOutput);
// region: NO      ← sicuro in 1.2, ma per massima compatibilità virgolettarlo esplicitamente

// Forza il comportamento YAML 1.1 (per ambienti K8s/Helm che analizzano 1.1)
const yamlForK8s = stringify(data, { version: '1.1' });
// region: 'NO'    ← messo automaticamente tra virgolette perché 1.1 analizzerebbe NO come false
console.log(yamlForK8s);

// js-yaml — molto diffuso, ma semantica YAML 1.1, rischio Norway senza attenzione
import yaml from 'js-yaml';
import { readFileSync } from 'fs';

const data = JSON.parse(readFileSync('input.json', 'utf8'));

// Dump predefinito — le parole Norway potrebbero non essere tra virgolette
const unsafe = yaml.dump(data);
// region: NO    ← verrà analizzato come false se riletto da un parser 1.1!

// Più sicuro: usa uno schema personalizzato o forza il virgolettamento
const safer = yaml.dump(data, {
  schema: yaml.JSON_SCHEMA,   // restringe ai tipi compatibili JSON
  noCompatMode: false,
  lineWidth: -1,
  quotingType: '"',
  forceQuotes: false,         // mette tra virgolette solo quando necessario per lo schema JSON
});

Per i nuovi progetti, preferisci eemeli/yaml. Il suo default YAML 1.2 è più sicuro, la sua Document API dà un controllo granulare sul virgolettamento, e gestisce meglio la fedeltà del round-trip. Per i progetti che già usano js-yaml, usa l’opzione JSON_SCHEMA per restringere ai tipi sicuri per JSON.

Python (PyYAML + ruamel.yaml)

Python è il linguaggio dominante per gli strumenti Kubernetes, Ansible e le pipeline di data engineering — tutti utenti intensivi di YAML.

import json
import yaml
import sys

# PyYAML — semplice, standard, ma YAML 1.1 di default
with open('input.json') as f:
    data = json.load(f)

output = yaml.dump(data, default_flow_style=False, allow_unicode=True)
# country: 'NO'   ← PyYAML è abbastanza intelligente da mettere automaticamente tra virgolette le parole Norway
# Ma NON mette tra virgolette "yes", "no" (minuscolo) in tutte le configurazioni:
# enabled: 'yes'   ← tra virgolette
# tag: y           ← potrebbe o meno essere tra virgolette a seconda della versione

print(output)

import json
import sys
from ruamel.yaml import YAML

# ruamel.yaml — fedeltà round-trip, supporta YAML 1.2, consigliato per la produzione
yaml_rt = YAML()
yaml_rt.default_flow_style = False
yaml_rt.width = 4096              # previene il line wrapping indesiderato
yaml_rt.best_map_flow_style = False

with open('input.json') as f:
    data = json.load(f)

yaml_rt.dump(data, sys.stdout)
# Preserva l'ordine delle chiavi, gestisce le parole Norway correttamente, supporta le ancore nel round-trip

Per gli script di automazione Ansible e Kubernetes dove stai convertendo risposte API JSON in manifest YAML, ruamel.yaml è la scelta più sicura. PyYAML va bene per script semplici dove controlli i dati di input e hai verificato che non compaiono parole Norway.

Go (gopkg.in/yaml.v3)

Go è il linguaggio dell’ecosistema Kubernetes stesso — kubectl, Helm, Argo, Flux e la maggior parte degli operator K8s sono scritti in Go.

package main

import (
    "encoding/json"
    "fmt"
    "os"

    "gopkg.in/yaml.v3"
)

func main() {
    // Leggi l'input JSON
    jsonBytes, err := os.ReadFile("input.json")
    if err != nil {
        panic(err)
    }

    // Deserializza JSON in una mappa generica
    var data map[string]interface{}
    if err := json.Unmarshal(jsonBytes, &data); err != nil {
        panic(err)
    }

    // Serializza in YAML — yaml.v3 usa la semantica YAML 1.2
    yamlBytes, err := yaml.Marshal(data)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(yamlBytes))
    // country: "NO"     ← yaml.v3 virgoletta le parole Norway correttamente
    // replicas: 3       ← gli interi rimangono interi
    // enabled: true     ← i booleani rimangono booleani
}

yaml.v3 è un miglioramento significativo rispetto a yaml.v2 per la sicurezza Norway. La libreria v2 seguiva YAML 1.1 e scriveva NO senza virgolette; v3 virgoletta correttamente i valori ambigui. Se stai mantenendo un progetto Go più vecchio che usa v2, aggiorna a v3 — l’API è largamente compatibile e il miglioramento della sicurezza vale la migrazione.

Per la conversione type-safe con struct Go (invece di map[string]interface{}), usa i tag degli struct:

type DeploymentLabels struct {
    App    string `yaml:"app" json:"app"`
    Region string `yaml:"region" json:"region"`
}
// yaml.Marshal su un campo struct contenente "NO" lo metterà tra virgolette correttamente in v3

CLI Bash (yq + jq)

Per gli script shell e le conversioni rapide una tantum, yq (la versione di Mike Farah, mikefarah/yq) converte JSON in YAML con un singolo comando:

# Installa yq
brew install yq                         # macOS
sudo wget -qO /usr/local/bin/yq \
  https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
chmod +x /usr/local/bin/yq              # Linux

# Converti un file JSON in YAML
yq -P < input.json > output.yaml

# Converti dall'output JSON di kubectl
kubectl get deploy my-app -o json | yq -P > manifest.yaml

# Passa prima attraverso jq per filtrare/trasformare, poi converti in YAML
kubectl get deploy my-app -o json \
  | jq 'del(.status, .metadata.creationTimestamp, .metadata.managedFields)' \
  | yq -P > clean-manifest.yaml

Il pattern jq | yq è uno schema potente: usa jq per la manipolazione JSON (filtrare campi, ristrutturare, interrogare valori) e yq -P come serializzatore YAML finale.

Attenzione Norway con yq: yq (mikefarah) rispetta il tipo di input dal JSON — una stringa JSON "NO" nell’input verrà serializzata come stringa YAML con virgolette. Ma se generi YAML direttamente con yq (non dall’input JSON), devi mettere esplicitamente tra virgolette i valori delle parole Norway. Usa il nostro convertitore YAML in JSON per validare il round-trip dopo l’output di yq.

Casi Limite e Gotcha

Oltre al problema Norway, la conversione JSON ↔ YAML ha diversi casi limite che fanno inciampare anche gli sviluppatori esperti:

YAML multi-documento (separatore ---). Un singolo file YAML può contenere più documenti separati da ---. JSON non ha un concetto equivalente. Quando si converte YAML multi-documento in JSON, la maggior parte degli strumenti prende solo il primo documento, unisce tutti i documenti in un array, o restituisce un errore. Quando si converte JSON in YAML, per convenzione viene aggiunto un singolo header di documento ---. Decidi e documenta esplicitamente il comportamento per le pipeline che potrebbero incontrare file multi-documento.
Ancore e alias YAML. YAML supporta definizioni &anchor e riferimenti *alias per configurazioni DRY. Quando si converte YAML in JSON, le ancore devono essere espanse — il JSON risultante può essere molto più grande del YAML sorgente. Quando si converte JSON in YAML, il convertitore non può ricostruire le ancore che non esistevano nell’originale. Gli alias sono una funzionalità solo YAML.
Analisi implicita dei timestamp. I parser YAML 1.1 convertono 2024-05-04 e 2024-05-04T12:00:00Z in oggetti data nativi del linguaggio, non in stringhe. Quando questo oggetto data viene serializzato di nuovo in JSON, l’output dipende dalla libreria: alcuni producono stringhe ISO, altri timestamp Unix, altri null. Il round-trip delle date attraverso YAML senza virgolettamento esplicito della stringa ("2024-05-04") può silenziosamente cambiare il formato.
Il tag !!binary. YAML può incorporare dati binari codificati in base64 con il tag !!binary. JSON non ha un tipo binario — il binario deve essere una stringa base64. Quando si converte YAML con campi !!binary in JSON, decodifica in stringa base64. Quando si torna indietro, non puoi ricostruire il tag binario senza conoscere lo schema. Kubernetes usa !!binary per alcuni valori secret.
Collisioni di tipo chiave. JSON richiede che le chiavi degli oggetti siano stringhe. YAML permette chiavi di qualsiasi tipo — chiavi intere, chiavi booleane, persino chiavi oggetto complesse. Un file YAML con true: value o 1: value come chiavi non può essere rappresentato fedelmente come JSON. La maggior parte dei convertitori stringifica le chiavi, ma la semantica cambia.
Varianza nella rappresentazione di null. In YAML, null, ~, Null, NULL e un valore vuoto significano tutti null. In JSON, solo null è null. Quando si converte YAML in JSON, tutti questi si normalizzano in null. Ma quando si converte JSON di ritorno in YAML, la scelta della rappresentazione null conta — ~ è più compatto, null è più esplicito. Scegline uno e mantienilo.
Cambiamenti nell’ordine di ordinamento. Gli oggetti JSON tecnicamente non hanno un ordine definito per le chiavi (anche se la maggior parte dei parser preserva l’ordine di inserimento). I mapping YAML non hanno anch’essi un ordine obbligatorio. Ma alcune librerie YAML ordinano le chiavi alfabeticamente di default quando serializzano. Questo può causare diff grandi nel controllo versione se il JSON sorgente usava un ordine diverso. Configura sort_keys=False in PyYAML e opzioni equivalenti nelle altre librerie.

Quando NON Convertire

La conversione non è sempre la risposta giusta. Ecco gli scenari in cui è meglio restare nel formato originale:

Non convertire YAML in JSON se il YAML contiene commenti che documentano logica di business. I commenti YAML non fanno parte del modello dati — scompaiono in qualsiasi serializzazione in JSON. Se un manifest Kubernetes ha commenti che spiegano perché è stato scelto un limite di risorse specifico o perché è stata fatta un’eccezione alla policy di sicurezza, convertirlo in JSON distrugge quella documentazione. Tieni il YAML.

Non auto-convertire le configurazioni nelle pipeline CI senza test di round-trip. Se la tua pipeline converte JSON in YAML e poi applica il YAML a un cluster, aggiungi un passaggio di validazione del round-trip: YAML di ritorno in JSON, poi confronta con l’originale. Questo rileva le sorprese di coercizione del tipo prima che raggiungano la produzione.

Non convertire solo perché uno strumento produce JSON. kubectl, aws, terraform e docker inspect producono tutti JSON, ma la maggior parte di questi strumenti accetta anche YAML come input. Prima di costruire un passaggio di conversione, verifica se lo strumento di destinazione può accettare direttamente input YAML — la maggior parte degli strumenti DevOps moderni può farlo. Il nostro convertitore YAML in JSON è più utile quando hai specificamente bisogno di JSON per uno strumento che non accetta YAML.

Non convertire se gli schema differiscono. Se il tuo JSON usa chiavi camelCase e il tuo consumatore YAML si aspetta snake_case (o viceversa), hai bisogno di un passaggio di trasformazione oltre alla conversione di formato. Una semplice conversione di formato produrrà YAML sintatticamente corretto ma semanticamente sbagliato. Gestisci esplicitamente il mapping degli schema.

Non mantenere entrambi i formati sincronizzati manualmente. Se stai mantenendo un config.json e un config.yaml che dovrebbero essere equivalenti, col tempo divergeranno. Scegli un formato canonico e deriva l’altro automaticamente — o meglio, scegli un formato ed elimina la duplicazione.

FAQ

Il problema Norway di YAML riguarda ancora i sistemi moderni?

Sì — è pervasivo nell’ecosistema. Kubernetes e Helm usano la libreria yaml.v2 di Go (semantica YAML 1.1) in parti significative del loro codebase. Ansible usa PyYAML (YAML 1.1). I workflow GitHub Actions vengono analizzati dal parser YAML interno di GitHub che ha il suo comportamento. La maggior parte dei file YAML CI/CD in circolazione viene elaborata da parser YAML 1.1. Assumi la semantica 1.1 finché non hai verificato altrimenti.

Perché dovrei convertire JSON in YAML se YAML è più difficile da analizzare?

La conversione non riguarda la difficoltà del parser — riguarda la modificabilità da parte degli umani. JSON è ideale per le macchine; YAML è ideale per gli umani che devono leggere, modificare e revisionare i file di configurazione. Un manifest Kubernetes in git, revisionato nelle pull request e ottimizzato a mano dagli sviluppatori dovrebbe essere YAML. Lo stesso manifest recuperato dall’API per l’elaborazione programmatica dovrebbe essere JSON. Il nostro convertitore JSON in YAML fa da ponte tra i due.

Posso fare il round-trip JSON ↔ YAML senza perdita di dati?

Con alcune avvertenze, sì — per i dati compatibili JSON. JSON è un sottoinsieme di YAML 1.2, quindi qualsiasi documento JSON valido è YAML 1.2 valido. Andare JSON → YAML → JSON dovrebbe essere privo di perdite per qualsiasi dato senza coercizione implicita del tipo. Il problema Norway significa che una stringa JSON "NO" potrebbe sopravvivere al passaggio di andata solo se il convertitore la mette tra virgolette, e poi sopravvivere al passaggio di ritorno solo se il parser YAML rispetta le virgolette. Usa una libreria YAML 1.2 per entrambe le direzioni per garantire round-trip privi di perdite.

Qual è la libreria YAML più sicura per la produzione?

Per Python: ruamel.yaml configurato per YAML 1.2. Per Node.js: eemeli/yaml (il pacchetto yaml su npm). Per Go: gopkg.in/yaml.v3. Tutte e tre implementano la semantica YAML 1.2 o hanno modalità YAML 1.2 esplicite e gestiscono le parole Norway correttamente. Evita le librerie YAML 1.1 nei nuovi progetti. Se devi usare una libreria 1.1 (PyYAML, js-yaml, yaml.v2) per motivi di compatibilità, metti sempre esplicitamente tra virgolette le stringhe problematiche per Norway.

I manifest YAML Kubernetes supportano i commenti dopo la conversione JSON?

No — i commenti non possono essere recuperati dal JSON. JSON non ha sintassi per i commenti, quindi non c’è nulla da convertire. Quando esegui kubectl get deploy -o json e converti l’output in YAML per il storage git, il YAML risultante non avrà commenti. I commenti in un manifest Kubernetes devono essere scritti da un umano dopo la conversione. Questo è uno dei motivi per cui mantenere il YAML scritto a mano come fonte canonica è spesso preferibile al round-trip attraverso l’API JSON.

Come gestisco i grandi interi come resourceVersion o i timestamp in nanosecondi?

Il campo metadata.resourceVersion di Kubernetes è un campo stringa deliberatamente — il team di Kubernetes sapeva che i parser JSON in JavaScript e altri runtime basati su float64 avrebbero perso precisione sugli interi grandi. Trattalo sempre come stringa. Per i grandi interi genuinamente numerici (come i timestamp epoch in nanosecondi in alcuni sistemi di tracing), usa il tipo int di Python, int64 di Go, o BigInt di Node.js per l’analisi. Non passarli mai attraverso JSON.parse() in JavaScript senza una funzione reviver personalizzata. Quando si converte in YAML, questi grandi interi sono al sicuro — YAML non ha limite di precisione per gli interi. Il pericolo è nel round-trip attraverso il parser JSON di JavaScript.

YAML 1.2 è già ampiamente adottato?

In modo disomogeneo. Le principali librerie linguistiche hanno migrato: yaml.v3 di Go, ruamel.yaml di Python e eemeli/yaml di Node.js supportano o hanno come default YAML 1.2. Ma Kubernetes, Ansible e gran parte dell’ecosistema DevOps usa ancora parser YAML 1.1 a causa del costo di compatibilità della migrazione. L’adozione di YAML 1.2 nei nuovi progetti è raccomandata, ma assumi 1.1 per qualsiasi sistema che non hai configurato tu stesso.

Il nostro team dovrebbe standardizzarsi su JSON o YAML per le configurazioni?

Standardizza per scopo, non per formato. Usa JSON per le configurazioni consumate dal codice (corpi di richieste API, file di configurazione SDK, strumenti programmatici). Usa YAML per le configurazioni consumate dagli umani (manifest Kubernetes, pipeline CI, configurazioni di deployment, playbook Ansible). Evita di mescolare i due per la stessa configurazione — scegli una rappresentazione per tipo di configurazione e automatizza la conversione se hai bisogno di entrambe. Quando hai bisogno di convertire, sia il nostro convertitore JSON in YAML che il convertitore YAML in JSON girano interamente nel browser — nessun dato lascia il tuo dispositivo.

Prova Ora

Pronto a convertire un file reale? Prova il nostro convertitore JSON in YAML per trasformare JSON in YAML sicuro per Kubernetes — mette automaticamente tra virgolette le parole Norway (NO, yes, on, off e l’intera lista di booleani YAML 1.1) e ti permette di scegliere l’indentazione a 2 o 4 spazi. Per la direzione inversa, il nostro convertitore YAML in JSON gestisce ancore, alias e YAML multi-documento. Entrambi gli strumenti girano interamente nel browser — i tuoi dati non lasciano mai il dispositivo, il che conta quando lavori con manifest Kubernetes di produzione o piani Terraform che contengono configurazioni di risorse sensibili.

Il Problema Norway di YAML e le Differenze JSON-YAML Online per Devs