شرح JSON: لماذا أصبح شائعاً إلى هذا الحد

تاريخ قصير

بدأ JSON كتنسيق تبادل عملي، لا كمشروع معايير أكاديمي. وثّق دوغلاس كروكفورد التنسيق على json.org وجادل بأن قواعد نحوية صغيرة ومتوقعة تتفوق على أكوام XML الأثقل لكثير من حالات الويب. لاحقاً رسّمت ECMA-404 وIETF RFC 8259 القواعد نفسها: نص UTF-8، كائنات ومصفوفات، ومجموعة ثابتة من أنواع القيم. كان ذلك التوحيد مهماً لأن الواجهات عقود — يجب على كل عميل تحليل البايتات نفسها بنفس الطريقة.

JSON is a light-weight, text-based, language-independent data interchange format.

— RFC 8259

ما تسمح به صياغة JSON فعلياً

في المستوى الأعلى، JSON إما كائن أو مصفوفة. الكائنات خرائط غير مرتبة من سلاسل إلى قيم؛ المصفوفات قوائم مرتبة. يجب أن تكون المفاتيح سلاسل بين علامتي اقتباس مزدوجتين. السلاسل تستخدم الاقتباس المزدوج وتسلسلات الهروب القياسية (\", \\, \b, \f, \n, \r, \t, \uXXXX). الأعداد تُكتب بالنظام العشري؛ المنطقيان true وfalse؛ null قيمة أولى. هذا هو نظام الأنواع كله — لا تواريخ، لا تعليقات، لا undefined، لا فواصل زائدة في JSON الصارم.

{
  "title": "JSON Explained",
  "published": "2026-10-04",
  "featured": true,
  "tags": ["api", "data"],
  "metrics": { "views": 1204, "rating": 4.8 },
  "notes": null
}

التاريخ والمقاييس المتداخلة اتفاقيات توثّقها واجهتك — وليست أنواع JSON مدمجة. JSON يعرف فقط string وnumber وboolean وnull وobject وarray.

الكائنات والمصفوفات والأنواع البدائية عملياً

• تجمّع الكائنات حقولاً مسماة — نموذجية للسجلات والإعدادات أو موارد الواجهة.
• تحفظ المصفوفات الترتيب — قوائم عناصر أو أسطر سجل أو إحداثيات.
• تحمل السلاسل النص؛ الأعداد IEEE 754 binary64 في معظم المحلّلات (انتبه للأعداد الصحيحة فوق 2^53 في JavaScript).
• المنطقي وnull صريحان حتى لا يخمّن المحلّل.

التداخل وشكل الحمولة

تُدخل الواجهات الحقيقية كائنات داخل مصفوفات ومصفوفات داخل كائنات: قد تكون نتيجة بحث { "items": [ { "id": 1, "name": "…" } ], "total": 42 }. التداخل العميق مقروء بجرعات صغيرة؛ الهياكل المسطحة مع معرّفات غالباً تتوسع أفضل للعملاء الذين يعدّلون حقولاً منفردة. JSON لا يبالي بأي أسلوب تختاره — العقد هو ما يعد به OpenAPI أو README.

JSON ليس JavaScript

تسمح كائنات JavaScript بمفاتيح بين علامات مفردة، ومفاتيح غير مقتبسة عندما تكون معرّفات صالحة، وفواصل زائدة، وundefined، ودوال، وكائنات Date. JSON لا يسمح بأي من ذلك. عرضت المتصفحات تاريخياً JSON.parse وJSON.stringify حتى تتجاوز التطبيقات الحد بأمان. معاملة استجابات الواجهة بـ eval() كان النمط المضاد الذي أُريد JSON لاستبداله.

لماذا أزاح JSON الـ XML من كثير من الواجهات

يتفوق XML حين تحتاج محتوى مختلطاً، أو مساحات أسماء، أو مخططات مدمجة في سير عمل المؤسسات، أو ترميز مستندات. يتفوق JSON حين تحتاج تنسيقاً رفيعاً للسجلات المنظمة عبر HTTP. حمولات JSON عادة أصغر، والمحلّلات أبسط، وكل لغة رئيسية تشحن مكتبة JSON. جدال XML بين السمات والعناصر يصبح غير ذي صلة حين يصبح كل شيء كائنات متداخلة.

JSON5 وJSONC وضريبة الصرامة

يريد البشر تعليقات وفواصل زائدة في الإعداد المحرّر يدوياً. JSON5 وJSONC (JSON مع تعليقات) يضيفان هذه التسهيلات لملفات المصدر. واجهات الإنتاج، مع ذلك، تلتزم بغالبية ساحقة بـ JSON الصارم RFC 8259 حتى يتفق كل مستهلك على أوضاع الفشل. فاصلة زائدة يتسامح معها محرّرك ستكسر محلّل فريق آخر الصارم — لذلك ما زالت عمليات اللصق في المدقّقات تفشل في 2026.

التسلسل والتحليل

خيارات التسلسل مهمة: stringify الافتراضي قد يحذف خصائص undefined في JavaScript، أو يعيد ترتيب مفاتيح الكائن بلا توقع، أو يسلسل التواريخ كسلاسل ISO فقط إن أضفت replacer. مصممو الواجهات يوثّقون هذه القواعد حتى لا يعتمد العملاء على ترتيب المفاتيح أو إجبار الأنواع ضمنياً.

التحقق والأخطاء الشائعة

• فواصل زائدة بعد آخر عنصر في المصفوفة أو آخر خاصية في الكائن
• سلاسل بين علامات مفردة بدلاً من مزدوجة
• مفاتيح غير مقتبسة (عادة JS تُلصق في JSON)
• حرفيات JavaScript: undefined وNaN وInfinity
• تعليقات منسوخة من قوالب إعداد
• أقواس غير متطابقة أو فواصل شاردة بين القيم
• هروب Unicode غير صالح (\u يجب أن تكون أربع خانات hex)

حين يفشل التكامل، مرّر الحمولة عبر منسّق ومدقّق قبل إلقاء اللوم على الخادم. نصف بلاغات «الواجهة تُرجع JSON سيئاً» هي ضرر لصق أو ترميز مزدوج عبر middleware لسلسلة كانت JSON أصلاً.

JSON في الواجهات والتبادل

ترسل واجهات HTTP JSON غالباً مع Content-Type: application/json. يرسل العملاء Accept: application/json لتفضيل استجابات JSON. GraphQL وأنماط أخرى ما زالت تسلسل النتائج كـ JSON عبر HTTP. يبقى CSV شائعاً للجداول؛ أدوات json-to-csv وcsv-to-json في SmartKitio موجودة للتسليم بين الجداول المسطحة وأشكال الواجهة المتداخلة — لا لأن تنسيقاً واحداً أفضل مطلقاً، بل لأن الفرق تعيش في العالمين.

قيود حقيقية (لا أساطير)

• لا نوع تاريخ قياسي — استخدم سلاسل ISO 8601 ووثّق المناطق الزمنية.
• لا نوع ثنائي — استخدم Base64 في سلسلة (بتكلفة حجم) أو نقاط نهاية ثنائية منفصلة.
• لا مخطط يفرضه التنسيق ذاته — استخدم JSON Schema أو OpenAPI أو مدقّقات مخصصة.
• لا تعليقات أو بيانات وصفية في JSON الصارم — استخدم حقولاً مجاورة مثل "_comment" إن اضطررت (ووثّق ذلك الاتفاق).
• مفاتيح مكررة في الكائنات: RFC 8259 يقول إن الأسماء يجب أن تكون فريدة؛ قد تختلف المحلّلات في أي قيمة تفوز — لا تعتمد على التكرار.

JSON مُعلَّق: شكل صالح مقابل أخطاء لصق شائعة

الكتلة أدناه JSON صارم صالح — لاحظ مفاتيح بين علامات مزدوجة، بلا تعليقات، بلا فاصلة زائدة بعد آخر خاصية. كثير من ملفات «JSON» في المستودعات هي JSON5 أو حرفيات JavaScript؛ لصقها في مدقّق صارم يفشل لأسباب متوقعة تُذكر بعد ذلك.

{
  "data": {
    "id": "usr_8f2a",
    "email": "dev@example.com",
    "roles": ["reader", "editor"]
  },
  "meta": {
    "requestId": "req_91bc",
    "cached": false
  }
}

تغليف الموارد في data مع meta نمط متكرر: data تحمل المورد، وmeta تحمل التصفح أو معرّفات التتبع أو تلميحات حد المعدّل دون تلويث كائن المجال.

{
  // TODO: remove before prod
  "data": {
    "id": "usr_8f2a",
    "email": "dev@example.com",
    "roles": ["reader", "editor",],
  },
  "meta": { "requestId": "req_91bc", "cached": false }
}

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