JSON Schema Validator

ما هو JSON Schema ولماذا هو مهم؟

JSON (JavaScript Object Notation) هي اللغة المشتركة لواجهات برمجة التطبيقات على الويب وملفات الإعداد وتبادل البيانات. لكن JSON الخام لا يمتلك نظام نوع مدمج — يمكن أن يكون الحقل سلسلة نصية في يوم ورقماً في اليوم التالي، والطريقة الوحيدة لاكتشاف التناقض هي خطأ في وقت التشغيل أو خلل بيانات خفي. يملأ JSON Schema هذه الفجوة: فهو مفردات تصريحية لوصف البنية المتوقعة والقيود الخاصة بمستند JSON، ويتم التحقق منها مقابل البيانات الفعلية في وقت التشغيل.

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

إصدارات مسودة JSON Schema: Draft-07 وDraft 2019-09 وDraft 2020-12

مرّ JSON Schema بعدة مسودات مواصفات. يظل Draft-07، الصادر عام 2018، الأكثر دعماً عبر جميع مكتبات المدققين الرئيسية وهو اللهجة المستخدمة من قِبل OpenAPI 3.0. قدّم كلمات المفاتيح القوية للتحقق الشرطي if/then/else وتعليقات الخصائص readOnly/writeOnly وكلمات مفاتيح ترميز المحتوى. إذا كنت تكتب مخططات اليوم ولا تحتاج إلى أحدث الميزات، فإن Draft-07 هو الخيار الأكثر أماناً لتحقيق أقصى توافق مع النظام البيئي.

Draft 2020-12 هو المواصفة المستقرة الحالية ويُقدم عدة تغييرات مهمة: تم استبدال كلمة المفتاح items بـ prefixItems للتحقق من المجموعات المرتبة، وتستخدم المراجع الديناميكية $dynamicRef بدلاً من $recursiveRef، وتوفر كلمات المفاتيح الجديدة unevaluatedProperties وunevaluatedItems تحكماً أكثر دقة في المحتوى الإضافي.

شرح كلمات المفاتيح الأساسية في JSON Schema

تفرض كلمة المفتاح type نوع بيانات: string أو number أو integer أو boolean أو array أو object أو null. تُدرج required الخصائص التي يجب أن تكون موجودة في كائن. تُعيّن properties كل اسم خاصية إلى مخططها الفرعي الخاص. يطبق pattern تعبيراً منتظماً على قيمة سلسلة. تُقيد minimum وmaximum وminLength وmaxLength النطاقات العددية ونطاقات السلاسل. تقيد enum قيمة بمجموعة ثابتة من القيم المسموح بها؛ تقيدها const بقيمة واحدة.

تتيح لك كلمات مفاتيح التركيب بناء قواعد معقدة من وحدات بناء بسيطة: تعمل allOf كـ AND منطقي، وanyOf كـ OR، وoneOf كـ XOR. تعكس كلمة المفتاح not مخططاً. تتيح كلمات المفاتيح if/then/else التحقق الشرطي. يمكنك معاً التعبير عن أي قاعدة تحقق تقريباً دون كتابة كود أمري مخصص.

JSON Schema في بيئة الإنتاج: عقود API وخطوط أنابيب CI

في أنظمة الإنتاج، يعمل التحقق من JSON Schema على جانب الخادم أو في خطوط أنابيب CI باستخدام مكتبات مثل Ajv (JavaScript/Node.js) أو jsonschema (Python) أو Newtonsoft.Json (C#). تُودَع المخططات في التحكم بالإصدارات جنباً إلى جنب مع كود التطبيق حتى تتم مراجعة تغييرات العقد وتتبعها مثل أي تغيير آخر.

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

مثال عملي: التحقق من استجابة API

لنفترض أن واجهة برمجة التطبيقات الخاصة بك ترجع كائن مستخدم. قد يتطلب JSON Schema الذي يتحقق منه معرفاً صحيحاً، واسماً نصياً غير فارغ، وبريداً إلكترونياً مطابقاً لنمط البريد الإلكتروني، ودوراً نصياً اختيارياً من تعداد 'admin' و'editor' و'viewer'. يضمن ضبط additionalProperties على false أن واجهة برمجة التطبيقات لا تُرجع أبداً حقولاً غير موثقة بصمت.

تتيح ميزة if/then/else قواعد شرطية — مثلاً، إذا كان الدور 'admin' فمصفوفة الأذونات مطلوبة، وإلا فهي محظورة. تتيح هذه القواعد التركيبية لمخطط واحد تغطية أشكال صالحة متعددة لكائن دون تكرار تعريفات الخصائص.

كيف يقارن UtiloKit بمدققات JSON Schema الأخرى

تقع معظم أدوات التحقق من JSON Schema عبر الإنترنت في فئتين: منشئو المخططات المرئية ومدققو API من جانب الخادم. يجبرك jsonschema.net على المرور بواجهة نقر بصري لإنشاء المخططات — مفيد للمبتدئين لتعلم بنية المخطط، لكنه بطيء للمطورين الذين يعرفون بالفعل الكلمات المفتاحية التي يحتاجونها.

يُبلّغ jsonschemavalidator.net، المبني على مكتبة Newtonsoft.Json من Microsoft، عن الأخطاء باستخدام مسارات خصائص .NET ورموز أخطاء تبدو غير مألوفة لمطوري JavaScript. أدوات مثل Stoplight وSwaggerHub تتحقق من المخططات كجزء من مستند OpenAPI كامل وتتطلب إعداد مشروع وحساباً.

يعمل مدقق UtiloKit على نفس محرك Ajv الذي يدعم معظم تطبيقات Node.js وExpress وFastify. تتطابق رسائل الخطأ ومسارات مؤشر JSON وسلوك الكلمات المفتاحية تماماً مع بيئة الإنتاج الخاصة بك — ويعمل مجاناً في متصفحك بدون حساب أو رفع ملفات أو حد لحجم الملف أو حد استخدام يومي.