ملف JSON: البنية والاستخدامات والأمثلة

# ملف JSON: دليل شامل

فهم بنية ملفات JSON، الامتدادات، والاستخدامات العملية.

ما هو ملف JSON؟

التعريف

ملف JSON هو:

• 📄 ملف نصي بسيط
• 🔤 يستخدم امتداد .json
• 📊 يحتوي على بيانات منظمة
• 🌐 قابل للقراءة من قبل البشر والآلات

البنية الأساسية

{
  "key": "value"
}

بنية الملف

1. العنصر الجذري

يجب أن يكون الجذر إما:

• كائن {}
• مصفوفة []

كائن جذري:

{
  "name": "أحمد",
  "age": 30
}

مصفوفة جذرية:

[
  {
    "id": 1,
    "name": "محمد"
  },
  {
    "id": 2,
    "name": "فاطمة"
  }
]

2. الكائنات المتداخلة

{
  "user": {
    "name": "سارة",
    "contact": {
      "email": "sara@example.com",
      "phone": "+966-XXX-XXXX"
    }
  }
}

3. المصفوفات المتداخلة

{
  "company": "شركة التقنية",
  "departments": [
    {
      "name": "التطوير",
      "employees": [
        {"id": 1, "name": "أحمد"},
        {"id": 2, "name": "محمد"}
      ]
    }
  ]
}

أنواع ملفات JSON

1. ملفات البيانات

users.json:

{
  "users": [
    {
      "id": 1,
      "name": "أحمد محمد",
      "email": "ahmad@example.com",
      "role": "admin"
    },
    {
      "id": 2,
      "name": "فاطمة علي",
      "email": "fatima@example.com",
      "role": "user"
    }
  ]
}

2. ملفات التكوين

config.json:

{
  "app": {
    "name": "تطبيقي",
    "version": "1.0.0",
    "port": 3000,
    "environment": "production"
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "mydb"
  },
  "features": {
    "authentication": true,
    "logging": true,
    "caching": false
  }
}

3. ملفات الترجمة (i18n)

ar.json:

{
  "common": {
    "welcome": "مرحباً",
    "goodbye": "وداعاً",
    "thanks": "شكراً"
  },
  "errors": {
    "notFound": "الصفحة غير موجودة",
    "serverError": "خطأ في الخادم"
  }
}

4. package.json (Node.js)

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "مشروعي",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "test": "jest"
  },
  "dependencies": {
    "express": "^4.18.0",
    "mongoose": "^7.0.0"
  }
}

البنية المفصلة

الترويسة والبيانات الوصفية

{
  "version": "1.0",
  "timestamp": "2026-01-16T10:00:00Z",
  "author": "أحمد محمد",
  "data": {
    // البيانات الفعلية هنا
  }
}

التقسيم المنطقي

{
  "metadata": {
    "version": "1.0",
    "createdAt": "2026-01-16"
  },
  "users": [],
  "products": [],
  "settings": {}
}

أفضل الممارسات

1. التسمية

✅ جيد:

{
  "firstName": "أحمد",
  "lastName": "محمد",
  "emailAddress": "ahmad@example.com"
}

❌ سيء:

{
  "FiRsTnAmE": "أحمد",
  "last_name": "محمد",
  "EMail": "ahmad@example.com"
}

2. البنية

✅ جيد:

{
  "user": {
    "personal": {
      "name": "أحمد",
      "age": 30
    },
    "contact": {
      "email": "ahmad@example.com"
    }
  }
}

❌ سيء:

{
  "userName": "أحمد",
  "userAge": 30,
  "userEmail": "ahmad@example.com"
}

3. التنسيق

✅ منسق:

{
  "name": "أحمد",
  "age": 30,
  "city": "دبي"
}

❌ غير منسق:

{"name":"أحمد","age":30,"city":"دبي"}

أمثلة عملية

1. قائمة المنتجات

products.json:

{
  "products": [
    {
      "id": "prod-001",
      "name": "حاسوب محمول",
      "price": 1200.00,
      "currency": "USD",
      "inStock": true,
      "categories": ["إلكترونيات", "حواسيب"],
      "specs": {
        "ram": "16GB",
        "storage": "512GB SSD",
        "processor": "Intel i7"
      }
    },
    {
      "id": "prod-002",
      "name": "هاتف ذكي",
      "price": 800.00,
      "currency": "USD",
      "inStock": false,
      "categories": ["إلكترونيات", "هواتف"],
      "specs": {
        "ram": "8GB",
        "storage": "256GB",
        "screen": "6.5 inch"
      }
    }
  ]
}

2. استجابة API

api-response.json:

{
  "status": "success",
  "code": 200,
  "message": "تم جلب البيانات بنجاح",
  "data": {
    "users": [
      {
        "id": 1,
        "name": "أحمد",
        "isActive": true
      }
    ],
    "pagination": {
      "page": 1,
      "perPage": 10,
      "total": 50,
      "pages": 5
    }
  },
  "timestamp": "2026-01-16T10:00:00Z"
}

3. قائمة المهام

todos.json:

{
  "todos": [
    {
      "id": 1,
      "title": "مراجعة الكود",
      "description": "مراجعة pull requests",
      "completed": false,
      "priority": "high",
      "dueDate": "2026-01-17",
      "tags": ["code-review", "urgent"]
    },
    {
      "id": 2,
      "title": "كتابة الوثائق",
      "description": "توثيق الميزات الجديدة",
      "completed": true,
      "priority": "medium",
      "dueDate": "2026-01-16",
      "tags": ["documentation"]
    }
  ]
}

القراءة والكتابة

JavaScript

القراءة:

// قراءة ملف JSON في Node.js
const fs = require('fs');

const data = JSON.parse(
  fs.readFileSync('data.json', 'utf8')
);

console.log(data.name);

الكتابة:

const data = {
  name: "أحمد",
  age: 30
};

fs.writeFileSync(
  'output.json',
  JSON.stringify(data, null, 2),
  'utf8'
);

Python

القراءة:

import json

with open('data.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

print(data['name'])

الكتابة:

data = {
    "name": "أحمد",
    "age": 30
}

with open('output.json', 'w', encoding='utf-8') as f:
    json.dump(data, f, ensure_ascii=False, indent=2)

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

استخدام JSON Schema

schema.json:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "User",
  "type": "object",
  "required": ["name", "email"],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 2
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "number",
      "minimum": 0,
      "maximum": 150
    }
  }
}

التحقق:

const Ajv = require('ajv');
const ajv = new Ajv();

const schema = require('./schema.json');
const validate = ajv.compile(schema);

const data = {
  name: "أحمد",
  email: "ahmad@example.com",
  age: 30
};

const valid = validate(data);
if (!valid) {
  console.log(validate.errors);
}

الأخطاء الشائعة

1. فاصلة في النهاية

❌ خطأ:

{
  "name": "أحمد",
  "age": 30,
}

✅ صحيح:

{
  "name": "أحمد",
  "age": 30
}

2. التعليقات

❌ غير مسموح:

{
  // هذا تعليق
  "name": "أحمد"
}

3. مفاتيح بدون علامات اقتباس

❌ خطأ:

{
  name: "أحمد"
}

✅ صحيح:

{
  "name": "أحمد"
}

التحسينات

1. ضغط الملفات

قبل الضغط (102 بايت):

{
  "name": "أحمد",
  "age": 30,
  "city": "دبي"
}

بعد الضغط (46 بايت):

{"name":"أحمد","age":30,"city":"دبي"}

2. GZIP

# ضغط
gzip data.json

# فك الضغط
gunzip data.json.gz

3. تقليل الحجم

قبل:

{
  "userName": "أحمد محمد",
  "userEmail": "ahmad@example.com",
  "userAge": 30
}

بعد:

{
  "u": {
    "n": "أحمد محمد",
    "e": "ahmad@example.com",
    "a": 30
  }
}

الأدوات

1. المحققون

• JSONLint
• BigJSON.online
• JSON Formatter

2. المحولون

• XML إلى JSON
• CSV إلى JSON
• YAML إلى JSON

3. المحررون

• VS Code
• Sublime Text
• Atom

الخلاصة

النقاط الرئيسية

✅ ملفات JSON هي ملفات نصية بامتداد .json

✅ يجب أن يكون الجذر كائن أو مصفوفة

✅ اتباع قواعد البنية الصارمة

✅ استخدام تسمية متسقة

✅ التحقق من الصحة قبل الاستخدام

أفضل الممارسات

• 📝 استخدام تنسيق واضح
• ✅ التحقق من الصحة بانتظام
• 🗂️ تنظيم البنية منطقياً
• 📚 توثيق المخطط
• 🔒 تأمين البيانات الحساسة

ملفات JSON هي أساس تبادل البيانات الحديث!