أفضل ممارسات تنسيق JSON يجب أن يعرفها كل مطور

أساسيات بنية JSON

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

أنواع القيم الست في JSON هي: نص، رقم، قيمة منطقية (true/false)، null، كائن، ومصفوفة. يجب أن يكون كل مفتاح في كائن JSON نصاً محاطاً بعلامات اقتباس مزدوجة — لا مفردة، ولا معرّفات غير محاطة بعلامات اقتباس.

أخطاء التركيب الشائعة

JSON صارم. خطأ تركيبي واحد يجعل المستند بأكمله غير قابل للتحليل. أكثر الأخطاء شيوعاً هي:

• الفواصل الزائدة: {"name": "Alice",} — الفاصلة الزائدة بعد العنصر الأخير غير مشروعة في JSON (إنها صحيحة في JavaScript مما يسبب ارتباكاً).
• النصوص بعلامات اقتباس مفردة: يتطلب JSON علامات اقتباس مزدوجة. {'key': 'value'} ليس JSON صحيحاً.
• المفاتيح غير المحاطة بعلامات اقتباس: {name: "Alice"} هو بناء جملة لكائن JavaScript، لا JSON.
• التعليقات: لا يدعم JSON التعليقات. إذا احتجت إلى تعليقات في ملف إعداد، فكّر في JSONC أو YAML عوضاً عنه.
• Undefined وNaN: هذه القيم الخاصة بـJavaScript غير موجودة في JSON. استخدم null أو احذف الحقل.
• أحرف التحكم غير المُهرَّبة: يجب كتابة أسطر جديدة داخل النصوص كـ\n، وليس كفواصل سطرية حرفية.

التنسيق لسهولة القراءة

JSON المُرسَل عبر الشبكة غالباً ما يكون مضغوطاً — بدون مسافات — لتقليل حجم الحمولة. لكن JSON المخزَّن في ملفات الإعداد أو المُلتزَم به في نظام التحكم في الإصدارات يجب تنسيقه لسهولة القراءة البشرية. الاتفاقيات القياسية هي:

• مسافتان أو أربع مسافات لكل مستوى تداخل (اختر واحدة وكن متسقاً)
• زوج مفتاح-قيمة واحد في كل سطر للكائنات
• قوس الفتح في نفس سطر المفتاح الأب، قوس الإغلاق في سطره الخاص
• مصفوفات القيم البسيطة يمكن كتابتها في سطر واحد إذا كانت قصيرة

يمكن لمعظم المحررات تنسيق JSON تلقائياً. في VS Code، انقر بزر الماوس الأيمن واختر "Format Document"، أو استخدم الاختصار Shift+Alt+F. يمكن لمستخدمي سطر الأوامر استخدام jq . input.json لطباعة أي ملف JSON بتنسيق جميل.

اتفاقيات التسمية

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

• camelCase (firstName) — قياسي في واجهات JavaScript البرمجية ومعظم خدمات REST
• snake_case (first_name) — شائع في واجهات Python البرمجية وPostgreSQL
• PascalCase (FirstName) — يُستخدم في بعض بيئات .NET وC#

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

التعامل مع null مقابل الحقول المفقودة

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

الأعداد الكبيرة والدقة

أعداد JSON لا حدّ محدداً لحجمها، لكن كثيراً من المحللين يحوّلونها كقيم نقطة عائمة مزدوجة الدقة IEEE 754. هذا يعني أن الأعداد الصحيحة الأكبر من 2^53 لا يمكن تمثيلها بدقة. إذا كان JSON الخاص بك يحمل أعداداً صحيحة كبيرة (معرّفات قواعد البيانات أو مبالغ مالية بوحدات العملة الصغرى أو معرّفات تشفيرية)، مثّلها كـنصوص ووثّق ذلك في واجهتك البرمجية. هذه مشكلة معروفة في معرّفات التغريدات في تويتر على سبيل المثال.

التحقق من صحة JSON

ما وراء التحقق من التركيب (هل هذا JSON صحيح؟)، يتيح لك JSON Schema تعريف الشكل المتوقع للمستند: الحقول المطلوبة وأنواعها ونطاقات قيمها وأكثر. أدوات كـajv (JavaScript) وjsonschema (Python) والمحققات الإلكترونية يمكنها التحقق من مستند JSON مقابل مخطط. لأي واجهة برمجية تنشرها أو تستهلكها في سياق إنتاجي، يستحق التحقق بـJSON Schema التطبيق عند الحدود.

منسّق ومحقق JSON — كالمتوفر على TheDailyUtils — هو أسرع طريقة للكشف عن أخطاء التركيب في حمولة غير مألوفة. الصق JSON الخام، وستعرف فوراً ما إذا كان يُحلَّل وأين توجد أي أخطاء.

نسّق JSON والتحقق منه فوراً

افتح منسّق JSON المجاني — الصق أي JSON لطباعته بتنسيق جميل أو ضغطه أو الكشف عن أخطاء التركيب في ثوانٍ. يعمل في متصفحك؛ بياناتك تبقى خاصة.