ما هو JSON؟ الصياغة والأخطاء الشائعة وطريقة التحقق منه

Q: ماذا تعني الرسالة «Unexpected token < in JSON at position 0»؟

يبدأ النص الجاري تحليله بالرمز < ، وهذا يعني في الغالب الأعم أنك تلقيت HTML، مثل صفحة خطأ أو تسجيل دخول، بدلًا من JSON. افحص عنوان URL للطلب ورمز حالة HTTP ومتن الاستجابة الخام.

Q: هل يُحفَظ ترتيب المفاتيح في كائن JSON؟

يعامل المعيار الكائنات على أنها غير مرتّبة، فلا ينبغي أن تعتمد على ترتيب المفاتيح. وعمليًا تحتفظ معظم المحلِّلات الحديثة بالترتيب الذي قرأته، لكن ترتيب المصفوفات هو الترتيب الوحيد الذي تضمنه JSON.

Q: ما امتداد الملف ونوع MIME اللذان تستخدمهما JSON؟

تستخدم الملفات الامتداد.json ، ونوع الوسائط هو application/json ، كما هو مسجَّل في RFC 8259.

JSON (اختصار JavaScript Object Notation) صيغة نصية خفيفة لتخزين البيانات المنظّمة وتبادلها، وتتألف من كائنات تضم أزواج مفتاح/قيمة، ومصفوفات مرتّبة، وعدد قليل من أنواع القيم: النصوص والأرقام وtrue وfalse وnull. وهي الصيغة الافتراضية لواجهات الويب البرمجية (API) وكثير من ملفات الإعداد، لأن قراءتها سهلة على البشر وتحليلها بسيط في كل لغات البرمجة. وJSON صارمة: فالمفاتيح والنصوص تحتاج إلى علامات اقتباس مزدوجة، ولا يُسمح بالفواصل الزائدة في النهاية ولا بالتعليقات.

أهم النقاط

لـ JSON ستة أنواع من القيم بالضبط: كائن (object) ومصفوفة (array) ونص (string) ورقم (number) وقيمة منطقية (true/false) وnull.
يجب أن تكون المفاتيح نصوصًا بين علامتي اقتباس مزدوجتين؛ ولا تصحّ علامات الاقتباس المفردة أبدًا.
لا فواصل زائدة في النهاية، ولا تعليقات، ولا undefined ولا NaN ولا Infinity.
تنشأ معظم أخطاء «JSON غير صالحة» من فاصلة ناقصة أو زائدة، أو علامة اقتباس خاطئة، أو حرف غير مُهرَّب داخل نص.
تحقق من الصياغة أولًا بمحلِّل صارم، ثم تحقق من البنية بـ JSON Schema إذا احتجت إلى ذلك.

كيف تبدو JSON

نشأت JSON من الصياغة التي تستخدمها JavaScript لكتابة الكائنات الحرفية (object literals)، لكنها مستقلة عن أي لغة. وهي معرَّفة في RFC 8259 وفي معيار ECMA-404، ويصف الملخص ذو الصفحة الواحدة في json.org القواعد النحوية كلها. وهكذا تبدو وثيقة نموذجية:

{
  "id": 1042,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "active": true,
  "score": 98.5,
  "manager": null,
  "roles": ["admin", "editor"],
  "address": {
    "city": "London",
    "postcode": "N1 9GU"
  }
}

تُتجاهل المسافات الفارغة بين العناصر (المسافات وعلامات التبويب وفواصل الأسطر)، لذلك يمكن كتابة البيانات نفسها في سطر واحد أو موزّعة بمسافات بادئة. ويمكن أن يكون المستوى الأعلى في وثيقة JSON أي قيمة، مع أن واجهات API تستخدم في الغالب كائنًا أو مصفوفة.

أنواع بيانات JSON

النوع	مثال	القواعد
كائن (Object)	`{"a": 1, "b": 2}`	مجموعة غير مرتّبة من أزواج مفتاح/قيمة بين أقواس معقوفة. المفاتيح نصوص؛ وتفصل نقطتان رأسيتان بين المفتاح والقيمة؛ وتفصل الفواصل بين الأزواج.
مصفوفة (Array)	`[1, "two", false]`	قائمة مرتّبة من القيم بين أقواس مربعة، تفصل بينها فواصل. يمكن أن تكون القيم من أنواع مختلفة.
نص (String)	`"caf\u00e9 \"quoted\""`	علامات اقتباس مزدوجة فقط. رموز الهروب بالشرطة المائلة العكسية: `\"` `\\` `\/` `\b` `\f` `\n` `\r` `\t` و`\uXXXX`. لا يُسمح بفواصل الأسطر الخام ولا بعلامات التبويب داخل النصوص.
رقم (Number)	`-12` و`3.14` و`6.02e23`	عشري فقط. لا علامة `+` في البداية، ولا أصفار بادئة (`07`)، ولا نظام ستة عشري، ولا `NaN` أو `Infinity`. ويجب أن تكون على جانبي الفاصلة العشرية أرقام.
قيمة منطقية (Boolean)	`true` و`false`	بأحرف صغيرة ودون علامات اقتباس.
Null	`null`	بأحرف صغيرة ودون علامات اقتباس. تمثّل قيمة فارغة أو غير معروفة.

لا يوجد نوع للتواريخ. تُكتب التواريخ عادةً نصوصًا بصيغة ISO 8601 مثل "2026-10-13T09:30:00Z"، أو أرقامًا بصيغة الطابع الزمني Unix؛ ويحوّل محوّل الطابع الزمني Unix لدينا بين الصيغتين.

الأرقام والدقة

لا يحدّ معيار JSON من حجم الأرقام ولا من دقتها، لكن البرامج التي تقرؤها تفعل ذلك. تخزّن JavaScript الأرقام قيمًا عشرية عائمة بدقة 64 بت، لذلك قد تفقد الأعداد الصحيحة الأكبر من 9,007,199,254,740,991 (2⁵³ − 1) دقتها بصمت. وفي المعرّفات الكبيرة ترسلها واجهات API كثيرة نصوصًا، مثل "id": "1234567890123456789".

القواعد التي يتعثّر بها الناس

تشبه JSON كلًّا من JavaScript وقواميس Python وYAML، وهذا بالضبط ما يجعل الناس يكتبون JSON غير صالحة عن غير قصد. هذه القواعد لا استثناء لها في JSON القياسية:

يجب أن تكون المفاتيح نصوصًا بين علامتي اقتباس مزدوجتين. الصيغة {name: "Ada"} صالحة في JavaScript لكنها غير صالحة في JSON؛ اكتب {"name": "Ada"}.
علامات الاقتباس المزدوجة فقط. 'Ada' ليست نص JSON.
لا فواصل زائدة في النهاية. [1, 2, 3,] و{"a": 1,} غير صالحتين.
لا تعليقات. لا يُسمح بـ // ... ولا بـ /* ... */.
القيم الحرفية بأحرف صغيرة. True وFALSE وNone (كتابة Python) غير صالحة؛ استخدم true وfalse وnull.
لا undefined ولا دوال ولا أرقام خاصة. هذه موجودة في JavaScript لكن لا مقابل لها في JSON.
ينبغي أن تكون المفاتيح فريدة. ينص المعيار على أن الأسماء داخل الكائن ينبغي أن تكون فريدة؛ ومع التكرار تتصرف المحلِّلات بطرق مختلفة، وكثير منها يحتفظ بالأخير فقط دون تنبيه.

تقبل بعض الأدوات صيغًا مخففة. فملفات مثل settings.json في VS Code وtsconfig.json في TypeScript تُقرأ بمحلِّلات تسمح بالتعليقات (تُسمّى غالبًا JSONC)، وتسمح JSON5 بالتعليقات وعلامات الاقتباس المفردة والفواصل الزائدة. هذه صيغ مستقلة: فمحلِّل JSON القياسي، بما في ذلك الذي يستخدمه عميل API أو الخادم لديك، سيرفضها.

أخطاء JSON الشائعة وكيفية إصلاحها

تختلف صياغة رسائل الخطأ بين المحلِّلات. يبيّن الجدول نوع الرسالة التي ستراها من وحدة json في Python أو من JSON.parse في المتصفح، وما تعنيه عادةً، وطريقة الإصلاح. وغالبًا ما يشير الموضع المبلَّغ عنه إلى ما بعد الخطأ الحقيقي مباشرةً، فانظر إلى الحرف الذي قبله أيضًا.

المشكلة	رسالة الخطأ المعتادة	الإصلاح
فاصلة زائدة في النهاية: `{"a": 1,}`	«Expecting property name enclosed in double quotes» أو «Unexpected token }»	احذف الفاصلة بعد آخر عنصر في الكائن أو المصفوفة.
مفتاح بلا علامات اقتباس أو بعلامات اقتباس مفردة: `{a: 1}` و`{'a': 1}`	«Expecting property name enclosed in double quotes» أو «Expected double-quoted property name»	ضع كل مفتاح بين علامتي اقتباس مزدوجتين.
قيمة نصية بعلامات اقتباس مفردة: `{"a": 'x'}`	«Expecting value» أو «Unexpected token '»	استخدم علامات الاقتباس المزدوجة، وهرِّب أي علامات اقتباس مزدوجة في داخلها بالشكل `\"`.
فاصلة ناقصة بين العناصر	«Expecting ',' delimiter» أو «Expected ',' or '}' after property value»	أضف فاصلة بين القيمتين أو الزوجين عند السطر المُبلَّغ عنه.
تعليق في الملف	«Expecting value» أو «Unexpected token /»	احذف التعليق، أو انقل الملاحظة إلى حقل بيانات مثل `"_comment"`.
قيم حرفية من Python أو JavaScript: `True` و`None` و`undefined` و`NaN`	«Expecting value» أو «Unexpected token»	استخدم `true` أو `false` أو `null`؛ وحوّل البيانات إلى JSON بمكتبة JSON حقيقية بدلًا من طباعتها.
فاصل أسطر خام أو علامة تبويب داخل نص	«Invalid control character» أو «Bad control character in string literal»	استبدلها بـ `\n` أو `\t`.
شرطة مائلة عكسية غير مُهرَّبة، مثل مسار Windows `"C:\new"`	«Invalid \escape» أو «Bad escaped character»	ضاعف الشرطات المائلة العكسية: `"C:\\new"`.
قوس إغلاق أو علامة اقتباس ناقصة	«Unterminated string» أو «Unexpected end of JSON input»	تأكد من إغلاق كل `{` و`[` و`"`؛ فالمسافات البادئة التي يضيفها المنسِّق تُظهر الموضع الناقص بوضوح.
وثيقتان متتاليتان، أو نص بعد النهاية	«Extra data» أو «Unexpected non-whitespace character after JSON»	ضع عدة كائنات في مصفوفة، أو عالج المدخلات بصيغة JSON Lines (وثيقة واحدة في كل سطر).
استجابة فارغة أو صفحة خطأ HTML جرى تحليلها على أنها JSON	«Expecting value: line 1 column 1» أو «Unexpected token <»	افحص رمز حالة HTTP ومتن الاستجابة؛ فقد أعاد الخادم شيئًا آخر غير JSON.

الصف الأخير من أكثر الحالات تكرارًا عمليًا: يستدعي الكود JSON.parse أو response.json() على صفحة خطأ تبدأ بـ <!DOCTYPE html>، فيُبلَّغ عن الرمز < على أنه رمز غير متوقع.

JSON مقابل YAML وXML

	JSON	YAML	XML
البنية	أقواس معقوفة ومربعة	المسافات البادئة	وسوم فتح وإغلاق
التعليقات	لا	نعم (`#`)	نعم (`<!-- -->`)
أنواع البيانات	نص ورقم وقيمة منطقية وnull وكائن ومصفوفة	مشابهة، إضافةً إلى التواريخ وأنواع أخرى بحسب المحلِّل	كل شيء نص ما لم يُسند مخطط أنواعًا
السمات والمحتوى المختلط	لا	لا	نعم
الإسهاب	مختصرة	الأكثر اختصارًا في القراءة	الأكثر إسهابًا
الاستخدامات المعتادة	واجهات الويب البرمجية، وتخزين المتصفح، وملفات تعريف الحزم، وملفات السجل	الإعدادات: Kubernetes وDocker Compose وخطوط CI	المستندات، وSOAP، وRSS وAtom، وخرائط المواقع، وصيغ ملفات المستندات المكتبية
أبرز المآزق	الصرامة في علامات الاقتباس والفواصل	حساسة للمسافات الفارغة؛ وبعض القيم غير المقتبسة تُفسَّر بطرق غير متوقعة	مسهبة؛ وتزيد المساحات الاسمية والكيانات التعقيد

صُمّمت YAML 1.2 بحيث تكون وثائق JSON، باستثناء حالات هامشية نادرة، صالحة أيضًا بصيغة YAML، ما يجعل التحويل بينهما مباشرًا. يتعامل محوّل JSON ↔ YAML لدينا مع الاتجاهين، ويتحقق منسّق YAML وأداة التحقق منه ومنسّق XML وأداة التحقق منه من الصيغتين الأخريين، ويحوّل محوّل CSV ↔ JSON ملفات التصدير من جداول البيانات إلى مصفوفات من الكائنات.

التنسيق المقروء والتصغير

لأن المسافات الفارغة غير مؤثرة، يمكن تنسيق JSON نفسها للبشر أو للآلات:

JSON المنسَّقة للقراءة (pretty-printed) تضيف فواصل أسطر ومسافات بادئة، وغالبًا مسافتين أو أربعًا، فيظهر التداخل واضحًا. استخدمها في ملفات الإعداد والتوثيق وتصحيح الأخطاء.
JSON المصغَّرة (minified) تزيل كل المسافات الاختيارية لتصغير الحمولة. استخدمها في البيانات المرسلة عبر الشبكة أو المخزَّنة بكميات كبيرة؛ ويقلّل ضغط HTTP الحجم أيضًا، لذلك يكون التوفير في الغالب متواضعًا.

{"name":"Ada","roles":["admin","editor"],"active":true}

تستطيع معظم اللغات الأمرين معًا. ففي JavaScript تنسّق JSON.stringify(data, null, 2) النص للقراءة بمسافتين بادئتين، وتصغّره JSON.stringify(data). وفي Python تنسّق json.dumps(data, indent=2) النص للقراءة، وتعطي json.dumps(data, separators=(",", ":")) أكثر المخرجات إحكامًا.

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

للتحقق من JSON مستويان: هل هي JSON صالحة صياغيًا أصلًا، وهل لها البنية التي يتوقعها تطبيقك؟

تحقق من الصياغة بمحلِّل صارم. الصق النص في منسّق JSON وأداة التحقق منه الذي يبلّغ عن سطر أول خطأ وعموده، ويعمل داخل متصفحك. وفي سطر الأوامر تطبع python3 -m json.tool data.json أو jq . data.json الوثيقة منسَّقة أو رسالة خطأ.
أصلح الأخطاء واحدًا تلو الآخر. يتوقف المحلِّل عند أول مشكلة، لذلك أعد تشغيله بعد كل إصلاح حتى ينجح.
تحقق من البنية. تأكد من وجود الحقول المطلوبة وصحة أنواعها، إما في الكود أو بمدقِّق JSON Schema.
تحقق من الترميز. ينبغي أن تكون JSON المتبادلة بين الأنظمة بترميز UTF-8. وقد يؤدي ملف محفوظ بترميز آخر إلى ظهور رموز غريبة أو أخطاء في النصوص غير الإنجليزية.

JSON Schema باختصار

JSON Schema مفردات، مكتوبة بـ JSON نفسها، لوصف شكل الوثيقة الصالحة: أي الخصائص مطلوبة، وما نوع كل منها، والقيم المسموح بها، وأنماط النصوص، ونطاقات الأرقام، وغير ذلك. وتتوفر مدقِّقات لمعظم اللغات، وتستخدم صيغ وصف واجهات API مثل OpenAPI مخطط JSON Schema لوصف متون الطلبات والاستجابات. المواصفة منشورة في json-schema.org. وهذا مثال صغير:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "roles": { "type": "array", "items": { "type": "string" } }
  }
}

وثيقة تفتقد email أو يكون فيها id نصًا ستكون JSON صالحة لكنها تفشل في هذا المخطط. وانتبه إلى أن مدقِّقات كثيرة تعامل format على أنه توضيح فقط ولا تفرضه ما لم تُضبط على ذلك.

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

هل يمكن أن تحتوي JSON على تعليقات؟

لا. لا تسمح JSON القياسية بأي نوع من التعليقات. تقبل بعض الأدوات JSONC أو JSON5 اللتين تسمحان بها، لكن الملفات المعدّة لتقرأها برامج أخرى ينبغي أن تلتزم بـ JSON العادية. وإذا احتجت إلى ملاحظة فأضف حقلًا مثل "_comment".

لماذا لا تسمح JSON بالفواصل الزائدة في النهاية؟

أُبقيت القواعد النحوية في حدها الأدنى عمدًا، وهي ببساطة لا تتضمنها. تقبل محركات JavaScript كثيرة ولغات أخرى فواصل زائدة في صياغتها الخاصة، ولهذا تظهر كثيرًا في JSON المكتوبة يدويًا بالخطأ.

ما الفرق بين JSON وكائن JavaScript؟

JSON صيغة نصية؛ أما كائن JavaScript فهو بنية بيانات في الذاكرة. وصياغة JSON مجموعة فرعية أكثر صرامة من صياغة الكائنات الحرفية في JavaScript. وتحوّل بينهما باستخدام JSON.parse وJSON.stringify.

ماذا تعني الرسالة «Unexpected token < in JSON at position 0»؟

يبدأ النص الجاري تحليله بالرمز <، وهذا يعني في الغالب الأعم أنك تلقيت HTML، مثل صفحة خطأ أو تسجيل دخول، بدلًا من JSON. افحص عنوان URL للطلب ورمز حالة HTTP ومتن الاستجابة الخام.

هل يُحفَظ ترتيب المفاتيح في كائن JSON؟