האם JSON יכול להכיל הערות
שורה תחתונה: ל-RFC 8259 אין תחביר להערות, כך ש-// והערות בלוק גורמות ל-JSON.parse לזרוק שגיאה. השתמשו ב-JSON5 או JSONC, בשדה _comment, ב-description של Schema או ב-YAML במקום.
שורה תחתונה: לעולם אל תשימו הערות ב-JSON סטנדרטי; השתמשו ב-JSONC או JSON5 לקונפיגורציה מקומית שרק בני אדם עורכים, העבירו הסברים ל-description של JSON Schema כשהקובץ חוצה מערכות, ועברו ל-YAML או TOML כשנפח ההערות גדל.
לא.
כל מפרס שתואם לתקן דוחה את זה:
{
"port": 8080 // local development only
}
Chrome מדווח SyntaxError: Unexpected token }. המפרס נתקל ב-/, שאינו יכול לפתוח שום ערך JSON, ועצר.
למה המפרט משמיט הערות בכוונה
RFC 8259 מגדיר שישה ערכים: אובייקט, מערך, מספר, מחרוזת, true/false, null. אין כלל ייצור להערות.
הערות הוצעו בשלב מוקדם ונדחו מסיבה קונקרטית: ברגע שהערות חוקיות, מישהו משתמש בהן לשאת הנחיות — כוללות מותנות, משתני תבנית — וכל מפרס מפתח דיאלקט משלו. התאימות בין מערכות נשברת כבר בקפיצה הראשונה. JSON הוא במכוון נתונים בלבד, בלי שום דבר ניתן לביצוע בתוכו.
ארבע דרכים לשמור את ההערות שלכם
1. השתמשו בעל-קבוצה. JSON5 ו-JSONC מקבלים את שני סגנונות ההערות. settings.json ו-tsconfig.json של VS Code הם JSONC.
המחיר אמיתי: JSON.parse עדיין דוחה אותם, ו-API, pipelines של לוגים ותורי הודעות מקבלים בדרך כלל רק JSON סטנדרטי. ההערה שלכם נשמטת בשקט או זורקת שגיאה במקום כלשהו בהמשך.
2. שימו את ההערה בתוך הנתונים.
{
"_comment": "port assigned by ops, do not change",
"port": 8080
}
עובד בכל מקום, אבל מזהם את המודל: כל צרכן צריך לדעת אילו מפתחות להתעלם מהם, והגדרת הטיפוס שלכם מקבלת שדה שאינו באמת נתונים.
3. השתמשו ב-description של Schema. description מיועד לבני אדם ולכלים. ולידטורים חושפים אותו, עורכים מציגים אותו בריחוף, והוא לעולם לא נכנס למטען. זו האפשרות היחידה ששורדת תחזוקה ארוכת טווח בלי לשבור תאימות.
4. החליפו את פורמט הקובץ. אם הקובץ קיים כדי להיערך ביד, ל-YAML או TOML יש תמיכה מקורית בהערות. להיאבק ב-JSON כאן הוא מאמץ מבוזבז.
בחירה
| מצב | תשובה |
|---|---|
| נשלח למערכת אחרת, דרך API או תור | בלי הערות; תעדו ב-Schema או בתיעוד חיצוני |
| קונפיגורציה שנקראת רק על ידי בני אדם ועורכים | JSONC, עם סיומת .jsonc |
| צריך כלים אוניברסליים והסבר inline | JSON סטנדרטי בתוספת description ב-Schema |
| קונפיגורציה ארוכה עם הרבה הערות | עברו ל-YAML |
שאלות ותשובות
למה שדה _comment מזהם את המודל?
כי הוא הופך לחלק מהנתונים. כל צרכן צריך לדעת אילו מפתחות להתעלם מהם, והגדרת הטיפוס מקבלת שדה שאינו באמת נתונים עסקיים.
האם ההסבר צריך לחיות ב-description של JSON Schema?
כן. description נשאר מחוץ למטען, בעוד וולידטורים חושפים אותו ועורכים מציגים אותו בריחוף, כך שזו האפשרות היחידה ששורדת תחזוקה ארוכת טווח בלי לשבור תאימות.
האם JSON.parse יכול לפרס JSONC או JSON5?
לא. JSON.parse עדיין דוחה הערות, ו-API, pipelines של לוגים ותורי הודעות מקבלים בדרך כלל רק JSON סטנדרטי, כך שההערה נשמטת או זורקת שגיאה במקום כלשהו בהמשך.
כלים
- מפרס JSON5 — הדביקו קונפיגורציה עם הערות וראו את המבנה שנפתר
- מעצב ומאמת JSON — JSON לא חוקי מדווח עם שורה ועמודה, כך שההערה הבעייתית בולטת