فهم JSON Schema: تحقق من بياناتك كالمحترفين

هل سبق أن واجهت خطأ حيث أعادت واجهة API الخاصة بك "42" (نص) بدلاً من 42 (رقم) وانهار كل شيء بعدها؟ أو أرسل شخص ما طلبًا بدون حقل مطلوب وتعطل تطبيقك بدلاً من إرجاع رسالة خطأ مفيدة؟ JSON Schema موجود تحديدًا لمنع هذا النوع من المشاكل.

فكّر فيه كمخطط لبيانات JSON الخاصة بك — يصف الشكل الذي يجب أن تكون عليه البيانات ويلتقط أي شيء لا يتطابق.

كيف يبدو JSON Schema

JSON Schema مكتوب بلغة JSON نفسها (ميتا، أليس كذلك؟). إليك مخططًا بسيطًا لكائن مستخدم:

هذا يقول: "أتوقع كائنًا يحتوي على name مطلوب (نص غير فارغ) وemail (تنسيق بريد إلكتروني صالح)، بالإضافة إلى age اختياري (عدد صحيح بين 0 و150)." إذا أرسل شخص ما {"name": "", "email": "not-an-email"}، سيكتشف المدقق كلتا المشكلتين.

بناء المخططات خطوة بخطوة

ابدأ بالنوع. كل مخطط يبدأ بـ "type": object، array، string، number، integer، boolean أو null.

أضف القيود. للنصوص: minLength، maxLength، pattern (تعبير نمطي). للأرقام: minimum، maximum، multipleOf. للمصفوفات: minItems، maxItems، uniqueItems. دليل JSON Schema الرسمي يحتوي على القائمة الكاملة.

حدد الحقول المطلوبة. استخدم مصفوفة "required" على مستوى الكائن. اذكر فقط الحقول التي يجب أن تكون موجودة — لا تجعل كل شيء مطلوبًا إلا إذا كنت تعني ذلك فعلاً.

عرّف الكائنات المتداخلة. ما عليك سوى وضع تعريفات المخطط داخل "properties". إليك مستخدمًا بعنوان:

ذلك pattern على الرمز البريدي؟ يضمن قبول الرموز البريدية الأمريكية المكونة من 5 أرقام فقط. التحقق الواقعي مثل هذا يمنع البيانات الفاسدة من التسلل إلى قاعدة بياناتك.

لماذا يجب أن تستخدمه فعلاً

التحقق من API: تحقق من أجسام الطلبات الواردة عند حافة API. البيانات السيئة تُرفض برسائل خطأ واضحة قبل أن تلمس منطق عملك. معظم الأطر تدعم هذا — Ajv لجافاسكربت سريع للغاية.

التحقق من التكوين: تحقق من ملفات التكوين عند بدء تشغيل التطبيق. افشل بسرعة برسالة واضحة "تكوينك يفتقد حقل database.host" بدلاً من استثناء مشفر لمؤشر فارغ بعد 5 دقائق.

التوثيق: JSON Schema يعمل كتوثيق حي. أدوات مثل Swagger UI تولّد وثائق API مباشرة من المخططات.

توليد الكود: ولّد واجهات TypeScript، أو هياكل Go، أو فئات بيانات Python من مخططك. اكتبه مرة واحدة، واستخدمه في كل مكان.

الاختبار: تحقق من استجابات API في مجموعة اختباراتك لاكتشاف التراجعات تلقائيًا.

ابدأ في 30 ثانية

أسرع طريقة للبدء؟ ولّد مخططًا من بيانات JSON موجودة. الصق استجابة JSON نموذجية في مولّد JSON Schema الخاص بنا — سيحلل البيانات وينتج مخططًا يمكنك تحسينه. ثم استخدم مدقق JSON Schema الخاص بنا لاختباره مقابل بيانات حقيقية.

يمكنك أيضًا التحقق برمجيًا. إليك مثالًا سريعًا في Node.js مع Ajv:

لبايثون، اطلع على مكتبة jsonschema. لجافا، هناك everit-json-schema. تقريبًا كل لغة برمجة لديها دعم قوي — اطلع على القائمة الكاملة للتطبيقات.

ميزات المخطط المتقدمة التي يجب أن تعرفها

بمجرد إتقان الأساسيات، يحتوي JSON Schema على ميزات قوية تجعل التحقق المعقد ممكنًا.

oneOf، anyOf، allOf — دمج المخططات:

أحيانًا يمكن أن يكون الحقل أحد عدة أنواع. مثلاً، قد تقبل واجهة API معرفًا نصيًا أو معرفًا رقميًا:

هذا المخطط يقبل كلاً من {"id": "PRD-1234"} و{"id": 42} لكنه يرفض {"id": -1} أو {"id": "invalid"}.

$ref — تعريفات مخطط قابلة لإعادة الاستخدام:

مع نمو مخططاتك، ستريد تجنب تكرار نفس التعريفات. الكلمة المفتاحية $ref تتيح لك الإشارة إلى تعريفات مشتركة:

الآن كلا billing_address وshipping_address يستخدمان نفس قواعد التحقق بالضبط. غيّر تعريف address مرة واحدة، ويتحدث كلا الحقلين. هذا ضروري للحفاظ على المخططات الكبيرة قابلة للصيانة.

additionalProperties — أقفل كائناتك:

بشكل افتراضي، يسمح JSON Schema بخصائص إضافية غير مدرجة في properties. هذا غالبًا ليس ما تريده — الحقول غير المتوقعة قد تشير إلى خطأ في العميل أو عدم تطابق في الإصدار. عيّن "additionalProperties": false لرفض الحقول غير المعروفة:

مع هذا المخطط، سيتم رفض {"name": "Alice", "email": "[email protected]", "admin": true} لأن admin ليست خاصية معرّفة.

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

حتى المطورون ذوو الخبرة يرتكبون هذه الأخطاء عند كتابة المخططات:

1. نسيان أن required على مستوى الكائن، وليس على مستوى الخاصية. هذا خطأ:

الطريقة الصحيحة هي:

2. استخدام "type": "number" عندما تقصد "type": "integer". النوع number يقبل الكسور العشرية مثل 3.14، بينما integer يقبل الأعداد الصحيحة فقط. إذا كان حقلك عدادًا أو معرفًا، استخدم integer.

3. عدم تحديد format للأنماط الشائعة. JSON Schema يحتوي على مدققات تنسيق مدمجة لـ email، uri، date-time، ipv4، ipv6، uuid والمزيد. استخدمها بدلاً من كتابة أنماط regex معقدة.

4. جعل كل شيء مطلوبًا. حدد الحقول كمطلوبة فقط إذا كانت يجب أن تكون موجودة فعلاً. تقييد مخططك بشكل مفرط يجعل تطور API أصعب — إضافة حقل اختياري جديد هو تغيير غير مُعطِّل، لكنك تفقد هذه المرونة إذا كان كل شيء مطلوبًا.

مثال واقعي: مخطط منتج التجارة الإلكترونية

لنلقِ نظرة على مخطط عملي قد تستخدمه لواجهة API للمنتجات:

هذا المخطط يفرض أن يكون لكل منتج اسم (1-200 حرف)، وسعر إيجابي، وفئة من قائمة ثابتة. العلامات اختيارية لكن يجب أن تكون نصوصًا فريدة بحد أقصى 10. الكلمة المفتاحية enum مفيدة للغاية للحقول التي يجب أن تقبل قيمًا محددة فقط.

إصدارات JSON Schema: أي مسودة تستخدم

مر JSON Schema بعدة مسودات — كل منها نُشر كـ مسودة إنترنت IETF — وهذا قد يكون محيرًا للمبتدئين. إليك نظرة عامة سريعة:

للمشاريع الجديدة، استخدم 2020-12 (الأحدث). إذا كنت تعمل مع قاعدة كود موجودة، تحقق من المسودة التي يدعمها المدقق الخاص بك. معظم المدققات الحديثة مثل Ajv تدعم Draft 7 وما بعده.

دمج JSON Schema في سير عملك

إليك نهجًا عمليًا لإضافة التحقق من JSON Schema إلى واجهة Express.js API:

هذا النمط يمنحك تحققًا تلقائيًا من الطلبات مع رسائل خطأ واضحة. خيار allErrors: true يضمن الإبلاغ عن جميع أخطاء التحقق دفعة واحدة، وليس فقط الخطأ الأول.

جرّبه بنفسك

مستعد لإضافة التحقق من المخطط إلى مشروعك؟ ابدأ بهذه الأدوات:

• JSON Schema Generator — الصق أي بيانات JSON واحصل على مخطط مولّد تلقائيًا. مثالي لإنشاء المخططات من استجابات API النموذجية.
• JSON Schema Validator — اختبر مخططك مقابل بيانات حقيقية للتأكد من أنه يكتشف ما يجب اكتشافه ويسمح بما يجب السماح به.
• JSON Validator — تحقق بسرعة من أن JSON الخاص بك صالح نحويًا قبل القلق بشأن التحقق من المخطط.

JSON Schema قد يبدو كعمل إضافي في البداية، لكنه يُثمر أضعافًا مضاعفة باكتشاف الأخطاء عند حدود نظامك بدلاً من عمق منطق عملك.