منسق JSON

الصق ملف JSON مضغوطاً أو مبعثراً واحصل على مخرجات بمسافات بادئة مثالية فوراً. يقوم المنسق بتحليل JSON الخاص بك باستخدام JSON.parse الأصلي للمتصفح (وفقاً لـ ECMA-404)، ويحافظ على أحرف Unicode، ويعيد إصدارها بالمسافة البادئة التي تختارها:

• مسافتان (الافتراضي لـ npm وprettier)
• 4 مسافات
• علامة تبويب (tab)

تتم محاذاة الكائنات والمصفوفات المتداخلة بمسافات بادئة صحيحة عند كل عمق. تحصل المفاتيح والنصوص والأرقام والقيم المنطقية وnull على ألوان تمييز بنية مختلفة حتى تتمكن من فحص البنية بلمحة.

تسمية 'beautifier' قابلة للتبديل مع 'formatter' أو 'pretty printer' — وكلها تصف نفس العملية: إنتاج JSON قابل للقراءة البشرية من مدخلات مضغوطة.

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

التحقق صارم وفقاً لـ RFC 8259 (معيار الإنترنت IETF) وECMA-404 — لا تعليقات، لا فواصل ختامية، لا علامات اقتباس مفردة، لا مفاتيح بدون اقتباس، لا NaN، لا Infinity، لا undefined. يمكن أن تكون قيمة المستوى الأعلى أي قيمة JSON (كائن، مصفوفة، نص، رقم، true، false، null).

بالنسبة للمدخلات المرمزة بـ UTF-8، يقبل المنسق مجموعة أحرف Unicode الكاملة؛ يجب أن تستخدم بيئات ASCII فقط ترميزات \uXXXX.

الأخطاء الشائعة والحلول:

• فاصلة ختامية بعد آخر عنصر في المصنوعة/الكائن (قم بإزالتها)
• علامات اقتباس مفردة حول المفاتيح أو النصوص (استبدلها بعلامات اقتباس مزدوجة)
• قوس إغلاق مفقود (يشير عمود الخطأ بالقرب من موقع الاقتطاع)
• أحرف تحكم غير مهربة في النصوص (قم بهروبها بـ \n، \t، \\)

يجرّد الضغط (Minification) جميع المساحات الفارغة غير الهامة — المسافات بين الرموز، والمسافات البادئة، والأسطر الجديدة — مما يترك التمثيل الأكثر ضغطاً ممكناً. التوفير النموذجي هو 20–60% اعتماداً على مقدار المسافة البادئة في JSON المصدر.

استخدم JSON المضغوط لـ:

• استجابات REST/GraphQL API
• رسائل WebSocket
• حمولات JWT
• كتل إعدادات SaaS
• سمات البيانات المدمجة في HTML

احتفظ بـ JSON المنسق لـ:

• ملفات الإعدادات الخاضعة للتحكم في الإصدارات
• التثبيتات واللقطات في الاختبارات
• المستندات المحررة بشرياً

لا يزال JSON المضغوط معيارياً بنسبة 100% — ويقبله أي محلل متوافق. يضمن المضغط هنا الحفاظ على البيانات بدقة: لا إعادة ترتيب للمفاتيح، لا إكراه للقيمة، لا فقدان للدقة في الأرقام ضمن نطاق IEEE 754 المزدوج.

يتحقق التحقق النحوي البسيط لـ JSON فقط من تحليل المستند. بينما يتحقق JSON Schema من شكل المستند — مثل أن 'email' نص، و'age' عدد صحيح بين 0–150، و'role' أحد الخيارات ['admin', 'user', 'guest']. المخطط نفسه هو مستند JSON يصف القيود؛ وتتم التحققات للمثيلات ضده.

الكلمات المفتاحية الشائعة: type، required، properties، items، enum، pattern (regex)، minimum/maximum، minLength/maxLength، format (email، date-time، uri).

تنفيذ المراجع:

• Ajv (JavaScript، الأسرع)
• jsonschema (Python)
• networknt/json-schema-validator (Java)
• justinrainbow/json-schema (PHP)

يكتشف التحقق من المخطط فئة كبيرة من الأخطاء عند حدود API: الحقول المطلوبة المفقودة، والأنواع الخاطئة، والقيم خارج النطاق، والتواريخ المشوهة. تستخدم مواصفات OpenAPI 3.x معيار JSON Schema للتحقق من الطلبات والاستجابات.

JSONPath بالنسبة لـ JSON كـ XPath بالنسبة لـ XML — لغة استعلام للتنقل والاستخراج من JSON المتداخل.

الصياغة النحوية:

• $ (الجذر)
• . (الابن)
• .. (الانحدار التكراري)
• [n] (فهرس المصفوفة)
• [start:end] (شريحة)
• [?(expression)] (تصفية)
• * (رمز بدل)

أمثلة على JSON متجر نموذجي:

• $.store.book[0].title يجلب عنوان الكتاب الأول
• $..author يعيد كل مؤلف عبر المستند
• $.store.book[?(@.price < 10)] يصفّي الكتب الأرخص من 10
• $.store..price[*] يسطّح جميع الأسعار

الأدوات: jq (بصياغة مختلفة قليلاً ولكن بنفس الإمكانيات، وسائد في البرمجة النصية للغلاف)، وسكربتات اختبار Postman، وJMESPath (الخاص بـ AWS CLI --query)، ومكتبات JSONPath في كل لغة رئيسية.

أسطر JSON (jsonlines.org)، والمعروفة أيضاً باسم NDJSON أو LDJSON، هي صيغة يكون فيها كل سطر عبارة عن قيمة JSON كاملة. الملف ككل ليس بتنسيق JSON صالح — ولكن كل سطر بمفرده كذلك.

تُستخدم بكثافة لتدفق السجلات (Loki، Splunk HEC، Vector)، وأنابيب ETL، وبيانات تدريب تعلم الآلة (مثل ملفات ضبط الدقة لـ OpenAI لإنشاء برنامج حساب الوقت)، وأي تدفق بيانات يقتصر على الإضافة فقط.

المميزات:

• مناسبة للتدفق (تحليل سجل واحد في كل مرة، ذاكرة ثابتة)
• تقتصر على الإضافة فقط (فقط اكتب السطر التالي)
• قابلة للبحث والمعالجة باستخدام أدوات Unix القياسية مثل grep و awk

امتدادات الملفات: .jsonl، .ndjson. للتحويل من مصفوفة JSON استخدم `jq -c '.[]'`؛ وللتحويل إلى مصفوفة JSON استخدم `jq -s` (slurp). تدعم منصات BigQuery و Athena و Snowflake ومعظم مستودعات البيانات الحديثة استيراد NDJSON بشكل أصلي.

توسع صيغة JSON5 (json5.org) تنسيق JSON لتوفير تسهيلات للمطورين:

• التعليقات (// و /* */)
• الفواصل الزائدة في نهاية القوائم
• السلاسل النصية المحاطة بعلامات اقتباس مفردة
• المفاتيح غير المحاطة بعلامات اقتباس
• السلاسل النصية متعددة الأسطر (باستخدام الشرطة المائلة العكسية للاستمرار)
• الأرقام السداسية عشرية
• قيم IEEE 754 الخاصة (NaN، Infinity)

هذه الصيغة غير متوافقة مع JSON.parse — ستحتاج إلى محلل JSON5 (مثل حزمة npm json5، أو PyJson5).

استخدم JSON5 لملفات الإعدادات التي يحررها البشر حيث تكون التعليقات قيمة: مثل إعدادات حاسبة الوقت (babel.config.json5)، أو بعض إعدادات أدوات البناء، أو .vscode/settings.json (الذي يستخدم JSONC، وهو تنسيق مشابه لـ JSON مع التعليقات).

التزم بـ JSON الصارم في: واجهات برمجة تطبيقات HTTP، وتبادل البيانات، وتنسيقات التخزين، وأي شيء يتم إنشاؤه تلقائياً بواسطة الآلة. خلط الاثنين يربك الأدوات البرمجية — اختر صيغة واحدة لكل ملف والتزم بها.

أخطاء تحليل JSON الأكثر شيوعاً وحلولها (مثال عند برمجة تطبيق حساب عدد الساعات والدقائق):

• (1) فاصلة زائدة بعد العنصر الأخير — `{"a":1,}` أو `[1,2,3,]` — قم بإزالة الفاصلة المعلقة.
• (2) علامات اقتباس مفردة للمفاتيح أو القيم النصية — `{'name':'Alice'}` — يجب استخدام علامات اقتباس مزدوجة.
• (3) مفاتيح غير محاطة بعلامات اقتباس — `{name:"Alice"}` — ضعها بين علامات اقتباس.
• (4) التعليقات باستخدام // أو /* */ — لا يسمح بها بروتوكول JSON الصارم؛ قم بإزالتها أو انتقل إلى JSON5/JSONC.
• (5) قيم JavaScript غير الموجودة في JSON — مثل undefined، NaN، Infinity، والدوال — استبدلها بـ null أو احذفها.
• (6) مدخلات مقتطعة — يشير المحلل عادةً إلى السطر الذي نفد فيه المحتوى المتوقع.
• (7) علامة BOM (علامة ترتيب البايت) في بداية ملف UTF-8 — ترفضها معظم المحللات؛ قم بإزالتها باستخدام `sed -i '1s/^\xEF\xBB\xBF//'`.
• (8) خلط علامات التبويب (Tabs) والمسافات لا يعطل التحليل ولكنه يفسد مقارنة الفروق (diffs) — اختر نمط مسافة بادئة واحداً.

ثلاث فئات من الثغرات الأمنية المتعلقة بـ JSON يجب على كل مطور فهمها.

• (1) تلوث البروتوتايب (Prototype pollution): دمج ملف JSON غير موثوق في كائن موجود يمكن أن يلوث Object.prototype إذا كانت المدخلات تحتوي على مفاتيح مثل __proto__ أو constructor أو prototype — مما يؤثر على كل كائن في بيئة التشغيل. استخدم Object.create(null)، أو structuredClone، أو مكتبات مثل defaultsDeep من lodash التي تحظر هذه المفاتيح صراحةً.
• (2) لا تستخدم eval() أبداً لتحليل JSON — تقوم eval بتنفيذ أي كود JavaScript، بينما تعمل JSON.parse في بيئة معزولة آمنة. لقد تم دحض أسطورة 'eval أسرع' منذ سنوات.
• (3) مشاكل إعادة التسلسل (Re-serialization): تتجاهل دالة JSON.stringify بصمت الدوال وقيم undefined و Symbol من الكائنات (وتحولها إلى null في المصفوفات). كما أنها تطلق خطأً عند وجود مراجع دائرية وقيم BigInt افتراضياً.

قم بالتحقق من صحة ملفات JSON غير الموثوقة باستخدام JSON Schema قبل معالجتها (مثلاً في تطبيقات الحاسبة العلمية أو أدوات الـ عد تنازلي)، وحدد حداً أقصى لحجم نص الطلب (body size) في واجهة برمجة التطبيقات الخاصة بك، واستخدم فحوصات Content-Type لرفض المدخلات التي ليست بتنسيق JSON مبكراً. تغطي ورقة الغش الأمني لـ REST من OWASP الصورة الكاملة.

JSON ↔ YAML هو التحويل الأكثر أماناً دون فقدان للبيانات — فكلاهما يدعم الكائنات/المصفوفات المتداخلة. احذر من التحويل التلقائي للأنواع في YAML (تتحول yes/no/on/off إلى قيم منطقية، وتظل الأرقام غير المقتبسة أرقاماً، وتتحول السلسلة النصية الحرفية 'null' إلى null) — ضع علامات اقتباس حول القيم الغامضة. الأدوات: js-yaml (npm)، PyYAML، yq.

JSON → CSV يتطلب تسوية البنية المتداخلة — وهو يعمل بشكل أفضل مع مصفوفات الكائنات المسطحة (مثل تصدير بيانات حساب ساعات العمل). اختر استراتيجية للقيم المتداخلة: stringify (كتابتها كـ JSON داخل الخلية) أو أعمدة بنمط النقطة (`address.city`، `address.zip`). الأدوات: in2csv من csvkit، و pd.json_normalize من pandas، و json2csv (npm).

JSON → XML بسيط ومباشر للهياكل الشجرية ولكنه يفقد التمييز بين المصفوفة والكائن — فقد تكون العناصر الشقيقة في XML أياً منهما. انتبه لأسماء عناصر XML غير الصالحة (لا يمكن أن تبدأ بأرقام، ولا يمكن أن تحتوي على مسافات). الأدوات: xml-js، xmltodict (Python).

بالنسبة لجميع عمليات التحويل، حدد مسبقاً ما إذا كنت تريد الحفاظ على معلومات النوع أو تسوية كل شيء إلى سلاسل نصية.

تقوم دالة JSON.parse بتحميل المستند بأكمله في الذاكرة — وهو أمر جيد لاستجابات واجهة برمجة التطبيقات النموذجية، ولكنه يمثل مشكلة للملفات التي تزيد عن بضع مئات من الميجابايت. تعالج محللات التدفق رمزاً واحداً (أو سجلاً واحداً) في كل مرة، مما يحافظ على استهلاك ثابت للذاكرة بغض النظر عن حجم الملف.

• JavaScript: استخدام stream-json أو oboe.js للتحليل بنمط SAX.
• Python: استخدام ijson للتحليل التدريجي، أو التحويل إلى أسطر JSON أولاً والقراءة سطراً بسطر.
• Java: واجهة برمجة تطبيقات Jackson Streaming (JsonParser).
• Shell: يعالج jq تدفق JSON عبر الخيار --stream.

بالنسبة للملفات التي يتم إنشاؤها كمصفوفات JSON من السجلات (مثل سجلات حساب الساعات)، فكر في تبديل المصدر ليقوم بإصدار أسطر JSON بدلاً من ذلك — ليستفيد كل مستهلك تالٍ للبيانات. عندما يتعين عليك التعامل مع مصفوفة JSON ضخمة في الذاكرة، فمن الأفضل تكرار السجلات والتخلص منها بدلاً من بناء بنية بيانات موازية. راقب حجم الذاكرة المخصصة (heap size)، واضبط --max-old-space-size في Node، وقم بتحليل الأداء قبل التحسين.

مرجع سريع لمهام JSON اليومية.

• المسافة البادئة: يعتمد prettier و npm افتراضياً مسافتين (مثال لتنسيق بيانات حساب الوقت بالدقائق)؛ اختر 4 مسافات لقواعد الأكواد البرمجية للمؤسسات التي تستخدم بالفعل مسافة بادئة مكونة من 4 مسافات عبر لغات مختلفة؛ علامات التبويب (tabs) صالحة ولكنها نادرة في JSON.
• ترتيب المفاتيح (لمقارنة فروق أنظف): استخدم JSON.stringify(obj, Object.keys(obj).sort(), 2) للكائنات السطحية؛ و jq --sort-keys للتكرار العميق؛ و Python json.dumps(obj, sort_keys=True).
• مقارنة الفروق بين ملفي JSON: قم بتشغيل jq --sort-keys على كلا الملفين، ثم قم بإجراء مقارنة الفروق العادية؛ أو استخدم json-diff (npm)، أو DeepDiff (Python)، أو أداة المقارنة المدمجة المتوافقة مع JSON في VS Code.
• تتابعات الهروب في السلاسل النصية: \\" (علامة اقتباس مزدوجة)، \\\\ (شرطة مائلة عكسية)، \\/ (شرطة مائلة للأمام، اختيارية)، \\b (مسافة للخلف)، \\f (تغذية النموذج)، \\n (سطر جديد)، \\r (إرجاع السطر)، \\t (علامة تبويب)، \\uXXXX (نقطة ترميز ينيكود).
• الأرقام: يسمح JSON بالأرقام العشرية والأسية (1.5e3) ولكن لا يسمح بالأصفار البادئة (0123 غير صالح) ولا يسمح بنقطة عشرية في النهاية (1. غير صالح).
• يجب أن تكون السلاسل النصية محاطة بعلامات اقتباس مزدوجة — علامات الاقتباس المفردة مخصصة لـ JSON5 فقط.