ما هو JSON؟

صياغة JSON: أنواع القيم الست

مستند JSON هو قيمة واحدة. تكون هذه القيمة عادةً كائناً أو مصفوفة، لكن المعيار (RFC 8259) يسمح بأي من الأنواع الست في المستوى الأعلى.

• الكائن (Object) — مجموعة غير مرتبة من أزواج مفتاح/قيمة داخل أقواس معقوفة: {"id": 7, "name": "ليلى"}. يجب أن تكون المفاتيح نصوصاً بين علامتي اقتباس مزدوجتين.
• المصفوفة (Array) — قائمة مرتبة من القيم داخل أقواس مربعة: ["admin", "editor"].
• النص (String) — نص بين علامتي اقتباس مزدوجتين، مع شرطة مائلة عكسية لتهريب علامات الاقتباس والشرطات وأحرف التحكم: "السطر الأول\nالسطر الثاني".
• الرقم (Number) — عدد صحيح أو عشري مع أسّ اختياري: 42 و-3.5 و1.2e10. لا أصفار بادئة، ولا أرقام سداسية عشرية، ولا NaN أو Infinity.
• القيمة المنطقية (Boolean) — القيمتان true وfalse (بأحرف صغيرة).
• null — القيمة الحرفية null وتعني «لا قيمة».

{
  "user": { "id": 7, "name": "Layla", "active": true },
  "roles": ["admin", "editor"],
  "lastLogin": null,
  "balance": 1250.75
}

القواعد التي تسبب معظم أخطاء JSON

يبدو JSON شبيهاً بـ JavaScript لكنه أكثر صرامة بكثير. تنشأ كل أخطاء «Unexpected token» و«Unexpected end of JSON input» تقريباً من إحدى هذه القواعد.

• المفاتيح والنصوص تستخدم علامات الاقتباس المزدوجة فقط. علامات الاقتباس المفردة '...' غير صالحة.
• لا فواصل زائدة في النهاية: [1, 2, 3,] و{"a": 1,} خطأ.
• لا تعليقات. لا يُسمح بـ // ولا /* */ في أي مكان من المستند.
• يجب اقتباس المفاتيح: {name: "Layla"} هي JavaScript وليست JSON.
• لا يمكن أن تبدأ الأرقام بأصفار (007) أو تنتهي بنقطة عشرية (5.).
• يجب أن يحتوي المستند على قيمة عليا واحدة بالضبط — كائنان متجاوران ليسا JSON صالحاً (هذا ما يُسمى JSON Lines).
• الترميز هو UTF-8. علامة ترتيب البايتات (BOM) في بداية الملف تعطّل كثيراً من المحلّلات.

جرّبها: مدقّق JSON

كيفية تنسيق JSON (Pretty Print)

ترسل واجهات API عادةً JSON مصغّراً — بحذف كل المسافات وفواصل الأسطر — لأنه أصغر حجماً. التنسيق يعيد المسافات البادئة لتظهر البنية بوضوح. الصق النص في أداة تنسيق، واختر مسافتين أو أربع مسافات أو علامة جدولة، وانسخ النتيجة؛ والأداة الجيدة تبلّغ أيضاً عن رقم السطر والعمود الدقيق لأي خطأ في الصياغة، ويمكنها ترتيب مفاتيح الكائنات حتى تسهل مقارنة مستندين.

في الكود، تؤدي JSON.stringify(value, null, 2) في JavaScript وjson.dumps(value, indent=2) في Python وjq . file.json في سطر الأوامر المهمة نفسها.

جرّبها: منسّق JSON جرّبها: مصغّر JSON

كيفية التحقق من صحة JSON

للتحقق مستويان. التحقق من الصياغة يتأكد من أن النص JSON سليم البنية — كل قوس مغلق وكل قاعدة أعلاه محترمة. أما التحقق من المخطط (Schema) فيذهب أبعد ويفحص البنية مقابل JSON Schema: أي المفاتيح مطلوبة، وما نوع كل قيمة، والنطاقات والأنماط المسموحة.

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

جرّبها: مدقّق JSON جرّبها: مدقّق JSON Schema جرّبها: مولّد JSON Schema

JSON مقابل XML مقابل YAML

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

أما YAML فهو مجموعة شاملة لـ JSON صُممت ليكتبها البشر — ملفات الإعداد، وخطوط CI، وملفات Kubernetes. يسمح بالتعليقات ويحذف معظم علامات الترقيم، لكن حساسيته للمسافات تجعله خياراً سيئاً للتبادل بين الآلات. القاعدة العملية: JSON لواجهات API والتخزين، وYAML للإعدادات، وXML عندما يفرضه النظام.

جرّبها: محوّل JSON إلى YAML جرّبها: محوّل JSON إلى XML جرّبها: محوّل XML إلى JSON جرّبها: منسّق YAML جرّبها: منسّق XML جرّبها: مدقّق XML

تحويل JSON إلى CSV وSQL وصيغ أخرى

تتحول مصفوفات JSON المسطّحة من الكائنات إلى CSV بسهولة: يصبح كل كائن صفاً وكل مفتاح عموداً. أما الكائنات المتداخلة فتحتاج إلى تسطيح أولاً (يصبح user.address.city عموداً باسم user.address.city). وتنطبق البنية نفسها على جمل SQL INSERT، وهي أسرع طريقة لتحميل بيانات API في قاعدة بيانات للتحليل.

جرّبها: محوّل JSON إلى CSV جرّبها: محوّل CSV إلى JSON جرّبها: محوّل JSON إلى SQL جرّبها: تسطيح / إلغاء تسطيح JSON

التعامل مع مستندات JSON الكبيرة

عارض الشجرة هو الطريقة العملية لقراءة مستند بآلاف الأسطر: اطوِ ما لا تحتاجه، ووسّع فرعاً واحداً في كل مرة، وانسخ مسار JSONPath لأي قيمة. ولإيجاد قيم محددة أو استخراجها برمجياً، تحدد تعابير JSONPath مثل $.users[?(@.active)].email العقد التي تريدها بالضبط.

جرّبها: عارض شجرة JSON جرّبها: مختبِر JSON Path جرّبها: مقارنة JSON

الأسئلة الشائعة