JSON vs YAML: Confronto completo e quando usare ciascuno

# JSON vs YAML: Confronto completo

JSON e YAML sono due formati molto popolari per configurazione e scambio dati. Questa guida ti aiuterà a capire le differenze e quando usare ciascuno.

Overview

JSON (JavaScript Object Notation)

• Formato basato su testo
• Sintassi JavaScript-like
• Strict syntax rules
• Ottimo per API e data exchange

{
  "name": "MyApp",
  "version": "1.0.0",
  "dependencies": {
    "express": "^4.18.0",
    "mongoose": "^6.0.0"
  },
  "scripts": {
    "start": "node server.js",
    "test": "jest"
  }
}

YAML (YAML Ain't Markup Language)

• Human-readable format
• Indentation-based
• Supporta commenti
• Popolare per configurazioni

name: MyApp
version: 1.0.0
dependencies:
  express: ^4.18.0
  mongoose: ^6.0.0
scripts:
  start: node server.js
  test: jest

Confronto sintassi

Oggetti/Mapping

{
  "utente": {
    "nome": "Marco",
    "età": 30,
    "città": "Roma"
  }
}

utente:
  nome: Marco
  età: 30
  città: Roma

Array/Liste

{
  "linguaggi": ["JavaScript", "Python", "Go"],
  "utenti": [
    {"nome": "Marco", "ruolo": "dev"},
    {"nome": "Laura", "ruolo": "admin"}
  ]
}

linguaggi:
  - JavaScript
  - Python
  - Go

utenti:
  - nome: Marco
    ruolo: dev
  - nome: Laura
    ruolo: admin

Stringhe

{
  "short": "Hello",
  "escaped": "He said: \"Hi!\"",
  "multiline": "Line 1\nLine 2\nLine 3"
}

short: Hello
escaped: 'He said: "Hi!"'
multiline: |
  Line 1
  Line 2
  Line 3

# Oppure
inline: >
  Questo è un testo lungo
  che viene unito
  in una singola riga

Numeri e Booleani

{
  "age": 30,
  "price": 19.99,
  "active": true,
  "deleted": false,
  "nullable": null
}

age: 30
price: 19.99
active: true      # o yes, on
deleted: false    # o no, off
nullable: null    # o ~

Commenti

{
  "_comment": "JSON non supporta commenti nativi",
  "workaround": "Usare campi speciali"
}

# Commenti supportati!
name: MyApp  # Inline comment
version: 1.0.0

# Multi-line comment
# Utile per documentazione

Confronto tecnico

Performance

| Formato | Parse Time (10MB file) |

|---------|------------------------|

| JSON | ~100ms |

| YAML | ~500ms |

import json
import yaml
import time

data = {"key": "value"}  10000


# JSON
start = time.time()
json_str = json.dumps(data)
parsed = json.loads(json_str)
json_time = time.time() - start

# YAML
start = time.time()
yaml_str = yaml.dump(data)
parsed = yaml.safe_load(yaml_str)
yaml_time = time.time() - start

print(f"JSON: {json_time:.4f}s")
print(f"YAML: {yaml_time:.4f}s")
# JSON: 0.0234s
# YAML: 0.1156s (5x più lento)

{
  "app": {
    "name": "Example",
    "version": "1.0.0",
    "config": {
      "port": 3000,
      "host": "localhost"
    }
  }
}

app:
  name: Example
  version: 1.0.0
  config:
    port: 3000
    host: localhost

# Questo è valido ma pericoloso
norway: NO    # Interpretato come false!
sweden: SE    # String

# Meglio:
norway: "NO"  # String explicit

version: '3.8'
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html
    environment:
      - NODE_ENV=production

  db:
    image: postgres:13
    environment:
      POSTGRES_PASSWORD: secret

// Request
POST /api/users
Content-Type: application/json

{
  "name": "Marco",
  "email": "marco@example.com",
  "preferences": {
    "theme": "dark",
    "notifications": true
  }
}

// Response
{
  "success": true,
  "user": {
    "id": 123,
    "name": "Marco",
    "createdAt": "2026-01-26T10:00:00Z"
  }
}

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Setup Node
        uses: actions/setup-node@v2
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

{
  "_id": "507f1f77bcf86cd799439011",
  "user": {
    "name": "Marco",
    "email": "marco@example.com"
  },
  "posts": [
    {
      "title": "Post 1",
      "views": 100
    }
  ],
  "createdAt": {"$date": "2026-01-26T10:00:00Z"}
}

{
  "name": "my-app",
  "version": "1.0.0",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "next": "^13.0.0",
    "react": "^18.0.0"
  }
}

{
  // Compiler options
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true
  },
  // Files to include
  "include": ["src//"]
}

• JSON con commenti
• Best of both worlds

Conversione tra formati

YAML → JSON

import yaml
import json

# Leggi YAML
with open('config.yaml') as f:
    data = yaml.safe_load(f)

# Scrivi JSON
with open('config.json', 'w') as f:
    json.dump(data, f, indent=2)

• yaml-to-json.com
• convertjson.com/yaml-to-json.htm

JSON → YAML

import json
import yaml

# Leggi JSON
with open('data.json') as f:
    data = json.load(f)

# Scrivi YAML
with open('data.yaml', 'w') as f:
    yaml.dump(data, f, default_flow_style=False)

const fs = require('fs');
const yaml = require('js-yaml');

// Read JSON
const json = JSON.parse(fs.readFileSync('data.json', 'utf8'));

// Write YAML
const yamlStr = yaml.dump(json);
fs.writeFileSync('data.yaml', yamlStr);

Pro e Contro

JSON

• ✅ Parsing molto veloce
• ✅ Syntax rigida = meno errori
• ✅ Supporto universale
• ✅ Nativo in browser
• ✅ Formato standard per API
• ✅ Tool di validazione maturi

• ❌ No commenti
• ❌ Più verboso
• ❌ Multi-line strings scomode
• ❌ No reference/anchors
• ❌ Meno human-readable

YAML

• ✅ Molto leggibile
• ✅ Commenti nativi
• ✅ Multi-line strings facili
• ✅ Meno verboso
• ✅ Anchors & references
• ✅ Ottimo per config files

• ❌ Parsing più lento
• ❌ Indentation errors comuni
• ❌ Ambiguità possibili
• ❌ Security concerns (arbitrary code exec)
• ❌ Non standard per API

Best Practices

Quando usare JSON

✅ Usa JSON per:

• API requests/responses
• Data storage in database
• Browser-based applications
• Performance-critical applications
• Data exchange tra sistemi
• Quando serve strict validation

Quando usare YAML

✅ Usa YAML per:

• Configuration files
• CI/CD pipelines
• Docker Compose
• Kubernetes manifests
• Ansible playbooks
• Documentation con codice

Hybrid approach

# .yarnrc.yml (config Yarn)
nodeLinker: node-modules
yarnPath: .yarn/releases/yarn-3.2.0.cjs

// package.json (metadata progetto)
{
  "name": "my-app",
  "version": "1.0.0"
}

Conclusione

• 🚀 Performance è critica
• 🔄 Hai API REST
• 💾 Usi database NoSQL
• 🌐 Lavori con browser
• ✅ Vuoi validation rigorosa

• 📝 Hai config files complesse
• 👥 Readability è priorità
• 💬 Hai bisogno di commenti
• 🔧 Lavori con DevOps/CI/CD
• 📚 Documenti configurazione

| Use Case | Formato | Motivo |

|----------|---------|--------|

| REST API | JSON | Standard, veloce |

| Config file | YAML | Leggibile, commenti |

| Database | JSON | Performance, supporto |

| CI/CD | YAML | Readability |

| Browser data | JSON | Nativo |

| Infrastructure as Code | YAML | Chiaro, documenta |