JSON Toolkit

JSON có thể có chú thích không

Kết luận: RFC 8259 không có cú pháp chú thích, nên // và chú thích khối làm JSON.parse ném lỗi. Hãy dùng JSON5 hoặc JSONC, một trường _comment, mô tả trong Schema, hoặc YAML thay thế.

Người mớiĐọc khoảng 3 phútXuất bản 2026-10-30Cập nhật 2026-10-30
Tại sao JSON không có chú thích và nên dùng gì thay thế

Tóm lại: đừng bao giờ đặt chú thích trong JSON chuẩn; dùng JSONC hoặc JSON5 cho cấu hình cục bộ chỉ người sửa, chuyển giải thích vào description của JSON Schema khi tệp đi qua ranh giới hệ thống, và chuyển sang YAML hoặc TOML khi lượng chú giải tăng lên.

Không.

Bất kỳ trình phân tích tuân thủ chuẩn nào đều từ chối đoạn này:

{
  "port": 8080 // local development only
}

Chrome báo SyntaxError: Unexpected token }. Trình phân tích gặp /, thứ không thể bắt đầu bất kỳ giá trị JSON nào, và dừng lại.

Tại sao đặc tả cố ý bỏ chú thích

RFC 8259 định nghĩa sáu giá trị: object, mảng, số, chuỗi, true/false, null. Không có luật sinh nào cho chú thích.

Chú thích từng được đề xuất sớm và bị từ chối vì một lý do cụ thể: một khi chú thích là hợp lệ, ai đó sẽ dùng chúng để mang chỉ thị — include có điều kiện, biến template — và mỗi trình phân tích lại mọc ra dialect riêng. Khả năng tương tác hỏng ngay ở chặng đầu. JSON được cố ý thiết kế chỉ chứa dữ liệu, không có gì thực thi được bên trong.

Bốn cách giữ ghi chú của bạn

1. Dùng tập cha. JSON5 và JSONC chấp nhận cả hai kiểu chú thích. settings.json và tsconfig.json của VS Code là JSONC. Cái giá là thật: JSON.parse vẫn từ chối chúng, và API, đường ống log và hàng đợi tin nhắn thường chỉ chấp nhận JSON chuẩn. Chú thích của bạn bị bỏ qua một cách âm thầm hoặc ném lỗi ở đâu đó phía hạ nguồn.

2. Đặt ghi chú trong dữ liệu.

{
  "_comment": "port assigned by ops, do not change",
  "port": 8080
}

Hoạt động ở mọi nơi, nhưng làm ô nhiễm mô hình: mọi phía tiêu thụ đều phải biết khóa nào cần bỏ qua, và định nghĩa kiểu của bạn mọc thêm một trường không thực sự là dữ liệu.

3. Dùng description trong Schema. description được dành cho con người và công cụ. Trình kiểm chứng hiển thị nó, trình soạn thảo hiện nó khi rê chuột, và nó không bao giờ đi vào payload. Đây là lựa chọn duy nhất tồn tại lâu dài qua bảo trì mà không phá vỡ tương thích.

4. Đổi định dạng tệp. Nếu tệp tồn tại để được sửa tay, YAML hoặc TOML hỗ trợ chú thích một cách tự nhiên. Chống lại JSON ở đây là công sức lãng phí.

Chọn cách nào

Tình huống Câu trả lời
Gửi sang hệ thống khác, qua API hoặc hàng đợi Không chú thích; ghi tài liệu trong Schema hoặc tài liệu bên ngoài
Cấu hình chỉ người và trình soạn thảo đọc JSONC, với phần mở rộng .jsonc
Cần công cụ phổ biến và giải thích nội tuyến JSON chuẩn kèm description trong Schema
Cấu hình dài với nhiều chú giải Chuyển sang YAML

Hỏi đáp

Tại sao trường _comment lại làm ô nhiễm mô hình?

Vì nó trở thành một phần của dữ liệu. Mọi phía tiêu thụ đều phải biết khóa nào cần bỏ qua, và định nghĩa kiểu mọc thêm một trường không thực sự là dữ liệu nghiệp vụ.

Có nên đặt giải thích trong description của JSON Schema không?

Có. description nằm ngoài payload, trong khi trình kiểm chứng hiển thị nó và trình soạn thảo hiện nó khi rê chuột, nên đây là lựa chọn duy nhất tồn tại lâu dài qua bảo trì mà không phá vỡ tương thích.

JSONC hoặc JSON5 có thể được JSON.parse phân tích không?

Không. JSON.parse vẫn từ chối chú thích, và API, đường ống log và hàng đợi tin nhắn thường chỉ chấp nhận JSON chuẩn, nên chú thích bị bỏ qua hoặc ném lỗi ở đâu đó phía hạ nguồn.

Công cụ

Đọc thêm