منسّق JSON

JSON اختصار لـ JavaScript Object Notation، وهو صيغة بيانات نصّية خفيفة لتبادل المعلومات بين الأنظمة. ابتكره Douglas Crockford في 2001، ومنذ ذلك الحين أصبح اللغة العالمية لـ APIs وإعدادات التطبيقات وقواعد بيانات NoSQL.

رغم اسمه، JSON ليس حكرًا على JavaScript. كل لغات البرمجة الحديثة (Python, Java, PHP, Go, Rust, Swift, Kotlin) تدعمه أصلاً. وحتى بعض قواعد البيانات الكلاسيكية مثل PostgreSQL و MySQL أضافت أنواع JSON كأعمدة أصلية.

JSON يتكوّن من 6 أنواع بيانات فقط:

• سلسلة نصية (string): داخل علامتي تنصيص مزدوجتين "text". لا يُقبل 'text'.
• رقم (number): صحيح أو عشري 42، 3.14، -1.2e5. لا يدعم Infinity أو NaN.
• منطقي (boolean): true أو false (حروف صغيرة فقط).
• فارغ (null): null (حروف صغيرة).
• مصفوفة (array): قائمة مرتبة بين [ ].
• كائن (object): مجموعة أزواج key:value بين { }. المفاتيح يجب أن تكون نصوصاً بين علامتَي تنصيص.

قواعد صارمة كثيراً ما يخالفها المطوّرون

• لا يُسمح بفاصلة زائدة بعد آخر عنصر في مصفوفة أو كائن (trailing comma) — على عكس JavaScript.
• لا يُسمح بالتعليقات (لا // ولا /* */) — استخدم JSON5 إذا احتجت تعليقات.
• مفاتيح الكائن يجب أن تكون نصوصاً بين علامتَي تنصيص. {name: "Ahmad"} غير صالح.
• علامتا التنصيص يجب أن تكونا مزدوجتين " لا مفردتين '.

JSON يدعم العربية وكل لغات العالم بشكل أصلي عبر UTF-8. الكتابة طبيعية:

{
  "اسم": "محمد",
  "مدينة": "الرياض",
  "هواية": "البرمجة"
}

لكن انتبه:

• احفظ ملفات JSON بترميز UTF-8 بدون BOM (Byte Order Mark). BOM يفسد الـ parsing في بعض اللغات.
• قد ترى الأحرف العربية مُرمّزة كـ \u0645\u062d\u0645\u062f — هذا تمثيل صحيح ومُكافئ لـ "محمد". أكثر برامج تحويل JSON تعيد فك التشفير.
• إذا كانت بياناتك تحتوي على رموز emoji أو علامات تشكيل عربية (فتحة، ضمة)، تأكد من استخدام مكتبة JSON parser حديثة.

JSON vs XML

• JSON أخف وزناً بنسبة 30-50% من XML لنفس البيانات (لا أقواس مغلقة).
• JSON أسرع في الـ parsing بـ 2-3 أضعاف.
• XML يدعم namespaces و schemas و attributes — قوي للمستندات المعقدة (SOAP, RSS).
• JSON يفوز في APIs الحديثة (REST, GraphQL).

JSON vs YAML

• YAML أكثر قابلية للقراءة (لا أقواس، لا فواصل).
• YAML يدعم تعليقات وعلامات تخصيص (anchors, references).
• JSON أسرع في الـ parsing.
• YAML شائع للإعدادات (Docker Compose, Kubernetes, GitHub Actions). JSON للـ APIs والتطبيقات.
• كل ملف JSON صالح هو ملف YAML صالح (YAML 1.2 superset).

التنسيق (Pretty Print)

إضافة مسافات وأسطر جديدة لجعل JSON قابلاً للقراءة البشرية. مفيد للتطوير والوثائق.

// قبل
{"name":"محمد","age":30,"skills":["JS","Go"]}

// بعد (indent: 2)
{
  "name": "محمد",
  "age": 30,
  "skills": ["JS", "Go"]
}

التصغير (Minify)

إزالة جميع المسافات والأسطر لتقليل الحجم. ضروري للإرسال عبر الشبكة.

توفير الحجم في المسار للإنتاج (production): استخدم Minify دائماً. الفرق قد يصل إلى 40% من الحجم.

أكثر APIs الحكومية والتجارية في العالم العربي تستخدم JSON. أمثلة:

• ZATCA (السعودية): فواتير إلكترونية تُرسل بـ JSON و XML.
• نفاذ (السعودية): تسجيل دخول حكومي عبر OAuth + JSON.
• أبشر: APIs للخدمات الحكومية.
• STC Pay، Apple Pay، Mada: دفعات بـ JSON Web Tokens.
• منصات التجارة الإلكترونية (Salla, Zid): APIs مفتوحة بـ REST + JSON.

قواعد ذهبية في تصميم API بـ JSON

1. استخدم snake_case أو camelCase وكن متّسقاً. الخلط بينهما كارثة للمستهلك.
2. أعد دائماً نفس البنية حتى في الأخطاء: { "success": false, "error": {...} }.
3. استخدم ISO 8601 للتواريخ: "2026-05-16T14:30:00Z" — لا تستخدم timestamp رقمي.
4. لا تُرسل null إن أمكن: اترك المفتاح أو استخدم قيمة افتراضية. null كثيراً ما يُفسد التطبيقات المستهلكة.
5. إيدِجن الأرقام الحسّاسة كنص: أرقام البطاقات، IDs الطويلة (لا فقدان دقة).
6. وثّق كل response بمثال JSON حقيقي.

JSON → CSV

مفيد لاستيراد البيانات في Excel أو Google Sheets. يعمل أفضل عندما تكون البيانات مصفوفة من كائنات بنفس البنية. مثال: مصفوفة منتجات من API → جدول Excel.

JSON → YAML

مفيد لتحويل إعدادات API لإعدادات Kubernetes أو GitHub Actions.

JSON → XML

مطلوب أحياناً للتكامل مع أنظمة قديمة (SOAP, ZATCA UBL 2.1، نظم البنوك التقليدية).

JSON → Query String

مفيد لتحويل JSON معقّد إلى رابط HTTP GET. مثال: filter[category]=tech&sort=desc.

1. فاصلة زائدة: {"a": 1,} غير صالح في JSON. صالح في JavaScript object literal فقط.
2. علامات تنصيص مفردة: {'a': 1} غير صالح.
3. NaN أو Infinity: JSON لا يدعمها. تجنّبها أو حوّلها إلى null.
4. أرقام كبيرة (BigInt): JavaScript يفقد دقة الأرقام الأكبر من 2^53. أرسلها كنصوص: "id": "1234567890123456789".
5. دورة كائن (Circular Reference): JSON.stringify(obj) يرمي خطأ إذا كان لديك كائن يشير لنفسه. استخدم مكتبة مثل flatted.
6. parsing بيانات غير موثوقة بـ eval: ثغرة أمنية خطيرة. استخدم JSON.parse دائماً.
7. عدم التحقق من نتيجة API: فحص response.ok قبل response.json().
8. تخزين كلمات سر في JSON: اعتقاد أن minify يخفيها. أي شخص يستخدم Postman يراها.

• JSON Hijacking: ثغرة قديمة. الحل: لا ترجع مصفوفة مباشرة من API، بل غلّفها بكائن: { "data": [...] }.
• JSON Injection: لا تبني JSON يدوياً بـ string concatenation. استخدم دائماً JSON.stringify() أو مكتبة موثوقة.
• Prototype Pollution: ثغرة حديثة. حدّث Node.js و libraries بانتظام، واحذر من استخدام Object.assign مع كائنات JSON من مصادر غير موثوقة.
• حجم البيانات: ضع حداً أقصى لحجم JSON في API (مثلاً 1MB). JSON parsing لـ 100MB يجمّد السيرفر.
• JSON Web Tokens (JWT): لا تخزّن أسراراً حسّاسة في الـ payload (يمكن decoding بدون مفتاح). JWT يُوقَّع فقط، لا يُشفَّر افتراضياً.

هل JSON هو نفسه JavaScript Object؟

لا. JSON نص (string). JavaScript Object كائن في الذاكرة. التحويل: JSON.parse(jsonString) ينتج كائن، JSON.stringify(obj) ينتج نص JSON.

كيف أكتب تعليقات في JSON؟

لا يمكن في JSON القياسي. الحلول: (1) استخدم JSON5 الذي يدعم تعليقات، (2) أضف حقل _comment بدلاً من تعليق فعلي.

هل JSON حسّاس لحالة الأحرف؟

نعم. True غير صالح، true صالح. أسماء المفاتيح حسّاسة أيضاً: {"Name"} و {"name"} مفتاحان مختلفان.

ما الحجم الأقصى لملف JSON؟

المعيار نفسه لا يحدّد حجماً. لكن المتصفحات والـ APIs عادةً تحدّ بـ 1-10MB. للبيانات الكبيرة، استخدم NDJSON (سطر JSON لكل entry) أو streaming.

هل يدعم JSON تواريخ؟

لا، رسمياً. اتفاقياً، تُكتب التواريخ كنصوص بصيغة ISO 8601: "2026-05-16T14:30:00Z". JSON.stringify(new Date()) يفعل هذا تلقائياً.

JSON أم JSONC أم JSON5؟

JSON: المعيار الرسمي، الأكثر دعماً. JSONC: JSON + تعليقات (يستخدمه VS Code). JSON5: JSON + تعليقات + trailing commas + مفاتيح بلا تنصيص. للنقل عبر الشبكة استخدم JSON. للإعدادات الداخلية يجوز JSONC.

هل أحتاج إنترنت لمنسّق JSON؟

أداتنا تعمل 100% محلياً في المتصفح — بياناتك لا تُرسل لأي خادم. تستخدم JSON.parse الأصلي في المتصفح. هذا مهم جداً عند معالجة بيانات حسّاسة (أرقام عملاء، فواتير، أسرار API).

JSON ليس مجرد تنسيق نصّي — هو لغة التبادل العالمية للويب الحديث. إتقانه أساسي لأي مطور. القواعد الذهبية:

1. لا تكتب JSON يدوياً — استخدم دائماً JSON.stringify().
2. تحقق من صحة JSON قبل الإرسال (parse → re-stringify).
3. استخدم UTF-8 بدون BOM للملفات.
4. للإنتاج: استخدم Minify. للتطوير: استخدم Pretty Print.
5. للأرقام الكبيرة (IDs): أرسلها كنصوص.
6. للتواريخ: ISO 8601 دائماً.

استخدم منسّق JSON أعلى الصفحة لتنسيق وتحقق وتحويل JSON الخاص بك. تعمل الأداة محلياً 100%.