متوفر أيضًا بلغات أخرى: English · Español · Português · Français
مؤشّر JSON: أداة تقييم مؤشّرات RFC 6901
أشِر إلى قيمة واحدة بعينها داخل مستند JSON، وانظر كيف انحلّ كل رمز، أو لماذا لم ينحلّ بالضبط.
ما مؤشّر JSON؟
مؤشّر JSON سلسلة قصيرة تسمّي موضعًا واحدًا بعينه داخل مستند JSON. وهو تتابع رموز يستهلّ كلٌّ منها بشرطة مائلة، فـ /paths/~1users/get ينزل من الجذر إلى العضو المسمّى paths، ثم إلى المسمّى /users، ثم إلى get. يعرّفه RFC 6901 في ثماني صفحات، وهو ما يستعمله JSON Patch وإحالات JSON Schema وOpenAPI جميعًا للدلالة على مقصودها.
والكلمة الفاصلة هي «واحدًا بعينه». فالمؤشّر يسمّي موضعًا واحدًا، إمّا أن يكون فيه شيء وإمّا ألّا يكون، وهذا ما يفصله عن JSONPath، حيث قد يعيد استعلام واحد مئة عقدة أو لا يعيد شيئًا، وحيث تعيد التطبيقات المختلفة مجموعات مختلفة. وليس في المؤشّر ما يُختلف عليه، ولذلك بعينه اختارته الصيغ التي لا تحتمل اللبس.
ولهذه القواعد الصغيرة حوافّ أكثر ممّا يُظنّ، وهذه الأداة تعرضها كلها. الصق مستندًا، واكتب مؤشّرًا، فتقيّمه رمزًا رمزًا: أين بُحث عن كل رمز، وماذا وجد، وإن لم يجد شيئًا فأيّ قاعدة أوقفته.
طريقة الاستعمال
- الصق مستندًا. تبدأ الأداة بالمستند الذي يضربه المعيار مثالًا، فكل جواب هنا يمكن مقابلته بـ RFC 6901 نفسه. وما ليس JSON صحيحًا يُخبَر به بدل أن يُخمَّن.
- اكتب مؤشّرًا. السلسلة الفارغة تسمّي المستند كله، وما عداها يبدأ بشرطة مائلة. وداخل الرمز تُكتب التلدة ~0 والشرطة ~1. أو اختر واحدًا من قائمة كل مؤشّرات مستندك في الأسفل.
- اقرأ الأثر. يعرض كل صف رمزًا، وهل بُحث عنه في كائن أم في مصفوفة، وماذا عاد. والإخفاق يسمّي القاعدة بعينها بدل أن يكتفي بألّا يعيد شيئًا.
قاعدة التهريب، والترتيب الذي يجب أن تجري به
حرفان لا يجوز ظهورهما كما هما داخل الرمز. فالشرطة المائلة تفتح رمزًا جديدًا، وعلامة التلدة هي حرف التهريب، فيُكتبان ~1 و~0. وهذا كل نظام التهريب، وهو أصغر ممّا يتوقّعه أكثر الناس: لا شرطة عكسية، ولا ترميز بالنسبة المئوية، ولا أي تهريب آخر. وتلدة يتبعها غير 0 أو 1 ليست مؤشّرًا صحيحًا.
والمثير هو الترتيب. فعلى فكّ الترميز أن يحوّل ~1 إلى شرطة مائلة أولًا، و~0 إلى تلدة ثانيًا. وبالعكس تصير ~01 هي ~1 ثم شرطة مائلة، والجواب الصحيح هو الحرفان ~1. ويخصّص المعيار لذلك فقرة كاملة يسمّي فيها النتيجة الخاطئة صراحةً، وذلك في العادة دليل على أن تطبيقات حقيقية تخطئ فيها. وهذه الأداة تفكّ الترميز في مرور واحد، فالخطر لا يُتَّقى بتذكّر ترتيب، بل لا سبيل إلى وقوعه أصلًا.
والترميز يجري في الاتجاه المعاكس وفيه الفخّ نفسه مقلوبًا: تُهرَّب التلدة أولًا ثم الشرطة المائلة، وإلا أعطى اسمٌ فيه شرطة مائلة رمزًا يُفكّ إلى شيء آخر. والأداة تهرّب أثناء مرورها للسبب نفسه.
أربع قواعد تفاجئ الناس
لا يجوز أن يحمل فهرس المصفوفة صفرًا في مقدّمته. فالقاعدة تجيز صفرًا مفردًا، أو رقمًا من واحد إلى تسعة يتبعه ما شاء من الأرقام، ولا شيء غير ذلك، فـ /foo/01 خطأ في التركيب لا الفهرس واحد. وهنا بالضبط يزلّ التطبيق المكتوب بجافاسكربت، لأن الطريقتين البديهيتين لقراءة عدد تقبلانه: إحداهما تحوّل النص 01 إلى العدد واحد، والأخرى تنتزع عددًا من أول 1abc وتطرح الباقي. وليست أيّ منهما ما تقوله القاعدة.
والشرطة المائلة وحدها ليست مؤشّرًا فارغًا، بل هي رمز اسمه السلسلة الفارغة، فتشير إلى العضو المسمّى «لا شيء البتّة» — وهو اسم عضو مشروع تمامًا في JSON، وقد ضمّه مستند المعيار المثال لهذا السبب عينه. أما المؤشّر الفارغ الخالي من أي حرف فهو الذي يسمّي المستند كله.
والحرف - وحده يسمّي الموضع التالي لآخر عنصر في المصفوفة. وليس فهرسًا، ولا قيمة هناك أبدًا؛ إنما وُجد ليقول JSON Patch «أضِف هنا». والإبلاغ عنه خطأً غلط، وإعادة قيمة كذب، فأفردت له الأداة جوابًا خاصًّا.
وتُقارَن أسماء الأعضاء بنقاط الترميز، وينصّ المعيار صراحةً على ألّا تُجرى أي تسوية يونيكودية. فصورتان لحرف مشكول واحد — إحداهما مركَّبة في حرف واحد والأخرى مكتوبة حرفًا تتبعه علامة ضامّة — تبدوان متطابقتين على الشاشة وهما عضوان مختلفان. فإن أبى مؤشّر يبدو صحيحًا أن ينحلّ، فهذا أول ما يُنظر فيه.
صورة الجزء، وما لا تعنيه
يمكن كتابة المؤشّر أيضًا داخل جزء من معرّف URI، ويعيد المعيار الأمثلة الاثني عشر نفسها في تلك الصورة: يُرمَّز المؤشّر بترميز UTF-8 ويُرمَّز بالنسبة المئوية كل ما لا يحمله الجزء، فتصير علامة النسبة %25 وتصير المسافة %20. وتعرض الأداة تلك الكتابة لما تكتبه وتتيح نسخها.
ثم تأتي الجملة التي لا يكاد أحد يتوقّعها، في القسم نفسه الذي يطبع تلك الأمثلة: صيغة معرّف الجزء لـ application/json ليست مؤشّر JSON. فعلى نوع الوسائط أن يعلن مؤشّر JSON صيغةً لجزئه إعلانًا صريحًا، وJSON المجرّد لم يفعل ذلك قطّ. فعنوان ينتهي بمؤشّر يعني شيئًا داخل JSON Schema أو إحالة OpenAPI حيث تنصّ الصيغة على ذلك، وهو زينة في ملف json. عادي حيث لا شيء يمنحه ذلك المعنى.
ويحسن كذلك بيان حدود الأداة. فهي تقيّم المؤشّرات ولا تطبّق الرقع؛ وRFC 6902 يبني على هذه القواعد ليضيف القيم ويحذفها وينقلها، وذاك عمل آخر. وهي تعمل على المستند الذي تلصقه، ولا تتبع إحالات إلى ملفات أخرى. وهي متشدّدة عن قصد: فحيث قد تقبل مكتبةٌ في صمت صفرًا في المقدمة أو تلدة شاردة، تخبرك هذه بالقاعدة التي انكسرت — لأن مؤشّرًا يعمل في تطبيق ويخفق في آخر هو بعينه المشكلة التي وُجد ليمنعها.
لماذا هي مجانية؟
المرور بمستند رمزًا رمزًا بضع مئات من أسطر معالجة النصوص، ويجريها متصفحك وأنت تكتب. ولا خادم يرى ملف JSON الخاص بك، فلا شيء يُحسب عليك ولا حساب تنشئه.
ولا يُرفع شيء. وما تلصقه يبقى في هذا التبويب.