أساسيات JSON: الصيغة، والأخطاء الشائعة، ومتى تستخدمه بدل CSV

إذا تعاملت مع واجهة برمجة تطبيقات، أو ملف إعدادات، أو تصدير بيانات من منصة إلكترونية، فقد رأيت JSON. صيغة بسيطة يقرأها الإنسان والآلة، لكنها لا تتسامح مع الأخطاء: المحلل (Parser) يرفض الملف كاملًا عند أول خطأ. هذا الدليل يشرح القواعد كلها تقريبًا، ثم أشهر الأخطاء، ثم المقارنة مع CSV.

البنية الأساسية

JSON يتكون من نوعين من الحاويات:

• الكائن (Object): أزواج "مفتاح": قيمة بين قوسين معقوفين { }.
• المصفوفة (Array): قائمة قيم مرتبة بين قوسين مربعين [ ].

{
  "name": "متجر الرياض",
  "city": "الرياض",
  "vatNumber": "300000000000003",
  "active": true,
  "rating": 4.7,
  "branches": ["العليا", "النخيل"],
  "owner": {
    "name": "سارة",
    "phone": null
  }
}

أنواع القيم (ستة فقط)

لا يوجد في JSON: تاريخ، دالة، undefined، تعليقات. التواريخ تُكتب نصًا عادةً بصيغة ISO 8601 مثل "2026-10-08T14:00:00Z" أو كرقم (Unix timestamp). التفاصيل في دليل Unix timestamp.

القواعد الصارمة

1. المفاتيح بين علامات اقتباس مزدوجة دائمًا: "name" لا name ولا 'name'.
2. النصوص بين علامات اقتباس مزدوجة: "نص" لا 'نص'.
3. فاصلة بين العناصر، ولا فاصلة بعد آخر عنصر.
4. الهروب (Escape) داخل النصوص: \" لعلامة الاقتباس، \\ للشرطة المائلة العكسية، \n لسطر جديد، \t للمسافة الجدولية.
5. الترميز UTF-8 هو المعيار.

أشهر الأخطاء وإصلاحها

1. الفاصلة الزائدة (Trailing comma)

{ "a": 1, "b": 2, }

خطأ. احذف الفاصلة الأخيرة: { "a": 1, "b": 2 }. JavaScript الحديث يقبلها في الكود، لكن JSON لا يقبلها.

2. علامات الاقتباس المفردة

{ 'city': 'Cairo' }

خطأ. الصحيح: { "city": "Cairo" }.

3. مفتاح بلا علامات اقتباس

{ city: "Dubai" }

صالح في JavaScript، خطأ في JSON.

4. علامات الاقتباس “الذكية”

النسخ من Word أو بعض تطبيقات المراسلة يحوّل " إلى “ ”. المحلل لا يتعرف عليها. استبدلها بعلامات عادية.

5. التعليقات

{
  // سعر المنتج
  "price": 100
}

JSON القياسي لا يقبل التعليقات. بعض الأدوات تقبل صيغة JSONC (مثل إعدادات VS Code)، لكن لا تعتمد على ذلك في تبادل البيانات.

6. أرقام وقيم خاصة

NaN وInfinity وundefined غير صالحة. الأرقام الكبيرة جدًا (مثل معرفات 19 خانة) قد تفقد دقتها في JavaScript لأنها تتجاوز 2^53؛ أرسلها نصًا.

7. أكثر من جذر

الملف يجب أن يحتوي قيمة جذرية واحدة. كائنان متتاليان دون مصفوفة خطأ، إلا في صيغة JSON Lines (كائن في كل سطر) المستخدمة في السجلات.

التنسيق والتحقق

• التنسيق (Pretty print): إضافة مسافات بادئة وأسطر لتسهيل القراءة.
• التصغير (Minify): إزالة المسافات لتقليل الحجم في النقل.
• التحقق (Validate): التأكد من أن النص JSON صالح، مع تحديد موضع الخطأ.

منسّق JSON يفعل الثلاثة ويشير إلى السطر والعمود عند الخطأ.

من سطر الأوامر

# تنسيق ملف والتحقق منه
python3 -m json.tool data.json

# باستخدام jq: تنسيق واستخراج حقل
jq '.owner.name' data.json

في JavaScript

const obj = JSON.parse(text);              // نص ← كائن (يرمي خطأ إن كان غير صالح)
const out = JSON.stringify(obj, null, 2);  // كائن ← نص منسق بمسافتين

لاحظ أن JSON.stringify يحذف الخصائص التي قيمتها undefined أو دالة بصمت.

JSON مقابل CSV

مشكلات CSV مع العربية

• Excel قد يعرض العربية رموزًا غريبة إن لم يكن الملف UTF-8 مع BOM.
• الفاصل قد يكون فاصلة , أو فاصلة منقوطة ; حسب إعدادات المنطقة.
• الفاصلة العربية ، ليست فاصلًا في CSV.

التحويل بينهما

[
  { "city": "الرياض", "sales": 1200 },
  { "city": "دبي", "sales": 950 }
]

يصبح في CSV:

city,sales
الرياض,1200
دبي,950

البيانات المتداخلة (مثل owner.name) تُسطَّح عند التحويل إلى أعمدة مثل owner.name. محول CSV إلى JSON يحول في الاتجاهين.

JSON Schema: التحقق من البنية لا الصيغة فقط

ملف JSON قد يكون صالح الصيغة لكنه ناقص أو خاطئ في المحتوى: حقل مفقود، أو رقم مكتوب نصًا. JSON Schema معيار لوصف البنية المتوقعة:

{
  "type": "object",
  "required": ["name", "price"],
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "price": { "type": "number", "minimum": 0 },
    "currency": { "enum": ["SAR", "AED", "EGP", "MAD"] }
  }
}

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

أين تقابل JSON؟

• واجهات البرمجة REST: معظمها يرسل ويستقبل JSON.
• البيانات المنظمة للمواقع (JSON-LD): لمساعدة محركات البحث على فهم الصفحة؛ راجع دليل البيانات المنظمة.
• ملفات الإعدادات: package.json، tsconfig.json، manifest.json.
• قواعد البيانات: MongoDB وحقول JSON في PostgreSQL وMySQL.

JSON والأمان

• لا تستخدم eval() لتحليل JSON في JavaScript؛ استخدم JSON.parse دائمًا.
• لا تضع أسرارًا (مفاتيح API، كلمات مرور) في ملفات JSON داخل مستودعات عامة أو في كود الواجهة الأمامية.
• تحقق من حجم المدخلات في الخادم قبل تحليلها، فملف ضخم قد يستهلك الذاكرة.

قائمة تحقق قبل إرسال JSON

• مرّره على منسّق للتحقق.
• لا فواصل زائدة، ولا علامات اقتباس مفردة أو ذكية.
• التواريخ بصيغة ISO 8601 نصًا.
• المعرفات الطويلة نصًا.
• الترميز UTF-8.