# Per multi-stack: pyproject.toml, k8s YAML, GitHub Actions > Convertitore YAML ↔ JSON ↔ TOML online bidirezionale: auto-detect del formato, validazione strict con posizione errore, swap I/O istantaneo. Strumento gratuito nel browser (nessun upload): https://www.mauriziofonte.it/strumenti/convertitore-yaml-json-toml Conversione **bidirezionale** fra YAML, JSON e TOML. Auto-detect del formato sorgente, validazione strict che segnala con precisione la posizione di un errore di sintassi, swap istantaneo fra input e output per round-trip test. Tipico per chi lavora multi-stack: passi al volo da un manifest Kubernetes YAML al JSON wire, da un `pyproject.toml` al JSON di un payload API, da un `.github/workflows/*.yml` alla rappresentazione struct equivalente. ## Come usare il convertitore 1. **Incolla il sorgente** - YAML, JSON o TOML. Auto-detect riconosce il formato dalla sintassi (JSON inizia con { o [, TOML ha [section] o key = value, YAML è fallback). 2. **Scegli il target** - JSON, YAML o TOML. La conversione passa attraverso una rappresentazione intermedia in oggetti JavaScript: roundtrip lossless per YAML/JSON, lossy ammesso per TOML su edge case (datetime offset complessi, multi-line strings). 3. **Output istantaneo** - Conversione live al typing (debounced). Pulsante Converti per forzare il refresh. Stato OK/Error in fondo alla pagina con messaggio di parser. 4. **Swap I/O** - Scambia input e output con un click, utile per fare round-trip tests. Es: scrivi YAML, converti a JSON, scambia, converti a TOML, scambia, dovresti tornare al YAML originale (a meno di edge case TOML). ## Tre formati, tre mondi **YAML, JSON e TOML coprono use case sovrapposti ma distinti.** JSON è il formato wire universale per API REST e per le configurazioni di app dove la verbosità delle parentesi è accettabile. YAML è lo standard de facto per i manifest di orchestrator (Kubernetes, Ansible, Helm) e per le pipeline CI/CD (GitHub Actions, GitLab CI, CircleCI), grazie alla leggibilità basata su indentazione. TOML è il formato di config moderno per ecosistemi che vogliono evitare l'ambiguità di indent del YAML (Cargo per Rust, `pyproject.toml` per Python, Hugo). La conversione fra i tre è frequente per chi attraversa stack diversi nello stesso progetto. **Privacy operativa.** I file di configurazione contengono spesso informazioni sensibili: secret accidentalmente non rimossi, API key, hostname di backend interni, struttura del modello di deploy. Una conversione formato che richiede di caricare il file su un servizio terzo è un anti-pattern documentato. Qui la conversione avviene direttamente nel browser, senza che il contenuto del config lasci la macchina. **Validazione strict con posizione errore.** Quando il sorgente non è valido, il tool indica linea e colonna dell'errore di sintassi, oltre al messaggio del parser sottostante. Utile in particolare con YAML, dove un'indentazione sbagliata può produrre struct dati silenziosamente errate; e con TOML, dove i tipi espliciti (string vs datetime vs integer) generano errori chiari ma poco frequenti se non si conosce la spec. ## Glossario - **YAML**: YAML Ain't Markup Language. Formato data-serialization basato su indentazione, leggibile umano. Standard de facto per config orchestrator (Kubernetes, Ansible) e CI/CD (GitHub Actions, GitLab CI, CircleCI). - **JSON**: JavaScript Object Notation, RFC 8259. Formato wire universale. Subset valido di YAML 1.2 (un JSON è anche YAML). - **TOML**: Tom's Obvious Minimal Language. Tom Preston-Werner, 2013. Spec 1.0.0 (2021). Formato config moderno per Rust (Cargo), Python (pyproject), Hugo. Sintassi simile a INI ma con type system esplicito. - **Roundtrip lossless**: Proprietà di una conversione: A -> B -> A produce A originale identico. JSON YAML è lossless per dati semplici. TOML ha edge case lossy (datetime con offset complicati, ordinamento di chiavi). ## Domande frequenti ### Il TOML supporta tutti i tipi spec 1.0? Subset. Il parser/serializer custom copre: key=value scalar, [section], [a.b.c] dotted, inline tables, arrays, strings (quoted/raw single line), integers, floats (incluso scientifico), booleans, datetime (parsati come stringhe ISO 8601 senza intelligenza). Skip: multi-line strings (triple quote), array of tables ([[...]]), datetime con offset complicati, hex/octal/bin literals. Per TOML pieno spec 1.0 conviene un tool CLI con @iarna/toml. ### YAML preserva i commenti? No. La maggior parte dei parser YAML mainstream gestisce i commenti come metadata, ma il dump non li preserva: nel roundtrip YAML -> oggetto -> YAML i commenti vanno persi. Per workflow dove i commenti devono restare (config Helm, manifest annotati con motivazione delle scelte), serve un parser CST-aware (Concrete Syntax Tree), tipicamente in Python o in librerie YAML specializzate. ### JSON to YAML genera anchor automaticamente? No. L'output YAML è prodotto senza anchor (`&`) né alias (`*`). Per dataset con riferimenti circolari (rari nei config, comuni in alcune pipeline ML serializzate) servono workaround manuali o un flatten preventivo della struttura. ### Posso convertire YAML multi-document (--- separator)? Si per il parsing (js-yaml.loadAll). Però il tool gestisce single-document in V1: se incolli YAML multi-doc, viene parsato solo il primo. Per multi-doc estenderemo con tab dedicato future. ### L'output JSON ha indentazione configurabile? V1 default 2 spazi. Per altri formati (4 spazi, tab, minified) usare il **JSON formatter** dedicato di questo reame dopo la conversione: incolla il JSON output, scegli indent, riformatta. ### Funziona offline? Sì. Tutti i parser e i serializer sono caricati col primo load della pagina; in seguito la conversione funziona anche senza connessione, comodo per ambienti di lavoro su rete intermittente o air-gapped. ### Il tool gestisce file oltre 1 MB? Sì finché la memoria del tab regge. Per config molto grandi conviene un tool CLI (`yq` per YAML, `jq` per JSON, `tomlq` per TOML, tutti con processing streaming): gestiscono file di gigabyte senza freezare il browser e si integrano in pipeline di automazione. ### Differenza pratica fra YAML e TOML per scegliere config app? YAML è migliore per config nested complessi (pipeline CI/CD, manifest Kubernetes con array di pod). TOML è migliore per config flat con poche sezioni e tipi semplici (config app desktop, package metadata). YAML ammette indentation typo ambigui (frequente fonte di bug); TOML è più rigido e quindi meno error-prone. --- Uno strumento di Maurizio Fonte, senior backend engineer. Tutti gli strumenti: https://www.mauriziofonte.it/strumenti/