مدقّق JSON Schema

ما هي أداة JSON Schema؟#

تُخبرك قيمة JSON بمفردها بما البيانات هو — سلسلة هنا، رقم هناك. لكنها لا تُخبرك بما يجب أن تكون البيانات: هل يجب أن يكون age عددًا صحيحًا غير سالب، هل email مطلوب، هل يُسمح لـ tags أن يكون فارغًا. JSON Schema هي المفردات لقول هذه الأشياء. تكتب مخططًا — مستند JSON صغير يصف شكلًا — ويتحقق المُحقِّق إن كانت قطعة بيانات تناسب ذلك الشكل، حقلًا بحقل.

تقوم هذه الصفحة بمهمتين بمحرك مخطط واحد. يأخذ التحقق مخططًا ومستند بيانات ويُخبرك بدقّة أي الحقول تنتهك أي القواعد، كلٌّ مُثبَّت إلى مساره في المستند. ويمضي الاستنتاج في الاتجاه الآخر: أعطه عيّنة قيمة JSON فيكتب مخططًا على نمط Draft-07 نيابةً عنك، بجول البنية وتسجيل نوع كل حقل. ويتكاملان بطبيعة الحال — استنتج مخططًا من عيّنة تمثيلية، ثم تحقّق كل مستند مستقبلي مقابلها.

يجري التحقق على محرك Ajv نفسه الذي يستخدمه كود الإنتاج، مع ثلاثة إصدارات قابلة للاختيار (Draft-07، 2019-09، 2020-12) وتخفيف حارس الوضع الصارم، فيُسمَح بمخطط غير صارم نسبيًّا بدلًا من رفضه تمامًا.

كيفية الاستخدام#

1. اختر وضعًا من مفتاح شريط الأدوات:
   • تحقق (الافتراضي): الصق مخططك على اليسار، وبياناتك على اليمين.
   • استنتاج: الصق عيّنة قيمة JSON على اليسار، اقرأ المخطط المُولَّد على اليمين.
2. في وضع التحقق، اختر Draft الذي كُتب المخطط ضده — Draft-07 يغطي الغالبية العظمى من المخططات الموجودة؛ اختر 2019-09 أو 2020-12 فقط إن كان مخططك يستخدم ميزات أدخلها هذان الإصداران.
3. اختر مسافة بادئة للمخرجات — مسافتان أو 4. في وضع الاستنتاج يتحكم هذا في تنسيق المخطط المُولَّد.
4. تُظهر اللوحة اليمنى إمّا مستند البيانات (تحقق) أو المخطط المستنتَج (استنتاج). تُبدَّل تسميات اللوحة لتطابق الوضع.
5. في وضع التحقق، تسرد لوحة المخالفات أسفل اللوحات كل خرق كـ path — reason. يُعرض جذر المستند كـ (root)؛ ويظهر حقل متداخل كمؤشر JSON Pointer، مثل /age.
6. انقر نسخ في اللوحة اليمنى لأخذ المخطط المستنتَج أو البيانات، أو مثال / مسح للتحميل أو الضبط.

تُحتسب النتائج بمجرد تحليل المدخلين. ويُبلَّغ عن خطأ بنية مخطط أو بيانات بصفه وعموده الدقيقين، مُوسومًا كمشكلة مخطط أو بيانات أو تجميع لتعرف أين تنظر.

الميزات الرئيسية#

• وضعان، محرك واحد. تحقق المستندات، أو ولّد مخططًا من عيّنة، بمُحقِّق موثوق نفسه تحته.
• ثلاثة إصدارات. Draft-07، 2019-09، 2020-12 يحمل كلٌّ منها مُحقِّقه المُترجم فقط، فتتحقق دائمًا مقابل الإصدار الذي تستهدفه فعلًا.
• كل الأخطاء، لا الأول فقط. تُجمَع كل مخالفة، فمستند بخمس مشاكل يُظهر خمس مشاكل بدلًا من إجبارك على خمس رحلات.
• مخالفات مُثبَّتة بالمسار. يشير كل خرق إلى موقعه في المستند — (root) لمشاكل المستند كله، أو مؤشر دقيق مثل /user/address/zip.
• تخفيف الوضع الصارم. مخطط بمفتاح مجهول أو بدون نوع ذي مستوى أعلى يُسمَح به ويُشغَّل، ولا يُرفض وقت الترجمة — السلوك الصحيح لأداة وظيفتها التحقق لا الوعظ.
• محلي فقط. تُعالَج المخططات والبيانات في متصفحك. لا شيء يُرفَع.

مثال عملي#

كائن user يجب أن يحوي name، ويجب أن يكون age عددًا صحيحًا غير سالب. الصق هذا المخطط على اليسار في وضع التحقق:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}

الآن اختبر مستندًا يكسر القاعدتين — يفتقد name، وage سالب:

{
  "age": -3
}

تُبلِّغ لوحة المخالفات عن خرأين، كلٌّ مُثبَّت إلى حيث حدث:

(root) — must have required property 'name'
/age   — must be >= 0

يُخبرك مسار (root) أن الخاصية المطلوبة المفقودة مشكلة على مستوى المستند؛ ويشير /age مباشرة إلى الحقل المُخطئ. أصلح البيانات إلى {"name":"ada","age":36} فينقلب الوضع إلى صالح بقائمة مخالفات فارغة. نص السبب هو صياغة Ajv الأصلية للكلمة المفتاحية، المُحفوظة حرفيًّا لتطابق ما ستقوله سجلات الإنتاج.

الأسئلة الشائعة#

Draft-07 أم 2019-09 أم 2020-12 — أيها أختار؟#

Draft-07 هو الافتراضي العملي: الغالبية الساحقة من المخططات في الدروس والمكتبات ومواصفات OpenAPI تستهدفه، وكل ما يُرجَّح أن تحتاجه (type، properties، required، minimum، format، $ref) يعمل هناك. انتقل إلى 2019-09 أو 2020-12 فقط حين يستخدم مخططك صراحةً ميزات أضافها هذان الإصداران — مثل unevaluatedProperties أو سلوك $ref المُنقَّح. اختيار الإصدار الخطأ يعمل عادةً أيضًا، لكن الخيار الآمن هو الإصدار الذي قصده مؤلف المخطط.

لماذا رسائل المخالفة بالإنجليزية؟#

إنها نص سبب Ajv الأصلي لكل كلمة مفتاحية (must have required property، must be >= 0، وهكذا)، مُمرَّرة دون تغيير. الهدف الاتساق: هذه هي السلاسل تمامًا التي ستسجّلها مُحقِّقاتك من جهة الخادم، فمطابقتها هنا يجعل عدم التطابق قابلًا للـ grep تافهًا في الإنتاج.

ماذا يعني “تخفيف الوضع الصارم”؟#

يرفض الوضع الصارم لـ Ajv المخططات التي يعتبرها مهملة — مفتاح مجهول، أو $ref لا يستطيع حله، أو غياب type. هذا مفيد في خط بناء لكنه خاطئ لأداة تحقق، وظيفتها التحقق من البيانات مقابل أي مخطط تُسلِّمه. تُطفئ هذه الصفحة الوضع الصارم، فيُترجَم المخطط غير الصارم ويُشغَّل بدلًا من رمي خطأ.

هل أستطيع استنتاج مخطط ثم التحقق ضده؟#

نعم — هذه رحلة الذهاب والإياب المقصودة. الصق عيّنة تمثيلية في وضع استنتاج، انسخ المخطط المُولَّد، بدِّل إلى تحقق، وألصق المخطط عودةً على اليسار. يُعيد المخطط المستنتَج التحقق من العيّنة الأصلية بنظافة، ومن ثمّ فصاعدًا يمكنك التحقق من كل مستند جديد ضده.