Chuyển đổi JSON ↔ YAML ↔ TOML

Ba format, ba triết lý thiết kế

JSON, YAML, và TOML đều là serialization format — đều biểu diễn cấu trúc key-value lồng nhau, arrays, strings, numbers, booleans — nhưng với các ưu tiên khác nhau.

JSON được thiết kế cho machine exchange: syntax tối giản, parsing rõ ràng, không comments. Mọi JSON parser ở mọi ngôn ngữ đều cho output giống hệt nhau với cùng input. Đây là ngôn ngữ chung của các API.

YAML được thiết kế cho khả năng đọc của con người: indentation có nghĩa thay vì dấu ngoặc, comments, multi-line strings không cần escape. Đây là format config phổ biến nhất trong hệ sinh thái cloud-native (GitHub Actions, Docker Compose, Kubernetes manifests, Ansible playbooks).

TOML được thiết kế riêng cho config files: kiểu dữ liệu tường minh, không mơ hồ, không có significant whitespace. Là format config mặc định của Rust (Cargo.toml), Python packaging (pyproject.toml), và Hugo sites. Tom Preston-Werner (đồng sáng lập GitHub) tạo ra nó như là "config file format dễ đọc nhờ semantics rõ ràng."

Khi nào dùng format nào

| | JSON | YAML | TOML | |---|---|---|---| | REST / GraphQL APIs | ✓ tốt nhất | — | — | | GitHub Actions | — | ✓ tốt nhất | — | | Docker Compose | — | ✓ tốt nhất | — | | Kubernetes manifests | — | ✓ tốt nhất | — | | Rust Cargo config | — | — | ✓ tốt nhất | | Python pyproject.toml | — | — | ✓ tốt nhất | | Config app tự edit tay | — | ✓ | ✓ | | Dữ liệu generate bằng machine | ✓ tốt nhất | — | — |

"Norway problem" của YAML

YAML có một cái bẫy parsing nổi tiếng: unquoted scalar values được interpret theo kiểu dữ liệu. Country code hai ký tự NO — mà Na Uy dùng — bị parse thành boolean false trong YAML 1.1. Tương tự YES, ON, OFF, TRUE, FALSE, yes, no, on, off, true, false đều là boolean trong YAML 1.1.

# YAML 1.1 (mặc định của hầu hết parsers trước 2022)
country: NO      # parse thành boolean false — BUG
enabled: yes     # parse thành boolean true
debug: off       # parse thành boolean false

YAML 1.2 đã fix: chỉ true và false (chữ thường) mới là boolean. Nhưng hầu hết parsers (PyYAML, Go's gopkg.in/yaml.v2, Ruby's Psych) vẫn mặc định dùng 1.1. Cách fix an toàn: luôn quote strings có thể bị misinterpret.

TOML với typing chặt hơn

TOML không có sự mơ hồ về kiểu dữ liệu. Trong khi YAML suy luận kiểu từ giá trị, TOML yêu cầu bạn rõ ràng:

# TOML — kiểu dữ liệu không mơ hồ
name = "Alice"          # string
age = 30                # integer
height = 1.75           # float
active = true           # boolean
joined = 2024-01-15     # date (RFC 3339)
tags = ["rust", "dev"]  # array — tất cả phần tử phải cùng kiểu

TOML arrays bắt buộc phải đồng nhất kiểu (tất cả strings, hoặc tất cả integers — không mixed). JSON và YAML cho phép heterogeneous arrays. Điều này có nghĩa convert [1, "two", true] từ JSON sang TOML cần tách thành arrays riêng hoặc từ chối conversion — tool sẽ flag trường hợp này.

Những gì bị mất khi convert

Comments

JSON không có comments. YAML và TOML hỗ trợ. Khi convert YAML→JSON hay TOML→JSON, tất cả comments bị mất vĩnh viễn. Nếu YAML config của bạn dùng comments để document values, convert một bản sao và giữ nguyên bản gốc.

Thứ tự keys

JSON objects về kỹ thuật là unordered. YAML mappings tương tự. TOML sections xuất hiện theo thứ tự document. Khi convert giữa các format, thứ tự keys có thể thay đổi.

Multi-line strings

YAML có syntax multi-line string gọn với | (literal block) và > (folded block). TOML có multi-line basic strings ("""…"""). JSON không có multi-line string syntax — dùng \n escape sequences. Convert YAML literal block sang JSON sẽ nén thành một string một dòng với \n.

Ví dụ thực tế

Convert một đoạn Docker Compose sang JSON để xử lý bằng script:

# YAML input
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    environment:
      NODE_ENV: production

Thành:

{
  "services": {
    "web": {
      "image": "nginx:latest",
      "ports": ["80:80"],
      "environment": {
        "NODE_ENV": "production"
      }
    }
  }
}

Convert dependencies trong Cargo.toml sang YAML:

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

Thành:

dependencies:
  serde:
    version: "1.0"
    features:
      - derive
  tokio:
    version: "1"
    features:
      - full

Privacy

Toàn bộ conversion chạy trong browser. Input không bao giờ được gửi lên server. Tool dùng js-yaml để parse YAML và @iarna/toml để parse TOML — cả hai đều là MIT-licensed libraries được test kỹ lưỡng.

Tại sao boolean values của YAML bị convert ra kết quả bất ngờ?

Bạn đang gặp "Norway problem" của YAML 1.1. Trong YAML 1.1 (vẫn là mặc định của hầu hết parsers), các unquoted values như NO, YES, ON, OFF, True, False được xử lý là boolean thay vì string. Nên country: NO thành {"country": false} trong JSON. Cách fix: quote các strings có thể bị misinterpret — country: "NO" là string rõ ràng trong mọi phiên bản YAML.

Comments có được giữ lại khi convert không?

Không. JSON không có cú pháp comment, nên mọi comment trong YAML hay TOML đều bị mất khi convert sang JSON. Khi convert YAML→TOML hay ngược lại, comments cũng bị mất vì parser loại bỏ chúng. Nếu config files của bạn có comments quan trọng, giữ nguyên bản gốc và coi output convert là bản phái sinh riêng.

Tại sao TOML từ chối mixed-type array của tôi?

TOML yêu cầu arrays phải đồng nhất kiểu — tất cả phần tử phải cùng kiểu. [1, "two", true] valid trong JSON và YAML nhưng invalid trong TOML. Nếu cần mixed types trong TOML, dùng array of inline tables: [{val = 1}, {val = "two"}]. Đây là thiết kế có chủ đích của TOML để kiểu dữ liệu không mơ hồ.

Có thể convert multi-document YAML file (phân cách bởi ---) không?

Multi-document YAML (nhiều documents trong một file phân cách bởi ---) không được hỗ trợ trong tool này — chỉ convert single documents. Tách multi-document YAML thành các files riêng lẻ trước, convert từng cái, rồi kết hợp lại nếu cần.

Output JSON→YAML có quotes quanh values không cần thiết. Vậy có sai không?

Không. YAML cho phép cả quoted và unquoted strings. Converter quote tất cả strings là producing valid, conservative YAML. Unquoted strings chỉ là tối ưu hóa cho dễ đọc, không phải yêu cầu. Giá trị parsed là giống hệt nhau trong cả hai trường hợp.

Điều gì xảy ra với JSON null values khi convert sang TOML?

TOML không có kiểu null. Đây là sự không tương thích thực sự: JSON null không có tương đương trong TOML. Tool bỏ qua null-valued keys trong quá trình JSON→TOML conversion và ghi chú điều này trong output. Nếu cần biểu diễn "absent" trong TOML, dùng sentinel value hoặc cấu trúc lại data để đơn giản là bỏ qua key đó.

Tool này dùng phiên bản YAML nào?

Tool dùng YAML 1.2 semantics qua js-yaml ở strict mode khi có thể, nghĩa là chỉ true và false (chữ thường) mới được parse là boolean. Điều này tránh Norway problem mặc định. Tuy nhiên, nếu bạn paste YAML được generate bởi YAML 1.1 parser (PyYAML, Ruby Psych), values có thể đã bị typed sai từ upstream — kiểm tra JSON output để xác nhận.

Tool này có phù hợp cho Kubernetes hay GitHub Actions YAML không?

Có, để đọc và hiểu các files đó. Convert chúng sang JSON hay TOML chủ yếu hữu ích để xử lý bằng script (ví dụ feed Kubernetes manifest vào script cần JSON). Đừng convert rồi dùng kết quả lại làm Kubernetes manifest — YAML của Kubernetes có field semantics cụ thể cần round-trip cẩn thận.