كيفية التحقق من JSON: دليل كامل مع أمثلة

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

لماذا التحقق من JSON مهم

JSON غير الصالح هو أحد أكثر مصادر الأخطاء شيوعًا في تطبيقات الويب. فاصلة في غير محلها أو مفتاح غير مقتبس أو فاصلة trailing يمكن أن تتسبب في رمي JSON.parse() لـ SyntaxError، مما يعطل خط أنابيب البيانات بالكامل. يلتقط التحقق هذه الأخطاء قبل أن تنتشر عبر النظام وتسبب أعطالاً.

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

قواعد JSON النحوية

قبل الغوص في أدوات التحقق، فهم القواعد التي تجعل JSON صالحًا أمر بالغ الأهمية. JSON له صيغة صارمة محددة بواسطة RFC 8259، وحتى مخالفة حرف واحد تجعل المستند بأكمله غير صالح.

يجب استخدام علامات الاقتباس المزدوجة للسلاسل

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

// Invalid - single quotes
{'name': 'Alice', 'age': 30}

// Valid - double quotes
{"name": "Alice", "age": 30}

يجب وضع علامات اقتباس حول مفاتيح الكائنات

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

// Invalid - unquoted keys
{name: "Alice", age: 30}

// Valid - quoted keys
{"name": "Alice", "age": 30}

الفاصلة trailing ممنوعة

لا يسمح JSON بفاصلة بعد آخر عنصر في كائن أو مصفوفة. هذا خطأ شائع آخر، خاصة عند تحرير JSON يدويًا.

// Invalid - trailing comma
{
  "name": "Alice",
  "age": 30,
}

// Valid - no trailing comma
{
  "name": "Alice",
  "age": 30
}

التعليقات غير مدعومة

لا يدعم JSON التعليقات. تعليقات // ذات السطر الواحد وتعليقات /* */ متعددة الأسطر غير صالحة في JSON. إذا كنت بحاجة إلى توثيق، استخدم ملفات منفصلة أو تنسيقات مثل JSONC.

أخطاء التحقق من JSON الشائعة

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

• رمز غير متوقع: عادة ما يحدث بسبب علامات الاقتباس المفردة أو المفاتيح غير المقتبسة أو الفواصل trailing. تتضمن رسالة الخطأ الموقع الذي فشل فيه التحليل.
• نهاية غير متوقعة لمدخل JSON: سلسلة JSON غير مكتملة أو فارغة. يحدث هذا غالبًا عندما ترجع طلبات الشبكة استجابة فارغة.
• حرف غير أبيض غير متوقع: محتوى إضافي بعد قيمة JSON الرئيسية، مثل كائن ثانٍ غير مغلف في مصفوفة.
• رقم غير صالح: الأرقام ذات الأصفار البادئة (باستثناء 0 نفسه) أو الترميز الست عشري أو قيم NaN / Infinity ليست JSON صالحًا.

التحقق من JSON في JavaScript

أبسط طريقة للتحقق من JSON في JavaScript هي تغليف JSON.parse() في كتلة try-catch. إذا كان JSON غير صالح، ترمي الدالة SyntaxError.

function validateJSON(jsonString) {
  try {
    JSON.parse(jsonString);
    return { valid: true };
  } catch (error) {
    return {
      valid: false,
      error: error.message
    };
  }
}

const result = validateJSON('{"name": "Alice"}');
console.log(result);
// { valid: true }

const badResult = validateJSON("{'name': 'Alice'}");
console.log(badResult);
// { valid: false, error: "Unexpected token '..." }

التحقق من JSON في Python

توفر Python وحدة json التي تتضمن json.loads() لتحليل سلاسل JSON. مثل JavaScript، يثير JSON غير الصالح استثناء json.JSONDecodeError مع معلومات موقع مفصلة.

import json

def validate_json(json_string):
    try:
        json.loads(json_string)
        return {"valid": True}
    except json.JSONDecodeError as e:
        return {
            "valid": False,
            "error": str(e),
            "line": e.lineno,
            "column": e.colno
        }

result = validate_json('{"name": "Alice"}')
print(result)
# {'valid': True}

التحقق من JSON Schema

التحقق النحوي يخبرك فقط إذا كان JSON منسقًا جيدًا. JSON Schema يتيح لك تعريف الهيكل المتوقع والتحقق من البيانات مقابله. يحدد Schema الحقول المطلوبة وأنواع البيانات ونطاقات القيم وأنماط السلاسل وهياكل الكائنات المتداخلة.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "email"],
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0 }
  }
}

تشمل مدققات JSON Schema الشائعة Ajv لـ JavaScript و jsonschema لـ Python و json-schema-validator لـ Java. تتحقق هذه المكتبات من بيانات JSON مقابل Schema الخاص بك وتولد رسائل خطأ مفصلة لكل مخالفة.

أدوات التحقق من JSON عبر الإنترنت

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

أفضل ممارسات التحقق من JSON

• تحقق مبكرًا: افحص JSON عند حدود النظام (مثل نقاط نهاية API ودوال استيراد الملفات)، قبل أن تدخل البيانات إلى منطق الأعمال.
• استخدم التحقق من Schema: بالإضافة إلى الصيغة، استخدم JSON Schema للتحقق من بنية البيانات لالتقاط الحقول المفقودة والأنواع الخاطئة والقيم خارج النطاق.
• قدم رسائل خطأ واضحة: عندما يفشل التحقق، ضمن مسار الحقل والنوع المتوقع والقيمة الفعلية لمساعدة المستخدمين في إصلاح المشكلات بسرعة.
• تحقق من جانب العميل والخادم: يوفر التحقق من جانب العميل تغذية راجعة فورية، بينما يضمن التحقق من جانب الخادم الأمان وسلامة البيانات.
• أتمتة التحقق في CI/CD: استخدم أدوات مثل ajv-cli أو jsonschema للتحقق من ملفات JSON الثابتة وملفات التكوين في أنابيب البناء.
• سجل أخطاء التحقق: سجل حالات فشل التحقق مع السياق لتحديد الأنماط وإصلاح الأسباب الجذرية في منتجي البيانات.