ما هو JSON؟ دليل بسيط مع أمثلة

JSON (JavaScript Object Notation) صيغة نصية بسيطة لكتابة البيانات المنظمة، مثل عميل أو طلب أو قائمة منتجات، على هيئة أسماء مقترنة بقيم. وهي سهلة القراءة للبشر، وسهلة الإنتاج والتحليل للبرامج. وحين تتبادل التطبيقات والخدمات البيانات عبر الويب، يكون JSON أكثر الصيغ شيوعًا بفارق كبير.

لماذا يهم JSON عند البناء بالذكاء الاصطناعي

ستصادف JSON باستمرار، حتى لو لم تكتب كودًا قط:

• واجهات البرمجة (APIs). حين تحمّل شاشات تطبيقك بياناتها من الخلفية، أو حين تستدعي خلفيتك خدمة دفع أو بريد أو ذكاء اصطناعي، تنتقل البيانات عادةً بصيغة JSON. انظر ما هي واجهة البرمجة.
• ملفات الإعداد. كثير من ملفات إعداد المشاريع هي JSON، مثل package.json الذي يسرد تبعيات مشروع JavaScript.
• قواعد البيانات. يستطيع Postgres تخزين JSON في عمود (نوع jsonb) للبيانات التي لا تناسب الصفوف والأعمدة المرتبة. انظر ما هو Postgres.
• مخرجات الذكاء الاصطناعي. حين تريد من نموذج ذكاء اصطناعي أن يعيد شيئًا يمكن للبرنامج استخدامه، كقائمة وسوم أو حقول مستخرجة من فاتورة، فغالبًا ما تطلب JSON.
• رسائل الأخطاء والسجلات. كثير من الأخطاء تصل بصيغة JSON، وقراءتها غالبًا أسرع طريقة لمعرفة ما حدث.

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

تشبيه يومي

تخيل استمارة ورقية: الاسم: ____، الهاتف: ____، النشرة البريدية: ☐ نعم ☐ لا. كل مدخل عبارة عن تسمية بجوارها قيمة. JSON هو هذه الاستمارة مكتوبة كنص، بتخطيط صارم يستطيع الحاسوب قراءته دون تخمين. ومثل الاستمارات، يستطيع JSON أن يحتوي أقسامًا داخل أقسام (كتلة عنوان فيها الشارع والمدينة والرمز البريدي) وقوائم (عدة أرقام هواتف).

كيف يبدو JSON

هذا حجز واحد بصيغة JSON:

{
  "id": 5001,
  "customer": "Lena Park",
  "service": "Haircut",
  "startsAt": "2026-10-03T14:00:00Z",
  "price": 35.5,
  "paid": false,
  "notes": null,
  "extras": ["beard trim", "hot towel"],
  "contact": {
    "email": "lena@example.com",
    "phone": "+44 20 7946 0000"
  }
}

كيف تقرؤه:

• الأقواس المعقوفة { } تحيط كائنًا، وهو مجموعة من أزواج الاسم والقيمة.
• كل زوج بالشكل "الاسم": القيمة، ويفصل بينها فواصل.
• الأقواس المربعة [ ] تحيط مصفوفة، وهي قائمة مرتبة.
• يمكن أن تكون الكائنات والمصفوفات داخل بعضها، كما في contact وextras.

أنواع القيم الستة

لدى JSON ستة أنواع من القيم فقط. هذه القائمة الصغيرة جزء كبير من سبب عمله في كل مكان.

لا يوجد نوع للتاريخ. تُكتب التواريخ نصوصًا، عادةً بصيغة ISO 8601 الموضحة أعلاه (2026-10-03T14:00:00Z، حيث Z تعني التوقيت العالمي UTC). الاتفاق على هذه الصيغة يتجنب فئة كاملة من أخطاء المناطق الزمنية.

القواعد الصارمة (ومنها تأتي الأخطاء)

JSON أقل تساهلًا مما يبدو. كل ما يلي غير صالح:

{ name: "Lena" }            ← مفتاح بلا علامات اقتباس مزدوجة
{ 'name': 'Lena' }          ← علامات اقتباس مفردة
{ "a": 1, "b": 2, }         ← فاصلة زائدة
{ "a": 1 "b": 2 }           ← فاصلة ناقصة
{ "a": 1 // comment }       ← التعليقات غير مسموحة

معظم رسائل «Unexpected token» التي تراها هي واحد من هذه. وأداة التحقق أو التنسيق لـ JSON ستعرض لك السطر الدقيق.

مثال عملي: JSON عبر تطبيق

يحجز عميل قصة شعر في تطبيق صالون. هذا مكان ظهور JSON:

1. يرسل نموذج الحجز هذا إلى خلفية التطبيق:

{ "service": "Haircut", "startsAt": "2026-10-03T14:00:00Z", "name": "Lena Park" }

1. تحفظ الخلفية الحجز في قاعدة البيانات وترد بالحالة 201 Created مع:

{ "id": 5001, "status": "confirmed" }

1. إذا كان الوقت محجوزًا من قبل، فقد ترد بالحالة 409 Conflict مع:

{ "error": "slot_taken", "message": "That time was just booked. Please pick another." }

تقرأ الصفحة status أو error وتعرض الرسالة الصحيحة. وإذا ظهرت شاشة فارغة بدلًا من ذلك، فإن فتح أدوات المطور في المتصفح (تبويب Network) سيُظهر لك هذا JSON، وغالبًا هو أسرع دليل على سبب المشكلة.

مصطلحات أساسية

مفاهيم خاطئة شائعة

• «JSON هو JavaScript». جاء من بناء جملة JavaScript، لكنه مستقل عن اللغات؛ فـ Python وJava وC# وGo وغيرها تقرؤه جميعًا.
• «الأرقام بين علامات الاقتباس لا بأس بها». "35" نص وليس رقمًا. وخلط الاثنين يسبب أخطاء مثل تحول "35" + "5" إلى "355". والمال يُحفظ غالبًا كأعداد صحيحة بالسنتات (3550) لتجنب مشكلات التقريب.
• «JSON آمن لأنه مجرد بيانات». يستطيع JSON حمل أي شيء، بما فيه الأسرار. لا تضع مفاتيح واجهات برمجية في JSON يُرسل إلى المتصفح.
• «ضع كل شيء في عمود JSON». مفيد للإضافات المرنة، لكن البيانات التي تبحث عنها أو تصفيها أو تربطها غالبًا ما تنتمي إلى أعمدة حقيقية.
• «الذكاء الاصطناعي يعيد JSON صالحًا دائمًا». قد تضيف النماذج نصًا إضافيًا أو تكسر الصيغة. كثير من المزودين يقدمون وضع المخرجات المهيكلة، لكن كودك يجب أن يتحقق مما يعود على أي حال.

ماذا تطلب من مُنشئ التطبيقات بالذكاء الاصطناعي

• «أرني مثالًا على JSON الذي تعيده نقطة النهاية هذه.»
• «أعد الأخطاء بصيغة JSON فيها رمز error ورسالة message مقروءة للبشر.»
• «خزّن التواريخ كنصوص ISO 8601 بالتوقيت العالمي UTC، وحوّلها إلى التوقيت المحلي عند العرض فقط.»
• «خزّن الأسعار كأعداد صحيحة بالسنتات.»
• «تحقق من JSON الوارد على الخادم، وارفض الطلبات التي تنقصها حقول أو تأتي بأنواع خاطئة.»
• «حين تستدعي نموذج الذكاء الاصطناعي، اطلب JSON بهذا الشكل بالضبط، وتحقق منه قبل استخدامه.»

JSON في Mythex

لا تحتاج إلى كتابة JSON يدويًا في Mythex؛ تصف ما تريد، ويكتب الوكيل الكود الذي يرسله ويقرأه. ومع ذلك يفيد أن تتعرف عليه، فحين يتعطل شيء، يعطي لصق خطأ JSON في المحادثة الوكيل دليلًا دقيقًا. وصفة الخلفية كواجهة REST في الوثائق تطلب «رسائل أخطاء JSON واضحة» من البداية، ووصفة دمج أي واجهة برمجية تغطي استدعاء الخدمات الخارجية. وللصورة الأوسع، انظر REST مقابل GraphQL وكيف تُصحّح تطبيقًا بُني بالذكاء الاصطناعي.

الأسئلة