JSON Schema هي طريقة لوصف الشكل الذي يجب أن تكون عليه بنية مستند JSON، باستخدام مستند JSON آخر. بدلاً من التحقق من البيانات يدويًا بشروط في الكود، يمكنك وصف الأنواع المتوقعة والحقول الإلزامية وقيود القيم بشكل تصريحي، ثم التحقق من البيانات تلقائيًا.
الكلمات المفتاحية الأساسية في draft-07
type— نوع القيمة المتوقع (object، string، number، array، إلخ).required— قائمة حقول الكائن التي يجب أن تكون موجودة إلزاميًا.properties— وصف المخطط لكل حقل من حقول الكائن على حدة.enum— تقييد القيمة بمجموعة محددة من الخيارات.pattern— التحقق من نص باستخدام تعبير نمطي، مثلاً للتحقق من صيغة رقم الهاتف.
مثال: pattern لرقم هاتف يخدم عدة دول عربية
واجهة برمجية واحدة تخدم مستخدمين في مصر (+20) والسعودية (+966) والإمارات (+971) لا يمكنها الاعتماد على نمط رقم هاتف واحد بسيط. مخطط واقعي لحقل الهاتف يحتاج إلى تناوب صريح بين الصيغ: "phone": {"type": "string", "pattern": "^\\+(20|966|971)\\d{8,9}$"} — وهذا مجرد مثال مبسّط، إذ يختلف طول الرقم فعليًا حسب الدولة ونوع الخط. كتابة مخطط يفترض رمز دولة واحدًا فقط (كما يحدث غالبًا عند نسخ نمط أمريكي جاهز) يرفض بصمت كل رقم هاتف عربي حقيقي آخر.
كيف يختلف هذا عن التحقق من الصياغة
يتحقق التحقق العادي من JSON فقط من أن النص صحيح نحويًا — الأقواس وعلامات الاقتباس والفواصل في مكانها الصحيح. أما JSON Schema فيتحقق من أكثر من ذلك بكثير: هل يملك الكائن حقلاً إلزاميًا email، وهل قيمة age رقم لا نص، وهل status ضمن قائمة القيم المسموح بها.
لماذا نحتاج ذلك
- التحقق من أن استجابة API طرف ثالث تطابق العقد الموثّق.
- التحقق من ملفات الإعداد قبل النشر لاكتشاف خطأ مبكرًا.
- توثيق بنية البيانات المتوقعة بصيغة يمكن التحقق منها تلقائيًا فورًا.
additionalProperties: هل يمكن إضافة حقول زائدة
افتراضيًا، تسمح JSON Schema بأي حقول في الكائن تتجاوز ما وُصف في properties — فـrequired وproperties يحددان الحد الأدنى فقط، لا قائمة حصرية. إذا احتجت منع الحقول غير المعروفة، يجب إضافة "additionalProperties": false صراحة — فبدون هذا القيد يبقى المخطط «مفتوحًا».