كيفية إنشاء JSON Schema
- الصق مثال JSON يمثّل بياناتك جيدًا. تعطي المصفوفات التي تحتوي على عدة عناصر أفضل النتائج، لأن عناصرها تُدمج في مخطط واحد.
- اختر إصدار المخطط (draft 2020-12 أو draft-07)، وحدّد ما إذا كانت الخصائص إلزامية، وما إذا كانت التنسيقات ستُكتشف، وما إذا كانت الخصائص الإضافية ممنوعة.
- انسخ المخطط أو نزّله، ثم حسّنه يدويًا – مثلًا بإضافة الأوصاف أو قيم enum أو الحدود الدنيا والقصوى.
ما الذي يستنتجه المولد؟
| مثال JSON | المخطط |
|---|---|
"ada@example.com" | {"type": "string", "format": "email"} |
"2026-05-01T10:00:00Z" | التنسيق date-time (وكذلك date و time و uri و uuid و ipv4) |
42 / 4.5 | "integer" / "number" |
| مفتاح موجود في كل كائن | يُدرج في required |
| مفتاح مفقود في بعض عناصر المصفوفة | اختياري (غير مدرج في required) |
[1, "a", null] | "items": {"type": ["string", "integer", "null"]} |
| كائنات ممزوجة بقيم بسيطة | anyOf مع مخطط لكل نوع |
ما هو JSON Schema؟
JSON Schema معيار لوصف بنية بيانات JSON والتحقق منها: ما الخصائص الموجودة، وما نوع كل منها، وأيها إلزامي، وما القيم المسموح بها. يُستخدم لتعريف عقود API في OpenAPI، وفي ملفات الإعدادات، وتوليد النماذج، والتحقق من صحة المخرجات المنظَّمة لنماذج الذكاء الاصطناعي. الإصدار الحالي هو 2020-12، ولا تزال كثير من الأدوات القديمة تدعم draft-07. والمواصفات منشورة على json-schema.org.
تحسين المخطط المُنشأ
- أضف
titleوdescriptionلتوثيق معنى كل حقل. - قيّد القيم باستخدام
enumأوminimumأوmaximumأوmaxLengthأوpattern. - حدّد خيار منع الخصائص الإضافية (
additionalProperties: false) لرفض المفاتيح غير المعروفة. - تحقق من صحة البيانات باستخدام Ajv في JavaScript أو حزمة
jsonschemaفي Python.
الأسئلة الشائعة
أي إصدار من JSON Schema يجب أن أستخدم؟
استخدم draft 2020-12 في المشاريع الجديدة – فهو الإصدار الحالي وأساس OpenAPI 3.1. واختر draft-07 إذا كانت أداة التحقق أو الأدوات التي تستخدمها لا تدعم 2020-12 بعد.
لماذا تظهر كل الخصائص كإلزامية؟
عند استخدام كائن مثال واحد تكون كل الخصائص موجودة، لذا تُعلَّم جميعها كإلزامية. استخدم مصفوفة تحتوي على عدة أمثلة متنوعة، أو أوقف خيار تحديد الخصائص كإلزامية.
هل يستطيع المولد اكتشاف قيم enum أو النطاقات؟
لا. لا يمكن لمثال واحد أن يبيّن القيم المسموح بها عمومًا، لذا يجب إضافة قيم enum والحدود الدنيا والقصوى والأنماط يدويًا.
كيف أتحقق من صحة JSON مقابل المخطط؟
استخدم مكتبة تحقق مثل Ajv في JavaScript أو jsonschema في Python. كما تتحقق كثير من محررات الأكواد من ملف JSON مقابل المخطط المشار إليه في خاصيته $schema.