رقعة JSON: تطبيق عمليات RFC 6902 خطوةً خطوة

ما رقعة JSON؟

رقعة JSON صيغة صغيرة لوصف التغييرات على مستند JSON بدل إرسال المستند كله. والرقعة مصفوفة عمليات، تقول كلٌّ منها ماذا يُفعل وأين: add وremove وreplace وmove وcopy وtest. يعرّف RFC 6902 هذه الستّ في نحو ثماني صفحات، ويُكتب كل موضع مؤشّرَ JSON، وهي الصيغة الشقيقة التي تسمّي موضعًا واحدًا بعينه داخل مستند.

ووُجدت لأن إرسال مستند كامل لتغيير حقل واحد إسراف وفيه لبس: عميلان يفعلان ذلك يمحو أحدهما عمل الآخر دون أن يشعرا. أما الرقعة فتقول ما الذي تغيّر، وهي أخفّ على الشبكة وأدقّ من أن تُقبل على مستند تبدّل من تحتك. ولهذا وُجدت العملية السادسة: فـ test لا تغيّر شيئًا بل تؤكّد، والرقعة التي تبدأ باختبار تغييرٌ يأبى أن يُطبَّق على المستند الخطأ.

تشغّل هذه الصفحة الرقعة على المستند وتعرض النتيجة بعد كل عملية، لا في الآخر فحسب. وهذا أهمّ ممّا يبدو، لسبب يشرحه القسم الذي يلي التالي.

طريقة الاستعمال

1. الصق المستند. لا يُعدَّل في مكانه أبدًا: كل عملية تشتغل على نسخة، فيبقى مستندك سليمًا مهما فعلت الرقعة.
2. الصق الرقعة. مصفوفة عمليات. وتحمّل أزرار الأمثلة خمس حالات: اختبار يخفق في المنتصف، وإدراج في مصفوفة، واختبار يُستعمل حارسًا، ونقل تحظره المواصفة، وفهرس بعد نهاية مصفوفة.
3. اقرأ الأثر. كل صف عملية، ولك أن تفتح أيًّا منها لترى المستند كله كما كان في تلك اللحظة. والإخفاق يسمّي القاعدة بعينها بدل أن يصمت.

رقعة JSON ليست ذرّية، والمواصفة لا تقول إنها كذلك

يعرف الجميع أن الرقعة إذا أخفقت تركت المستند كما كان. وهو أول ما يُقال لك عن هذه الصيغة، وليس هو ما يقوله RFC 6902.

يقول القسم الخامس إنه عند الإخفاق ينبغي أن يتوقّف التقييم وألّا يُعدّ تطبيق الرقعة كلها ناجحًا. اقرأها بتمعّن: هذا كلام على الحكم، على أتُحسب الرقعة مطبَّقة أم لا. ولا يقول شيئًا عن التراجع عن العمليات التي جرت بالفعل. أما الذرّية التي يستشهد بها الجميع فتأتي بعد جملة واحدة ومن موضع آخر: ملاحظةٌ بأن أسلوب HTTP PATCH ذرّي، وفق مستند آخر هو الذي يعرّف ذلك الأسلوب.

فالضمان إذن للناقل لا للصيغة. أرسل رقعةً عبر HTTP PATCH فيلزم الخادم أن يطبّقها كلها أو لا شيء منها. وسلّم الرقعة نفسها إلى مكتبة داخل عمليتك، فأن تجد بين يديك كائنًا معدَّلًا نصف تعديل شأن تلك المكتبة، لا أمرًا تحسمه المواصفة نيابةً عنك. والمثال الذي تضربه المواصفة نفسها رقعةٌ من عمليتين يخفق اختبارها الثاني، وتقول إن المستند ينتهي دون تغيير — لأنها تصف حالة HTTP.

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

ثلاث قواعد تفاجئ الناس

الإضافة إلى مصفوفة إدراجٌ لا استبدال. وجّه add إلى الفهرس واحد في مصفوفة من ثلاثة عناصر فتخرج بأربعة، وقد انزاح كل ما كان من الفهرس واحد فصاعدًا إلى اليمين. وإن كنت تريد الاستبدال فتلك replace. ويجوز أن يساوي الفهرس الطول فيُلحق في الآخر، أما ما بعد ذلك فخطأ لا كتابة متفرّقة — وفي صياغة المؤشّرات شرطة تعني «بعد آخر عنصر»، وهي أوضح في قول «ألحِق» من أي رقم.

وفي العملية نفسها فخّ آخر أهدأ. فإضافة مصفوفة بوصفها قيمةً تدرجها كلها عنصرًا واحدًا، فتصير قائمةٌ من عنصر مع مصفوفة من عنصرين قائمةً من عنصرين ثانيهما قائمة. وتفرد المواصفة لذلك مثالًا مستقلًّا، وهذه في العادة أمارة على أن الناس كانوا يتوقّعون غيره.

ولـ move قاعدة لا نظير لها بين بقية العمليات: لا يجوز أن يكون المصدر بادئةً حقيقية للوجهة، أو بعبارة المواصفة نفسها: لا يجوز نقل موضع إلى داخل أحد أبنائه. وهي بيّنة متى قيلت، ويسهل جدًّا كتابتها سهوًا حين تطول المسارات.

و test تقارن الأنواع كما تقارن القيم. فالعدد عشرة والنص عشرة مختلفان، والاختبار الذي يقابل أحدهما بالآخر يخفق. وهذا هو السلوك الذي تريده من شرط مسبق، لكنه يوقع من جاء من نموذج أو من سلسلة استعلام، حيث وصل كل شيء نصًّا.

حدود مُعلَنة

هذه الأداة تطبّق الرقع ولا تولّدها. فإنتاج أصغر رقعة بين مستندين مسألة أخرى لها أكثر من جواب وجيه، والمواصفة لا تعرّف واحدًا منها.

وثمّة مثال في المواصفة لا تستطيع هذه الأداة تشغيله، ويحسن معرفة السبب. إنه رقعة يحوي كائن عمليتها العضو نفسه مرتين — إذ تظهر op مرةً add ومرةً remove — وتلاحظ المواصفة أن JSON لا يقول إلا إن أسماء الأعضاء ينبغي أن تكون فريدة، دون معالجة قياسية للتكرار. وأي محلّل جافاسكربت يحسم ذلك في صمت مبقيًا على الأخير، فيُهدم العيب الذي وُجد المثال لوصفه قبل أن يرى محرّك الرقع المستند أصلًا. وهذه خاصّة المحلّل لا الصيغة، ولا يستطيع كشفها أي تطبيق يستقبل JSON محلَّلًا سلفًا.

وأخيرًا تطرح هذه الأداة النتيجة متى أخفقت أي عملية. وهذا مقصود وهو الافتراض الأسلم، لكنه قرار اتخذته هذه الصفحة لا شيء تفرضه الصيغة — ولهذا بالذات يُعرض المستند المنقوص إلى جواره بدل أن يُطرح في صمت.

لماذا هي مجانية؟

المرور بمستند وتطبيق حفنة عمليات عليه بضع مئات من أسطر معالجة النصوص والمصفوفات، ويجريها متصفحك وأنت تكتب. ولا خادم يرى ملف JSON الخاص بك، فلا شيء يُحسب عليك ولا حساب تنشئه.

ولا يُرفع شيء. وما تلصقه يبقى في هذا التبويب.