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

JSON لا يمنحك سوى حاويتين: الكائن يحمل الحقول المسماة، والمصفوفة تحمل القوائم المرتبة — وكل حمولة تالفة تقريبًا يفسّرها علامات اقتباس أو فواصل أو قائمة كُتبت على شكل كائن مزيف.
أولاً: JSON لا يملك سوى حاويتين
مهما كانت استجابة API معقدة، يُختصر كل شيء إلى حاويتين وستة أنواع من القيم. الكائن مجموعة من أزواج مفتاح/قيمة محاطة بأقواس معقوفة {}؛ والمصفوفة قائمة مرتبة من القيم محاطة بأقواس مربعة []. قد تكون القيمة سلسلة أو رقمًا أو true أو false أو null — أو كائنًا أو مصفوفة من جديد. كائنات داخل مصفوفات، مصفوفات داخل كائنات: هذا التكرار هو كامل القدرة التعبيرية لـ JSON.
{
"user": { "name": "Ada", "active": true },
"roles": ["admin", "editor"],
"lastLogin": null,
"loginCount": 42
}
من هذا تنتج نتيجة عملية: أمام حمولة محيّرة، لا تقرأها محرفًا بمحرف. تحقق أولًا من المحرف الخارجي: هل هو { أم [؟ إن كان كائنًا، اقرأه كحقول مسماة؛ وإن كان مصفوفة، اقرأه كقائمة ثم انزل مستوىً بعد مستوى. مخطط التركيب في json.org يتسع لصفحة واحدة تحديدًا لأن بنيتين مع التكرار يغطيان كل شيء.
ثانيًا: كتابة الكائنات، أربع قواعد صارمة
الكائنات هي المكان الذي يخطئ فيه المبتدئون أكثر، لكن القواعد تختصر إلى أربع:
- المفاتيح يجب أن تكون سلاسل داخل علامتي اقتباس مزدوجتين.
{name: "Ada"}و{'name': 'Ada'}كلاهما غير صالح؛ يجب كتابة{"name": "Ada"}. الحرفيات الكائنية في JavaScript تسمح بالمفاتيح العارية وبالاقتباس المفرد، وJSON لا يسمح — وهذا هو الالتباس الأكثر شيوعًا بينهما. - افصل الأزواج بفواصل ولا تترك فاصلة أبدًا بعد الزوج الأخير.
{"a": 1, "b": 2,}تفشل بخطأUnexpected token }عند القوس المعقوف الختامي. - المفاتيح ينبغي أن تكون فريدة. يصوغ RFC 8259 ذلك بـ SHOULD لا MUST: المفاتيح المكررة لا تسبب خطأ، لكن إبقاء القيمة الأولى أو الأخيرة يعتمد على التنفيذ، واللغات تختلف. لا تعتمد عليه أبدًا.
- ترتيب المفاتيح لا معنى له.
{"a":1,"b":2}و{"b":2,"a":1}كائن واحد؛ أدوات الفروق ودوال المقارنة تتجاهل ترتيب المفاتيح. إن كان الترتيب مهمًا فالبيانات ملك مصفوفة.
ثالثًا: كتابة المصفوفات، الترتيب نفسه بيانات
المصفوفات تخزن القيم حسب الموضع، والفهرسة تبدأ من 0: في ["admin", "editor"] السلسلة "editor" هي [1]. هذا الترتيب ذو معنى — وهو الفرق الجوهري بين المصفوفات والكائنات. نتائج بحث مرتبة حسب الصلة، سجلات مرتبة حسب التاريخ: هذه المعلومات لا تعيش إلا في التتابع، وتحويلها إلى كائن يدمّرها.
توصيتان عمليتان. أولًا، حافظ على تجانس العناصر: [{"id":1},{"id":2}] أسهل بكثير في الاستهلاك من [1, "text", true] — صالحة لكنها تجبر كل مستهلك على اختبار الأنواع في كل خطوة. ثانيًا، المصفوفة الفارغة [] قيمة صالحة تمامًا — حين لا يزال حقل قائمة بلا محتوى، أرسل [] لا null، حتى لا يضطر المستهلك للتحقق من الوجود ثم من الفراغ.
[
{ "city": "Tokyo", "population": 13960000 },
{ "city": "Delhi", "population": 16780000 }
]
رابعًا: التداخل، الأشكال الأربعة للحمولات الحقيقية
البيانات الحقيقية ليست إلا هاتين الحاويتين متداخلتين إحداهما في الأخرى، والأنماط تختصر إلى أربعة أشكال:
| الشكل | الشكل الظاهر | الاستخدام النمطي |
|---|---|---|
| كائن يحوي مصفوفة | {"tags": ["a","b"]} |
حقل قائمة لكيان ما |
| مصفوفة من كائنات | [{"id":1},{"id":2}] |
قوائم سجلات، نتائج مقسمة لصفحات |
| كائن يحوي كائنًا | {"db": {"host": "..."}} |
تهيئة مجمعة، كتل عناوين |
| مصفوفة من مصفوفات | [[1,2],[3,4]] |
مصفوفات رياضية، صفوف جداول |
استجابة API نموذجية تستخدم كائنًا كغلاف ومصفوفة كمحتوى:
{
"code": 0,
"data": {
"items": [
{ "id": 1, "title": "first" },
{ "id": 2, "title": "second" }
],
"page": 1,
"total": 2
}
}
لا تداغل لغرض التداغل. بعد ثلاثة أو أربعة مستويات تصبح مسارات الوصول غير مقروءة، وينتفخ كود المستهلك بالتوازي. الحقول التي تسافر معًا دائمًا تخص كائنًا فرعيًا: استبدل addrCity و addrZip بـ address: {city, zip}.
خامسًا: كائن أم مصفوفة، جدول قرار
| السؤال | الجواب | لماذا |
|---|---|---|
| لكل قيمة اسم؟ | كائن | الوصول بالمفتاح؛ إضافة أو حذف حقول لا يكسر شيئًا |
| قائمة سجلات متشابهة؟ | مصفوفة | الترتيب مهم؛ يمكن map وfilter |
| يلزم بحث سريع بالمفتاح؟ | كائن مفهرس بالمعرّف | وصول O(1) بدل المرور |
| عدة صفات لكيان واحد؟ | كائن | الصفات لا ترتيب ذاتي لها |
| مجموعة نامية من عناصر متشابهة؟ | مصفوفة | الطول يتمدد بحرية |
نمط مضاد يستحق ذكرًا خاصًا: محاكاة مصفوفة بكائن مفاتيحه "0" و "1" و "2". يُحلل بلا خطأ، لكنك تفقد دلالة الطول وأدوات التكرار لمصفوفة حقيقية، والمستهلكون مضطرون لترتيب Object.keys قبل قراءة أي شيء. إن كانت المفاتيح أرقامًا متسلسلة، اكتب مصفوفة حقيقية. والعكس صحيح أيضًا: قائمة أزواج مفتاح/قيمة مثل [{"key":"theme","value":"dark"}] أدنى من الكائن {"theme": "dark"} — إلا إذا كانت المفاتيح ديناميكية حقًا ولا يمكن التصريح بها مسبقًا.
سادسًا: ثلاثة أخطاء متكررة ورسائلها
| الشكل الخاطئ | الخطأ النمطي | التصحيح |
|---|---|---|
فاصلة ختامية {"a":1,} |
Unexpected token } |
حذف الفاصلة الأخيرة |
اقتباس مفرد / مفاتيح عارية {name:'Ada'} |
Unexpected token ' / Expected property name |
اقتباس مزدوج للمفاتيح والسلاسل، دائمًا |
حرفيات Python True / None |
Unexpected token T |
الاستبدال بـ true / null |
| مصفوفة مزيفة بمفاتيح رقمية | بلا خطأ، دلالة خاطئة | إعادة الكتابة كمصفوفة حقيقية |
عادتان في التنقيح: المحللات عادةً تُبلغ عن موضع بعد المحرف المذنب، فعندما ترى position 42 انظر محرفًا أو محرفين للخلف؛ وملف JSON ضخم في سطر واحد ينبغي تنسيقه أولًا — أرقام الأسطر والأعمدة تغلب الإزاحات الرقمية في كل مرة. كatalog الأخطاء الكامل في جدول مطابقة أخطاء JSON، ومسار الفرز خطوة بخطوة في كيف تصلح أخطاء تحليل JSON.
سابعًا: بعد الكتابة، تحقق من البنية
ملف JSON مكتوب يدويًا يجب أن يمر عبر محلل قبل التسليم دائمًا. أخف تحقق يتسع لسطر أوامر واحد:
python3 -m json.tool config.json > /dev/null && echo OK
jq empty config.json && echo OK
عبر الإنترنت، ألصق المحتوى في صفحة منسّق JSON ومتحققه — ترجع أخطاء التركيب مع السطر والعمود. انتقل إلى العرض الشجري لترى نوع كل مستوى بنظرة واحدة: هل عُدّ رقم ما سلسلة، وهل أطوال المصفوفات متوافقة. وعندما لا يكون الجمهور تقنيًا، يمكن فرد حمولة مصفوفة-كائنات إلى صفوف وأعمدة في صفحة JSON إلى جدول، وهو ما يتحقق بالمناسبة أن بياناتك قائمة سجلات منتظمة فعلًا.
أسئلة الحقل الذي كان يجب أن يكون مصفوفة، أو إعادة بناء تداخل أصبح عميقًا أكثر من اللازم، تنتمي إلى نمذجة الأنواع — القراءة التالية: ستة أنواع، دقة الأرقام وفخاخ الترميز.
هل يمكن تحويل المصفوفات والكائنات في JSON من واحد إلى الآخر؟
نعم، لكن ليس بلا خسائر. تحويل كائن إلى مصفوفة يعني عادةً تحويل المفاتيح إلى قيم وفقدان الوصول بالمفتاح؛ وتحويل مصفوفة إلى كائن يستلزم ابتداع مفتاح لكل عنصر، وأصل هذه المفاتيح مشكلة تصميم جديدة. قرر بحسب كيف يقرأ المستهلك البيانات، لا بحسب راحة الصياغة.
هل يمكن تكرار مفاتيح الكائن؟
نحويًا نعم — RFC 8259 يقول فقط إن المفاتيح Yنبغي أن تكون فريدة. لكن JavaScript يحتفظ بالقيمة الأخيرة بينما بعض مكتبات عائلة C تحتفظ بالأولى: السلوك يختلف بين المحللات. في التواقيع أو الفروق أو التجزئة، المفاتيح المكررة تنتج خلافات مباشرة. تجنبها في جانب المنتج، واعتبر المكررات من مصدر مجهول خطرًا في جانب المستهلك.
هل يمكن أن تحوي المصفوفة قيمًا بأنواع مختلفة؟
نحويًا نعم: [1, "a", true] صالحة. لكن المصفوفات غير المتجانسة تجبر المستهلك على فحص الأنواع في كل موضع، ويصعب التعبير عنها في مخطط. عدوى المصفوفات الرياضية والصفوف — حيث الموضع هو الدلالة — حافظ على تجانس مصفوفاتك.
لماذا يفشل {name:'json'} في التحقق؟
لأن JSON يفرض علامتي اقتباس مزدوجتين حول كل مفتاح وكل قيمة سلسلة. {name:'json'} حرفية كائن JavaScript وليست JSON. استبدلها بـ {"name": "json"} ويمر التحقق. الاقتباس المفرد والمفاتيح العارية والتعليقات ملك لهجات مثل JSON5/JSONC التي تتطلب محللاتها الخاصة بدل JSON.parse القياسي.