JSON vs YAML vs TOML: Khi Nào Nên Chọn Định Dạng Nào (Cẩm Nang Quyết Định cho Developer)

Bạn đang phân vân chọn định dạng config hoặc dữ liệu, và sự lựa chọn này quan trọng. JSON, YAML, và TOML giải quyết cùng một vấn đề theo các cách khác nhau, và nếu chọn sai bạn sẽ rước thêm ma sát, bug, hoặc đau đầu khi bảo trì. Hãy cứ thẳng vào vấn đề và xây dựng một sơ đồ quyết định rõ ràng nhé.

TL;DR

• JSON: trao đổi dữ liệu và API — phổ biến nhưng cứng nhắc, không có comment.
• YAML: tiêu chuẩn config do con người đọc (Kubernetes, GitHub Actions, Docker Compose) — dễ đọc nhưng mong manh (vấn đề Norway, khoảng trắng). Nhớ bọc nháy chuỗi của bạn.
• TOML: config tường minh, hỗ trợ comment tốt (Cargo.toml, pyproject.toml) — tuyệt vời cho cấu trúc phẳng hoặc lồng nhau nông, nhưng dài dòng nếu cấu trúc quá sâu.

JSON, YAML và TOML thực chất là gì?

JSON là một định dạng văn bản dùng để trao đổi dữ liệu có cấu trúc giữa các hệ thống. Nót rất khắt khe: ngoặc nhọn, key phải bọc nháy, không comment. Nó được thiết kế ưu tiên máy đọc trước, con người đọc sau. RFC 8259 khóa cứng đặc tả này, nên mọi ngôn ngữ đều phân tích cú pháp nó theo cùng một cách.

YAML là một ngôn ngữ config kiêm luôn định dạng tuần tự hóa (serialization). Mục tiêu của nó là khả năng đọc của con người: không cần bọc nháy hầu hết các chuỗi, thụt lề thay thế cho ngoặc, và nó là một siêu tập (superset) của JSON. Red Hat gọi nó là tiêu chuẩn cho tự động hóa — Kubernetes, Ansible, GitHub Actions, và Docker Compose đều nói ngôn ngữ YAML.

TOML là viết tắt của Tom's Obvious, Minimal Language. Nó minh bạch về cấu trúc: bạn khai báo các phần bằng dấu ngoặc vuông, các key luôn hiển thị rõ ràng và comment là công dân hạng nhất. TOML.io định vị nó như một giải pháp thay thế tối giản cho YAML trong các file config — và nó được tích hợp sẵn vào Rust (Cargo.toml) cũng như Python 3.11+.

Vấn đề không phải là cái nào xuất sắc nhất. Mà là cái nào phù hợp với trường hợp sử dụng của bạn. Hãy thử ném một đoạn code mẫu vào bộ chuyển đổi JSON↔YAML↔TOML của chúng tôi để xem cùng một dữ liệu được biểu diễn thế nào dưới cả ba góc độ.

Khi nào nên chọn JSON?

Hãy chọn JSON khi các hệ thống trao đổi dữ liệu và con người không cần tự tay chỉnh sửa file. JSON là ngôn ngữ chung của thế giới web: API trả về nó, log dùng nó, các công cụ chấp nhận nó. Mọi ngôn ngữ đều có parser, và tất cả đều xử lý y hệt nhau, nên bạn sẽ không bị giật mình bởi sự dị biệt của parser này so với parser khác.

Đánh đổi ở đây là JSON khá dài dòng đối với con người. Không có comment bởi vì đặc tả cấm điều đó. Bắt buộc bọc nháy mọi key. Từ chối dấu phẩy cuối cùng. Tự tay chỉnh sửa config bằng JSON đúng là một cơn ác mộng. Hãy dùng nó cho API, xuất dữ liệu giữa các công cụ và log do máy tạo ra — chớ đừng dùng làm file config để duy trì.

Khi nào nên chọn YAML?

Hãy chọn YAML khi con người thường xuyên sửa config và bạn muốn cú pháp tối giản nhất. Nó là tiêu chuẩn trên thực tế cho Kubernetes manifests, GitHub Actions, Docker Compose và Ansible. Chuỗi không cần bọc nháy, thụt lề định hình cấu trúc, và nó đọc giống như code giả (pseudo-code) vậy.

database:
  host: localhost
  port: 5432
  user: admin

Nhìn qua nhanh hơn nhiều so với JSON tương đương đúng không? Nhưng sự dễ đọc luôn đi kèm với cái giá, và cái giá đó có tên.

Những cái bẫy YAML mà dev nào cũng cần biết

Vấn đề Norway (Na Uy) là cú lừa nổi tiếng nhất. Trong YAML 1.1 — vốn vẫn là mặc định ở PyYAML và một số parser, các từ không bọc nháy như yes, no, on và off sẽ bị phân tích thành boolean chứ không phải chuỗi như tác giả StrictYAML đã chỉ ra.

country_code: NO
enabled: yes

Sẽ bị phân tích thành country_code: false, enabled: true. Mã quốc gia của Na Uy NO lặng lẽ biến thành boolean false. Không có bất kỳ lỗi cú pháp nào báo về — chỉ là một giá trị sai bét. Cách khắc phục là bọc nó lại: country_code: "NO".

Khoảng trắng cũng là thứ thiêng liêng. YAML cấm dùng phím Tab, thụt lề 2 khoảng trắng là chuẩn mực, và chỉ một dòng lệch đi một chút cũng sẽ bị dịch sai bét mà không báo lỗi. Một ký tự Tab vô tình dán từ trình soạn thảo rich-text có thể làm hỏng toàn bộ file. Bài học rút ra: YAML thân thiện với con người nếu bạn kỷ luật — bọc nháy các chuỗi dễ nhầm lẫn, chạy linter và xác thực bằng trình định dạng YAML của chúng tôi trước khi đưa lên production.

Khi nào nên chọn TOML?

Hãy chọn TOML khi bạn muốn cấu trúc tường minh và khả năng comment thực sự. Nó map trực tiếp vào một hash table, các phần được khai báo rõ ràng, và comment là một phần của ngôn ngữ. Đây là tiêu chuẩn cho Cargo.toml của Rust và pyproject.toml của Python.

[database]
host = "localhost"
port = 5432  # Ở đây comment là công dân hạng nhất nhé

Nhược điểm duy nhất là sự dài dòng khi cấu trúc lồng vào nhau quá sâu. Ở mức lồng thứ ba, TOML sẽ phải lặp lại toàn bộ đường dẫn của section ([servers.alpha.ports]) trong khi YAML chỉ cần thụt lề thêm một chút. Hãy dùng TOML cho các config phẳng hoặc nông; và quay sang YAML khi "cái cây" bắt đầu rễ sâu.

Bảng quyết định

Hãy định dạng JSON của bạn trước bằng trình định dạng JSON của chúng tôi, sau đó chuyển đổi qua lại giữa cả ba loại để so sánh cấu trúc của chúng.

Làm thế nào để chuyển đổi giữa JSON, YAML và TOML?

Hầu hết thời gian, bạn sẽ không tự viết lại bằng tay đâu, mà là dùng công cụ chuyển đổi. Bởi vì YAML 1.2 là một siêu tập của JSON và cả ba đều mô tả chung một kiểu cấu trúc key-value lồng nhau, nên các công cụ có thể dịch chúng một cách cơ học. Điều này cực kỳ hữu ích khi bạn được giao sẵn một file config bằng YAML nhưng muốn xem nó trông như thế nào dưới dạng TOML, hoặc khi API ném cho bạn JSON và bạn muốn một phiên bản dễ đọc hơn để ngâm cứu.

Vài quy tắc sẽ sống sót qua mọi lần chuyển đổi, và vài thứ thì không. Key, value, số liệu, và các cấp bậc lồng nhau sẽ được giữ nguyên hoàn hảo. Còn comment thì không: JSON không có chỗ để chứa chúng, nên việc chuyển đổi một file TOML hay YAML có chứa comment sang JSON sẽ đánh rơi hết mọi ghi chú. Kiểu dữ liệu cũng có thể bị biến đổi, và đây chính là chỗ cái bẫy Norway cắn bạn. Chuyển country_code: NO từ YAML 1.1 sang JSON, bạn có thể sẽ nhận về false thay vì "NO".

Quy trình an toàn là: chuyển đổi xong, hãy đọc lướt lại kết quả trước khi commit. Dán file của bạn vào bộ chuyển đổi JSON↔YAML↔TOML, kiểm tra xem chuỗi có còn là chuỗi không và có gì quan trọng biến mất không, rồi mới lưu vào dự án. Để rà soát nhanh cho một file đơn lẻ, JSON formatter sẽ đánh dấu các lỗi cấu trúc trước khi chúng kịp ngấm vào bản build của bạn.

Những định dạng này có xử lý ngày tháng và số liệu giống nhau không?

Không đâu, và khoảng cách này quyết định nhiều file config hơn bạn tưởng. JSON giữ hệ thống kiểu dữ liệu của nó cố tình thu nhỏ lại. Nó có chuỗi, số, boolean, null, mảng, và object, và không có gì khác trong đặc tả. Nó không có kiểu dữ liệu ngày tháng hay thời gian gốc, vì vậy một dấu thời gian (timestamp) trong JSON thực ra chỉ là một chuỗi mà code của bạn phải tự phân tích và tin tưởng nó đúng.

TOML thì đi theo hướng ngược lại. Nó có các kiểu ngày và giờ được tích hợp sẵn ở cấp độ đầu tiên, vì vậy một timestamp có múi giờ hoặc một ngày cụ thể sẽ là một giá trị thực sự được xác thực, thay vì một chuỗi mà bạn cứ thấp thỏm hy vọng là nó định dạng đúng. Điều này khiến TOML trở nên rất thú vị để làm config ghi lại các lịch trình, phiên bản hoặc ngày phát hành. YAML nằm ở giữa, với việc xử lý ngày tháng tùy chọn phụ thuộc vào từng parser và phiên bản.

Bài học mang tính thực tiễn là: Nếu config của bạn có dựa dẫm vào các ngày tháng thực tế và bạn muốn định danh đó xác thực chúng giúp bạn, TOML sẽ giúp bạn tiết kiệm được một bước parse dữ liệu. Nếu bạn chỉ trao đổi dữ liệu với các hệ thống khác và tự xử lý kiểu dữ liệu trong code thôi, thì bộ kiểu dữ liệu siêu nhỏ của JSON lại là một điểm cộng chứ không phải giới hạn.

XML và INI thì sao?

Chúng vẫn tồn tại, và đôi khi lại là lựa chọn đúng đắn. XML là "ông nội" dài dòng của gia đình này. Nó rất khắt khe, thân thiện với lược đồ (schema) và vẫn là tiêu chuẩn trong các hệ thống doanh nghiệp, SOAP API và các định dạng tài liệu như .docx. Cái giá phải trả là cú pháp nặng nề: mỗi giá trị đều kẹp giữa thẻ mở và thẻ đóng, khiến file XML dài gấp hai đến ba lần so với JSON tương đương. Chỉ nên dùng khi một hệ thống hoặc tiêu chuẩn bắt buộc phải có nó.

INI thì ngược lại, là một định dạng cổ kính, siêu nhỏ gọn với các dòng key = value gom nhóm dưới [sections]. Nó cực kỳ đơn giản và vẫn phổ biến trong các ứng dụng desktop cũ hoặc một số công cụ. Vấn đề là INI chưa bao giờ được tiêu chuẩn hóa chính thức, nên hai parser có thể sẽ không đồng ý với nhau về cách lồng cấu trúc, phân loại kiểu dữ liệu hay comment. Thật ra thì, bạn nên hiểu TOML chính là một bản INI có đặc tả chuẩn và quy tắc rõ ràng, đó là lý do tại sao các dự án mới gần như luôn chọn TOML thay vì INI.

Đối với mọi dự án mới, ba định dạng hiện đại này đã bao trùm hết mọi nhu cầu rồi. Chỉ cần nhớ XML và INI khi bạn làm việc bên trong một hệ thống đã quen dùng chúng mà thôi.

Tóm lại

Máy móc trao đổi dữ liệu thì dùng JSON. Con người sửa các config nông thì dùng TOML. Hệ sinh thái như Kubernetes và CI/CD thì dùng YAML — nhớ bọc nháy chuỗi và lint gắt gao là được. Định dạng tốt nhất thường là cái mà tech stack của bạn đang dùng; cố đấu tranh lại cả một hệ sinh thái thì đúng là một cuộc chơi thua cuộc.

Tóm lại: Máy móc trao đổi dữ liệu → JSON. Con người sửa config nông → TOML. Kubernetes / CI/CD → YAML (nhớ bọc nháy chuỗi nhé). Vấn đề Norway sẽ mắc bạn đúng một lần; sau đó, bạn sẽ tự động bọc nhạy các chuỗi của mình thôi.