המרת XML ל־JSON

מה הכלי הזה עושה

XML מגיע לרוב ממערכות שאיש לא בחר בהן: תשובת SOAP, הזנת RSS, קובץ הגדרות, ייצוא ממשהו ותיק יותר מ־JSON. הקוד שצריך להשתמש בו רוצה JSON. ההפך נפוץ באותה מידה: מסמך JSON שמיועד למערכת שמקבלת רק XML. הדף הזה ממיר בשני הכיוונים, בדפדפן שלכם, וקורא את שניהם לפי מערכת כללים אחת וקבועה, כך ששני הכיוונים מסכימים על המשמעות של כל מפתח.

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

הכללים: @ לתכונה, ‎#text לטקסט

יש מערכת כללים אחת, ושום הגדרה אינה משנה אותה. תכונה הופכת למפתח שנכתב כ־@ ואחריו שם התכונה, וטקסט שצריך לחלוק את האלמנט שלו עם כל דבר אחר נכנס תחת המפתח ‎#text. אף שם XML אינו יכול להתחיל ב־@ או ב־#, ולכן אי אפשר לטעות ולחשוב שמפתח שנכתב כך הוא אלמנט בן, וזה מה שמאפשר לקרוא את אותו JSON בחזרה ל־XML בלי לנחש. כך זה נראה על קטלוג קטן:

• אלמנט השורש הוא המפתח היחיד בראש המסמך: מסמך שאלמנט השורש שלו הוא catalog הופך לאובייקט עם המפתח היחיד "catalog".
• אלמנט שמחזיק רק טקסט הוא הטקסט הזה: <title>Midnight Rain</title> הופך ל־"title": "Midnight Rain".
• תכונה היא מפתח לצד האלמנטים הבנים: ‎<book id="bk101">‎ נותן לספר את "‎@id": "bk101", וכל אלמנט בן בא אחריו כמפתח, לפי הסדר שבו הוא מופיע לראשונה.
• אלמנט עם תכונות וטקסט שומר את הטקסט תחת ‎#text: למשל, <price currency="USD">44.95</price> הופך ל־‎"price": {"@currency": "USD", "#text": 44.95}.
• אלמנט שחוזר תחת אותו אב הופך למערך: לספר שאלמנט ה־author שלו מופיע פעמיים יש ‎"author": ["Gambardella, Matthew", "Knorr, Stefan"].
• שמות נשמרים בדיוק כפי שנכתבו, כולל הקידומת: <dc:title> הופך למפתח "dc:title", הצהרת מרחב שמות הופכת למפתח של תכונה כמו "‎@xmlns:dc", ושום דבר אינו מתורגם ל־URI של מרחב שמות.

ישויות והפניות תו מפוענחות, כך ש־‎&amp;‎ מגיע כ־& ו־‎&#233;‎ כ־é, ומקטע CDATA הוא פשוט טקסט. רווח לבן שעומד לבדו בין אלמנטים הוא עיצוב בלבד ומושמט; כל רצף טקסט אחר נשמר במלואו, ושום רווח אינו מוסר מקצותיו. שני הנרמולים שכל קורא XML תואם תקן מבצע עדיין באים קודם: החזרת גררה שנכתבה בתוך טקסט מגיעה כמעבר שורה, וטאב או מעבר שורה שנכתבו בתוך ערך של תכונה מגיעים כרווח. הפניית תו היא הדרך שבה מסמך שומר על כל אחד מהם.

למה המסמך כולו קובע את המבנה

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

לכן המבנה נקבע לפי נתיב: שמות האלמנטים מהשורש ועד האלמנט, שנכתבים כ־‎/catalog/book/author, בלי מיקומים, כך שכל מחבר של כל ספר עומד על אותו נתיב. כל האלמנטים שעל נתיב נשקלים יחד:

• מערכים. אם האלמנט חוזר תחת אב אחד כלשהו, כל אלמנט על הנתיב נכתב כמערך, גם אלמנט שמופיע לבדו.
• אובייקטים. אם אלמנט כלשהו על הנתיב נושא תכונה או אלמנט בן, כל אלמנט עליו נכתב כאובייקט, גם אלמנט שמחזיק רק טקסט, ושומר את הטקסט שלו תחת ‎#text.
• ערכים. נתיב נקרא כמספרים רק אם כל ערך עליו מומר, וכבוליאנים רק אם כל ערך עליו הוא true או false, לפי הכלל שמתואר בהמשך, בפרק על מספרים ובוליאנים.
• אלמנטים ריקים. אלמנט ריק אינו משתתף בהחלטות האלה, ומקבל את הסוג שנקבע לנתיב שלו.

בכל מקום שבו התוצאה שונה ממה שהאלמנט היה לבדו, הדף אומר זאת פעם אחת לנתיב, עם השורה והעמודה של האלמנט הראשון שהשתנה. בקטלוג שבו לספר אחד יש כמה מחברים ולאחר רק אחד, המחבר היחיד הזה עדיין נכתב כמערך; היכן שמחיר אחד נושא תכונת currency ואחר לא, המחיר הפשוט עדיין נכתב כאובייקט, והטקסט שלו תחת ‎#text. שני המקרים מדווחים, כך שאף אחד מהם אינו מפתיע את הקוד שקורא אותם.

דוגמה עם רשומה אחת, והשדה «תמיד מערכים»

המבנה טוב רק כמו המסמך שלפיו הוא נקבע. הדביקו קטלוג שיש בו ספר אחד, והספר הזה יהיה אובייקט, המחבר היחיד שלו מחרוזת והמחיר שלו מספר, בעוד שאותו קטלוג עם ספר שני לצדו הופך את הספרים למערך. נתיב שמופיע פעם אחת בכל מקום במה שהדבקתם נשאר ערך יחיד, ונתיב שכל ערכיו במקרה מומרים נשאר מספרים עד שמגיע מסמך עם מיקוד שמתחיל באפס. ה־JSON אמין בדיוק במידה שהדוגמה מייצגת, ולכן הדביקו יותר מרשומה אחת בכל פעם שאפשר.

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

• שם בודד כמו item מגיע לכל נתיב שמסתיים באלמנט בשם item, בכל מקום שבו הוא עומד.
• נתיב כמו ‎/rss/channel/item מגיע לנתיב הזה בלבד, והוא נכתב כפי שנכתבים הנתיבים שמתחת לפלט, כך שאפשר להעתיק אחד משם.
• ההתאמה מדויקת: אותיות גדולות וקטנות נחשבות, וקידומת היא חלק מהשם, ולכן Item אינו מגיע לאף item ו־link אינו מגיע לאף atom:link.
• כל נתיב שהשדה הפך למערך מדווח כמו כל החלטה אחרת. פריט שאינו שם ואינו נתיב, ופריט שלא הגיע לאף אלמנט במסמך, מופיעים מתחת לשדה, והפריטים שכן חלים ממשיכים לחול.

השדה שייך לכיוון «XML ל־JSON». הוא שומר את מה שהקלדתם כשמחליפים כיוון וחוזרים, וכמו כל הגדרה בדף הוא אינו נשמר בין ביקורים. לערכים אין שדה כזה: נתיב שחייב להישאר טקסט בלי קשר למה שיש בדוגמה הוא בדיוק מה שכיבוי «המר מספרים ובוליאנים» נועד לו, במחיר של הפיכת כל ערך אחר לטקסט גם הוא.

מספרים, בוליאנים, ולמה 02134 נשאר טקסט

ב־XML הכול טקסט, והמרה של טקסט שנראה מספרי למספרי JSON היא בדרך כלל מה שרוצים. זו גם הדרך שבה מיקוד 02134 הופך ל־2134, ומספר הזמנה ארוך מאבד את ספרותיו האחרונות. הכלל כאן הוא אותו כלל שבו משתמש ממיר ה־CSV שבאתר הזה, והוא אינו צריך רשימה של מקרים מיוחדים: טקסט הופך למספר רק אם המספר הזה, כשהוא נכתב בחזרה, משחזר את הטקסט בדיוק. 42 עובר, ולכן מומר. 02134 לא, וגם לא 1.50, ‏‎+5, ‏1e5 או מספר שלם ארוך מכדי שנקודה צפה בדיוק כפול תחזיק את כל ספרותיו. הבוליאנים הם בדיוק true ו־false, באותיות קטנות.

מה שהדף הזה מוסיף הוא שהכלל נשאל על נתיב שלם בבת אחת. נתיב נקרא כמספרים רק אם כל ערך עליו מומר, וכבוליאנים רק אם כל ערך עליו הוא בוליאני; ערך יחיד שהיה מאבד ספרה, או מספרים ובוליאנים שנפגשים על אותו נתיב, משאירים שם כל ערך כטקסט. כל שם של תכונה על נתיב נקבע בפני עצמו. נתיב שנשאר טקסט אף שחלק מערכיו היו מומרים מדווח, עם שם הנתיב, ועבור תכונה הנתיב מסתיים בתכונה, כמו ב־‎/catalog/book/@id.

המתג «המר מספרים ובוליאנים» דלוק כשהדף נפתח, כמו המתג המקביל בדף ה־CSV, וכיבוי שלו כותב כל ערך כטקסט. הערך של הצהרת מרחב שמות לעולם אינו נקרא כמספר, בשום מצב של המתג, כי התקן Namespaces in XML מגדיר את הערך הזה כשם של מרחב שמות, שהוא טקסט.

אלמנטים ריקים, וה־null שמסמך אומר בעצמו

• אלמנט ריק מקבל את הסוג שנקבע לנתיב שלו. בנתיב של טקסט הוא המחרוזת הריקה. בנתיב של מספרים או בוליאנים הוא null, והדף אומר זאת, כי לבדו האלמנט היה טקסט ריק.
• ריק פירושו שאין בו דבר בכלל: <zip> </zip> מחזיק רווח, ורווח הוא טקסט.
• נתיב שכל האלמנטים עליו ריקים הוא טקסט, ולכן כל אחד מהם הוא המחרוזת הריקה. שום דבר שם אינו נקרא כמספר, ו־null היה מידע שהמסמך מעולם לא נתן.
• בנתיב שנכתב כאובייקטים, גם אלמנט ריק נושא ‎#text, ריק או null לפי אותו כלל, בכל מקום שבו אלמנט אחר על הנתיב מחזיק טקסט: לצד <price currency="USD">5</price>, אלמנט ‎<price/>‎ הופך ל־‎{"‎#text": null}. היכן שאף אלמנט על הנתיב אינו מחזיק טקסט, כמו אלמנטים של תמונה שנושאים רק תכונת src, אף אחד מהם אינו נושא ‎#text.

מסמך יכול גם לומר null בעצמו. אלמנט שמסומן ב־xsi:nil="true"‎, כשהקידומת הזאת קשורה למרחב השמות XML Schema instance, הוא null בכל נתיב, בלי קשר למצב של «המר מספרים ובוליאנים». הסימון הוא הדרך של המסמך לומר null ולא נתונים, ולכן לא התכונה, ולא הצהרת מרחב שמות שאינה קושרת שום דבר אחר, מופיעות ב־JSON. כל קידומת שקשורה למרחב השמות הזה עובדת, ו־i:nil="1"‎ אומר את אותו הדבר; xsi:nil="false"‎ הוא נתון רגיל, ואלמנט שמסומן nil ועדיין מחזיק תוכן נשאר כפי שהוא, כי קריאה שלו כ־null הייתה משמיטה את התוכן הזה בלי מילה.

מה שאין לו מקום ב־JSON, מדווח במקום ללכת לאיבוד

לחלק ממה שמסמך XML מחזיק אין מקום ב־JSON. מה שנושא משמעות מדווח מתחת לפלט במקום להיעלם בשקט:

• הסדר של תוכן מעורב. ב־<p>Hello <b>world</b>, again</p> הטקסט נאסף תחת ‎#text כ־"Hello , again" והאלמנט b תחת "b": כל תו וכל אלמנט שורדים, אבל לא הסדר שבו עמדו. אלמנטים בנים שמתחלפים בין שמות מאבדים את הסדר שלהם באותו אופן. זה מדווח פעם אחת לנתיב של האלמנט שהתוכן שייך לו, ורק היכן שהסדר באמת אבד, ולכן <p><b>Note:</b> the rest</p> אינו מעלה דבר, כי סדר המפתחות שלו שומר עליו.
• הערות והוראות עיבוד. הן מושמטות, עם הודעה אחת לכל סוג שאומרת כמה היו והיכן עומדת הראשונה.
• ה־DOCTYPE. גם הוא מושמט, וההודעה עליו אומרת שה־DTD לא הוחל: ערך ברירת מחדל שה־DTD מצהיר עליו עבור תכונה חסר ב־JSON, כי הכלי הזה אינו קורא את ה־DTD.
• הצהרת ה־XML בראש המסמך. היא מושמטת בלי הודעה, כי היא מתארת איך הטקסט מקודד ולא מהם הנתונים.

JSON בחזרה ל־XML: ה־XML הקרוב ביותר, וכל שכתוב מדווח

החליפו כיוון ואותם כללים רצים בכיוון ההפוך: מפתח @ הופך לתכונה, ‎#text הופך לטקסט של האלמנט שלו, מערך הופך לאלמנט אחד לכל איבר, וכל מפתח אחר הופך לאלמנט בן, כשהאלמנטים הבנים באים לפי הסדר שבו המפתחות שלהם עומדים. null נכתב כאלמנט ריק שמסומן ב־xsi:nil="true"‎, כשמרחב השמות XML Schema instance מוצהר פעם אחת על אלמנט השורש, ורק כשנכתב null, כך שהמרה חזרה נותנת שוב null ולא מחרוזת ריקה. מלבד JSON שאינו תקין, או שמקונן עמוק מדי להמרה, שום דבר אינו נדחה. היכן שב־JSON שלכם יש מבנה ש־XML אינו יכול לשאת כפי שהוא, נכתב ה־XML התקין מבנית הקרוב ביותר והשכתוב מדווח מתחת לפלט, ב־JSONPath שאפשר להדביק בבודק ה־JSONPath שבאתר הזה:

• כל דבר שאינו אלמנט שורש יחיד, בין אם כמה מפתחות בראש המסמך, אף לא אחד, מערך בראש המסמך או ערך בודד, נכתב בתוך <root>.
• מפתח שאינו שם XML נכתב בשם הקרוב ביותר שאף מפתח אחר לצדו אינו נכתב בו: first name כ־first_name, ו־1st כ־‎_1st.
• איבר של מערך שאף מפתח אינו נותן לו שם, בין שהוא עומד בתוך מערך אחר ובין שבראש המסמך, נכתב כאלמנט <item>.
• מפתח @ או ‎#text שמחזיק אובייקט או מערך נכתב כאלמנט בן, כי לא תכונה ולא טקסט יכולים להחזיק כזה.
• מפתח @ שמחזיק null מושמט, וכך גם ‎#text שמחזיק null לצד אלמנטים בנים, כי XML אומר null רק על אלמנט שלם.
• תו ש־XML 1.0 אינו יכול להכיל כלל, אפילו לא כהפניה, מוחלף, והדף אומר היכן.

הברחה היא חלק מכתיבת XML תקין מבנית, ולא אפשרות. תו ‎<‎ ותו & מוברחים תמיד. בערך של תכונה מוברחת גם מרכאה כפולה, כי הערך עצמו כתוב בין שתיים כאלה; טאב, מעבר שורה או החזרת גררה נכתבים שם כהפניית תו, כי אחרת קורא היה הופך אותם לרווח. בטקסט, החזרת גררה נכתבת כהפניה, כי אחרת קורא היה הופך אותה למעבר שורה, ו־‎]]>‎ לעולם אינו נכתב כפי שהוא. זה מה שמאפשר לערך להיקרא בחזרה כערך שכתבתם.

מה ההמרה חזרה נותנת, נאמר לפני שממירים

יש XML שהוא תקין מבנית ובכל זאת נקרא בחזרה כמשהו אחר מה־JSON שממנו נכתב, ולכן הדף קורא את ה־XML שהוא כתב זה עתה, לפי אותם כללים שהכיוון השני משתמש בהם, ואומר היכן התשובה שונה. מערך של איבר אחד נקרא בחזרה כאיבר היחיד שלו, אלא אם אותם אלמנטים חוזרים תחת אב אחד במקום אחר במסמך. מערך ריק אינו כותב אף אלמנט, ו־‎#text ריק אינו כותב טקסט, ולכן כל אחד מהם נעלם בקריאה חזרה. אובייקט שאינו מחזיק דבר שנכתב כתכונה או כאלמנט בן נקרא בחזרה כערך פשוט, והיכן שאותם אלמנטים במקום אחר גורמים למסמך לקבוע מערך או אובייקט שלא היו ב־JSON שלכם, גם זה נאמר. כל אחד מאלה נכתב כפי שהוא ב־JSON שלכם, ומדווח.

הכפתור «השתמש כקלט» מעביר את הפלט לתיבת הקלט ומחליף את הכיוון, כך שמה שחוזר, ומה שמדווח עליו, נמצא במרחק לחיצה אחת. היכן שלא דווח דבר, מה שחוזר הוא ה־JSON שלכם, מלבד מה ש־XML אינו שומר. טקסט XML אינו מתעד אם ערך היה מספר, בוליאני או מחרוזת: כשהמתג «המר מספרים ובוליאנים» דלוק, מחרוזת שכתובה בדיוק כמו מספר עשויה לחזור כמספר הזה, וכשהוא כבוי כל ערך חוזר כטקסט. ותכונה, או ‎#text ריק או null, עשויים לחזור במקום אחר בין המפתחות שלצדם, כי XML אינו שומר את המיקום הזה.

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

כשה־XML או ה־JSON אינם נקראים

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

מתחת למשפט שנותן מיקום, הדף מציג את השורה שלכם עצמכם כשהתו הבעייתי מסומן, וזה חשוב במיוחד ב־XML או ב־JSON דחוסים, שבהם המסמך כולו הוא שורה אחת. שורה ארוכה מקוצרת לקטע שסביב הסימון, עם שלוש נקודות היכן שנחתכה. תו בעייתי שאינו מצייר דבר, כמו סוף הטקסט, טאב או סימן סדר בתים, מסומן על תו חלופי גלוי. העמודה נספרת כפי ש־JavaScript סופרת מחרוזת, ביחידות קוד של UTF-16, ולכן אמוג'י או אידאוגרמה נדירה לפני הסימון מזיזים אותה בשתיים ולא באחת.

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