JSON, TOML, YAML או CSON: בחירת פורמט הגדרה

שורה תחתונה: השתמשו ב-JSON להחלפה בין מכונות, ובחרו TOML או YAML להגדרה שמתוחזקת בידי אדם לפי האקוסיסטם (YAML ל-Kubernetes ו-CI, TOML למבנים שטוחים או תאריכים מקוריים); חזרו ל-JSONC רק כשאינכם בטוחים שהקורא תומך בניב.

JSON קיים בשביל מכונות שמחליפות נתונים; קובץ הגדרה נכתב בידי אנשים בשביל אנשים. ערבבו את השניים ותקבלו config.json שלא יכול להחזיק הערה ואף אחד לא מעז לקצץ.

1. התחילו משני סוגים שונים של קבצים

החלפת נתונים והגדרה אינן חולקות את אותה מטרה, למרות שאותו אדם כותב לעתים קרובות את שניהם באותה מכונה.

JSON מקבל ציון כמעט מושלם בעמודה השמאלית: דקדוק מינימלי, מפרסר בכל שפה, והיעדר הערות אומר שאין בעיית "ההערה נסחפה מהערך". בעמודה הימנית, הקפדנות שלו היא חיכוך טהור: אין הערות, אין פסיקים בסוף, אין תאריכים, וטקסט מרובה-שורות חייב להתכווץ לשורה אחת עם \n.

2. ארבעת המתחרים והתחביר שלהם

• JSON: מוגדר ב-RFC 8259 וב-ECMA-404, עם בדיוק שישה טיפוסי ערך: אובייקט, מערך, מחרוזת, מספר, בוליאני ו-null. זהו תקן ההחלפה בפועל והפורמט היחיד שאינו דורש החלטת בחירה.
• TOML: נוצר בידי Tom Preston-Werner, כאשר v1.0.0 פורסם בינואר 2021. מטרתו המוצהרת היא פורמט הגדרה מינימלי עם סמנטיקה ברורה שממפה באופן חד-משמעי לטבלת hash. Cargo.toml ו-pyproject.toml משתמשים בו כברירת מחדל.
• YAML: המפרט הנוכחי הוא 1.2.2. הזחה מבטאת היררכיה, והוא תומך בהערות, בעוגנים ובכמה מסמכים. מניפסטים של Kubernetes, GitHub Actions ו-Ansible כולם תלויים בו, במחיר של מפרט גדול והבדלי מימושים.
• CSON: CoffeeScript Object Notation, שכותב הגדרות באמצעות ליטרלים של אובייקט CoffeeScript. config.cson של Atom השתמש בו. הוא תומך בהערות, במפתחות בלי מרכאות ובפסיקים בסוף, אבל האקוסיסטם שלו מעולם לא עזב את עולם JavaScript.

2.1 השוואת יכולות

שני תאים ראויים להערה. ל-TOML אין null, וזה הכשל הנפוץ ביותר בהמרה מ-JSON. התנהגות "תאריך מקורי" של YAML אומרת שמפרסר 1.1 הופך 2026-10-31 לאובייקט תאריך אוטומטית, כך שהטיפוס נסחף בין שפות.

3. הערות: החולשה היחידה של JSON

המסקנה קודם: אם אדם מתחזק את הקובץ וצריך להסביר למה ערך הוא מה שהוא, אל תשתמשו ב-JSON סטנדרטי.

יש ארבעה מסלולים מעשיים, מסודרים לפי כמה הם פולשניים:

1. עברו ל-JSONC, שהוא JSON סטנדרטי בתוספת הערות ופסיקים בסוף. settings.json ו-tsconfig.json של VS Code משתמשים בו. המחיר הוא שהקורא חייב להשתמש במפרסר מודע להערות כמו jsonc-parser; JSON.parse רגיל נכשל. פרטים ב-JSON5 ו-JSONC: JSON עם הערות.
2. שמרו מסמך לוואי. config.json נשאר קריא למכונה, בעוד config.md מסביר מה כל שדה אומר ולמה יש לו את הערך הזה. שניהם יושבים באותה ספרייה ומשתנים באותו commit.
3. שימו הסברים בסכימה. מילות המפתח description ו-$comment של JSON Schema יכולות לתעד שדות, אבל סכימות לעתים רחוקות נשלחות יחד עם הגדרות runtime, ולכן מי שקורא את ההגדרה אולי לעולם לא יראה אותן.
4. עברו ל-TOML או YAML, ותנו לפורמט עצמו לספק הערות שכל מפרסר מבין.

复制{
  // Fixed at 8080: the frontend build script reads this port for its proxy
  "port": 8080,
  // Disable watching to avoid exhausting inodes in CI
  "watch": false
}

JSONC הוא עדיין ניב: הסיומת נשארת .json, אבל רק חלק מהכלים מבינים אותו. כשנתונים עוזבים את הצוות או חוצים גבול שירות, הגבול בין JSONC ל-JSON סטנדרטי חייב להיות מתועד.

4. תאריכים ומחרוזות מרובות-שורות: השטח הביתי של TOML

TOML מקדם תאריך-שעה לטיפוס ממדרגה ראשונה עם ארבעה וריאנטים: תאריך-שעה עם היסט, תאריך-שעה מקומי, תאריך מקומי ושעה מקומית. למחרוזות מרובות-שורות יש תחביר ייעודי שמשמר שבירות שורה:

复制title = "json-toolkit"
created = 2026-10-31T09:00:00+08:00
description = """
A JSON toolkit for developers.
Every operation runs locally in the browser.
"""

אותו מידע ב-JSON חייב להוריד את התאריך למחרוזת ולהימלט את שבירות השורה:

复制{
  "title": "json-toolkit",
  "created": "2026-10-31T09:00:00+08:00",
  "description": "A JSON toolkit for developers.\nEvery operation runs locally in the browser."
}

ב-JSON, "created" הוא רק מחרוזת שמקרה נראית כמו תאריך, ולכן מידע הטיפוס חייב לחיות בחוזה שדה: שני הצדדים חייבים להסכים שהשדה הוא תמיד RFC 3339. TOML נותן למפרסר אובייקט תאריך ממשי בלי הסכמה מילולית.

YAML יכול גם להחזיק טקסט מרובה-שורות, אבל שני סגנונות ה-block אומרים דברים שונים: | משמר שבירות שורה בעוד > מקפל אותן לרווחים. בחרו את הלא נכון וכתובת או הצהרת SQL מתכווצות לשורה אחת, שגיאה שקשה מאוד לתפוס בסקירה.

5. מספרים: ההבדל הקל ביותר לפספס

מפרט JSON לא מגביל דיוק מספרי, אבל RFC 8259 גם מזהיר שתאימות היא הבטוחה ביותר כשמספרים מטופלים כ-double של IEEE 754. ב-JavaScript, מספרים שלמים מעל 2^53 - 1 מאבדים דיוק בשקט:

复制JSON.parse('{"id":9007199254740993}').id
// 9007199254740992: the last digit is gone

TOML דורש שמספרים שלמים של 64 ביט עם סימן יטופלו ללא אובדן ושהוא יזרוק שגיאה במקום לחתוך בשקט; floats הולכים לפי binary64 ויכולים להיות גם inf או nan. ל-YAML 1.1 יש נטל ישן יותר: 1:30 נפרסר כ-90 (סקסגסימלי), ובוליאנים מקבלים yes, no, on ו-off. מכאן "בעיית נורווגיה" הקלאסית, שבה קוד המדינה NO הופך ל-false.

לכסף, לעולם אל תסתמכו על נקודה צפה באף אחד מהפורמטים האלה: השתמשו ביחידות משנה שלמות, מחרוזות או טיפוס decimal של בסיס נתונים. עיצוב ודיוק מכוסים לעומק יותר ב-גבולות ההמרה בין JSON, YAML ו-XML.

6. טבלאות וקינון: הגבולות הקשיחים של TOML

TOML מבטא קינון עם טבלאות ומערכים של טבלאות:

复制[server]
port = 8080

[[routes]]
path = "/parse"
method = "POST"

[[routes]]
path = "/minify"
method = "POST"

יש לו שני גבולות קשיחים שחייבים להכיר לפני המרה:

• השורש של מסמך TOML הוא טבלה, ולכן מסמך JSON שרמתו העליונה היא מערך (כמו [1, 2, 3]) אין לו ייצוג TOML חוקי; חייבים לעטוף אותו כ-{"items": [...]};
• ל-TOML אין null, ולכן שדה null של JSON חייב או להיות מושמט או להיות מוחלף במחרוזת ריקה או בערך סנטינל, כאשר הסמנטיקה נדחפת אל הצרכן.

YAML הוא ההיפך: עומק הקינון בלתי מוגבל, ועוגנים בתוספת מפתחות מיזוג יכולים להשתמש מחדש בקטעים:

复制defaults: &defaults
  retries: 3
  timeoutMs: 5000

server:
  <<: *defaults
  port: 8080

עוגנים הם יכולת ייחודית ל-YAML ואובדן מובטח בזמן המרה: ל-JSON אין תחביר הפניה, כך שהקובץ המורחב גדל ושום דבר לא מתעד ששני הקטעים היו פעם אותה הגדרה.

7. בחירה לפי תרחיש

כלל אצבע: תנו לאקוסיסטם לבחור את פורמט ההגדרה, לא להעדפה אישית. כתיבת Rust אומרת Cargo.toml, פריסה ל-Kubernetes אומרת YAML, ובניית תוסף VS Code אומרת JSONC. רק בפרויקט חדש בלי אילוצי אקוסיסטם "איזה מהם נעים יותר לכתוב" היא שאלה אמיתית.

8. גבולות המרה

כלי המרה מבטיחים את הערכים, לעולם לא את ההערות. לכן אל תתכננו צינור דו-כיווני שבו "JSON הוא המקור ו-YAML הוא תוצר build". או שתייצרו בכיוון אחד בלבד, או שתתחזקו קובץ מקור יחיד.

9. רשימת בדיקה

• [ ] תעדו אילו סוגי קבצים משתמשים באיזה פורמט, ורשמו את הניבים המותרים;
• [ ] העדיפו TOML או YAML להגדרה שמתוחזקת בידי אדם, ו-JSON להחלפה בין מכונות;
• [ ] אחסנו תאריכים ב-JSON כמחרוזות RFC 3339 וסמנו את הפורמט בסכימה;
• [ ] ייצגו כסף ומספרים שלמים מעל 2^53 כמחרוזות או כיחידות משנה, לעולם לא כ-floats;
• [ ] אמתו כל פורמט ב-CI עם המפרסר שלו, לעולם לא עם JSON.parse עבור YAML;
• [ ] המירו פורמטים בכיוון אחד בלבד, ומחקו את הקובץ הישן כדי שלא ייסחפו.

FAQ

למה המרה מ-JSON ל-TOML נכשלת בכמה שדות?

ל-TOML אין null, והשורש של מסמך TOML הוא טבלה, ולכן שדה null של JSON חייב להיות מושמט או מוחלף במחרוזת ריקה או בסנטינל, ומערך ברמה העליונה חייב להיעטף כ-{"items": [...]}. הערות, טיפוסי תאריך ו-inf/nan גם הם אובדים כשעוברים בכיוון ההפוך, ולכן המרה צריכה להיות חד-כיוונית.

כדאי להחזיק שני קובצי הגדרה בפורמטים שונים?

לא. כלי המרה מבטיחים את הערכים אבל לעולם לא את ההערות, ולכן צינור שבו "JSON הוא המקור ו-YAML הוא תוצר build" ייסחף. או שתייצרו בכיוון אחד בלבד, או שתתחזקו קובץ מקור יחיד ותמחקו את הישן אחרי המיגרציה.

איך מוסיפים הערות לקובץ הגדרה של JSON?

ל-JSON סטנדרטי אין הערות. אפשר לעבור ל-JSONC (הניב של VS Code, נקרא עם jsonc-parser), לשמור מסמך לוואי שמסביר כל שדה, או לעבור ל-TOML או YAML. קבצים שנשלחים למערכות אחרות צריכים להישאר JSON סטנדרטי, כאשר ההסברים חיים בתיעוד או בסכימה.

TOML או YAML עדיף להגדרת יישום?

בחרו TOML כשהמבנה שטוח, בעיקרו זוגות מפתח-ערך, ותאריכים מקוריים חשובים; הסמנטיקה שלו צפויה יותר והבדלי המפרסרים קטנים יותר. בחרו YAML כשצריך קינון עמוק, כמה מסמכים, שימוש חוזר בעוגנים, או כשאקוסיסטם היעד הוא YAML תחילה, כמו Kubernetes או CI. שניהם תומכים בהערות, ולכן המבדיל האמיתי הוא מורכבות מבנית ונעילה לאקוסיסטם.

למה NO הופך ל-false ב-YAML?

YAML 1.1 מתייחס ל-yes, no, on, off, y ו-n כבוליאנים, כך שקוד המדינה של נורווגיה NO נפרסר כ-false. זו "בעיית נורווגיה". הימנעו ממנה על ידי שימוש במימוש שהולך לפי YAML 1.2, או על ידי עטיפת כל מחרוזת שעלולה להיפרסר שגוי במרכאות.

האם CSON עדיין שווה שימוש?

לא לפרויקטים חדשים. CSON תלוי באקוסיסטם של CoffeeScript, יש לו מעט כלים מתוחזקים, ותמיכת עורכים ו-CI מוגבלת; אחרי ש-Atom הפסיק להיות מתוחזק תרחישי השימוש שלו הצטמצמו עוד. אם לפרויקט כבר יש הגדרות CSON, תכננו מיגרציה חד-פעמית ל-JSON, TOML או YAML במקום להוסיף עוד.