محوّل 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، لذا يزيحه رمز تعبيري أو حرف صيني نادر قبل العلامة بمقدار اثنين لا واحد.

ويُرفض كذلك المستند المتداخل أعمق مما يسمح به الموقع، في أي من الاتجاهين، وتذكر جملته الحد.