JSON มี comment ได้ไหม
สรุปสำคัญ: RFC 8259 ไม่มีไวยากรณ์สำหรับ comment ดังนั้น // และ block comment ทำให้ JSON.parse throw ให้เปลี่ยนไปใช้ JSON5 หรือ JSONC, ฟิลด์ _comment, description ใน Schema หรือ YAML แทน
สรุปสั้น ๆ: อย่าใส่ comment ใน JSON มาตรฐานเลย ใช้ JSONC หรือ JSON5 สำหรับ config ในเครื่องที่มนุษย์แก้คนเดียว ย้ายคำอธิบายเข้า description ของ JSON Schema เมื่อไฟล์ต้องข้ามระบบ และเปลี่ยนไปใช้ YAML หรือ TOML เมื่อปริมาณคำอธิบายเพิ่มขึ้น
ไม่ได้
parser ที่เป็นไปตามมาตรฐานจะปฏิเสธสิ่งนี้:
{
"port": 8080 // local development only
}
Chrome รายงาน SyntaxError: Unexpected token } parser เจอ / ซึ่งเริ่มค่า JSON ใด ๆ ไม่ได้ จึงหยุด
ทำไมมาตรฐานถึงจงใจไม่ใส่ comment
RFC 8259 นิยามค่าหกชนิด: object, array, number, string, true/false, null ไม่มี production สำหรับ comment
comment เคยถูกเสนอในยุคแรกและถูกปฏิเสธด้วยเหตุผลที่ชัดเจน: เมื่อ comment ถูกกฎหมายได้ คนก็จะใช้มันบรรทุก directive — การ include ตามเงื่อนไข, ตัวแปร template — แล้ว parser ทุกตัวก็จะโต้แย้งด้วย dialect ของตัวเอง interoperability พังตั้งแต่จุดเชื่อมแรก JSON จึงจงใจเป็นข้อมูลล้วน ไม่มีอะไรที่ execute ได้อยู่ข้างใน
สี่วิธีเก็บคำอธิบายของคุณ
1. ใช้ superset JSON5 และ JSONC รับ comment ได้ทั้งสองสไตล์ settings.json และ tsconfig.json ของ VS Code เป็น JSONC
ต้นทุนมีจริง: JSON.parse ยังปฏิเสธมัน และ API, pipeline ของ log และ message queue มักรับเฉพาะ JSON มาตรฐาน comment ของคุณจะถูกทิ้งอย่างเงียบ ๆ หรือ throw ที่ไหนสักแห่งปลายทาง
2. ใส่หมายเหตุลงในข้อมูล
{
"_comment": "port assigned by ops, do not change",
"port": 8080
}
ใช้ได้ทุกที่ แต่ปนเปื้อนโมเดล: ผู้ใช้ทุกคนต้องรู้ว่า key ไหนควรเพิกเฉย และ type definition ของคุณก็โตขึ้นด้วยฟิลด์ที่ไม่ใช่ข้อมูลจริง
3. ใช้ description ของ Schema description มีไว้สำหรับมนุษย์และเครื่องมือ validator จะเปิดเผยมัน editor แสดงตอน hover และมันไม่เคยเข้าไปใน payload นี่คือทางเลือกเดียวที่อยู่รอดระยะยาวโดยไม่ทำลายความเข้ากันได้
4. เปลี่ยนรูปแบบไฟล์ ถ้าไฟล์มีไว้ให้แก้ด้วยมือ YAML หรือ TOML รองรับ comment โดยธรรมชาติ การฝืนใช้ JSON ตรงนี้คือแรงที่เสียเปล่า
การเลือก
| สถานการณ์ | คำตอบ |
|---|---|
| ส่งไปยังระบบอื่น ผ่าน API หรือ queue | ไม่มี comment; อธิบายใน Schema หรือเอกสารภายนอก |
| config ที่มีแค่มนุษย์และ editor อ่าน | JSONC พร้อมนามสกุล .jsonc |
| ต้องการเครื่องมือสากลและคำอธิบายในบรรทัดเดียวกัน | JSON มาตรฐาน + description ใน Schema |
| config ยาวที่มีคำอธิบายเยอะ | เปลี่ยนไปใช้ YAML |
คำถามที่พบบ่อย
ทำไมฟิลด์ _comment ถึงปนเปื้อนโมเดล?
เพราะมันกลายเป็นส่วนหนึ่งของข้อมูล ผู้ใช้ทุกคนต้องรู้ว่า key ไหนควรเพิกเฉย และ type definition ก็ได้ฟิลด์ที่ไม่ใช่ข้อมูลธุรกิจจริงเพิ่มมา
คำอธิบายควรอยู่ใน description ของ JSON Schema ไหม?
ควร description ไม่เข้าไปใน payload ขณะที่ validator เปิดเผยมันและ editor แสดงตอน hover จึงเป็นทางเลือกเดียวที่อยู่รอดระยะยาวโดยไม่ทำลายความเข้ากันได้
JSONC หรือ JSON5 ถูก JSON.parse อ่านได้ไหม?
ไม่ได้ JSON.parse ยังปฏิเสธ comment และ API, pipeline ของ log และ message queue มักรับเฉพาะ JSON มาตรฐาน comment จึงถูกทิ้งหรือ throw ที่ไหนสักแห่งปลายทาง
เครื่องมือ
- parser JSON5 — วาง config ที่มี comment แล้วดูโครงสร้างที่ resolve ออกมา
- formatter และ validator JSON — JSON ที่ผิดกฎจะถูกรายงานพร้อมบรรทัดและคอลัมน์ ทำให้เห็น comment ที่ก่อปัญหาได้ชัด