مدقّق JSON Schema

كيفية التحقق من JSON مقابل مخطط

1. الصق مخططك في خانة JSON Schema وبياناتك في خانة مستند JSON، أو اختر حالة جاهزة من قائمة مثال.
2. اترك الإصدار (Draft) على تلقائي ($schema) لاستخدام الإصدار الذي تحدده قيمة $schema في المخطط، أو افرض الإصدار 4 أو 7 أو 2019-09 أو 2020-12.
3. يجري التحقق أثناء الكتابة، ويعيد زر تحقّق تشغيله. أما تنسيق الاثنين فيعيد إزاحة النصين.
4. اقرأ النتيجة: سطر أخضر عندما يكون المستند صالحًا، وإلا فجدول بالأخطاء.

قراءة جدول الأخطاء

يمثّل كل صف قاعدة واحدة لم تتحقق:

• مسار القيمة: مؤشر JSON Pointer إلى القيمة التي فشلت. فالمسار /roles/1 هو العنصر الثاني في roles، و(الجذر) هو المستند كله.
• الكلمة المفتاحية: قاعدة المخطط التي فشلت، مثل type وrequired وminimum وpattern وformat وadditionalProperties وغيرها.
• الرسالة: تشرح سبب الفشل، مثل 0 is less than 1.. تصدر هذه الرسائل عن محرّك التحقق وتظهر بالإنجليزية في الصفحة العربية.
• مسار المخطط: يشير إلى الكلمة المفتاحية داخل المخطط، مثل /properties/id/minimum، لتجد القاعدة بسرعة.

لا يتوقف التحقق عند أول مشكلة، بل تُسرد كل الأخطاء. وعندما تفشل خاصية في كائن، يعرض المدقّق خطأً ملخّصًا (مثل Property "id" does not match schema) يليه السبب الدقيق. يخفي خيار عرض الأخطاء الأكثر تحديدًا فقط هذه الملخصات، وإذا ألغيت تفعيله رأيت السلسلة كاملة. أما الأخطاء الواقعة تحت anyOf وoneOf فتبقى دائمًا مع الأخطاء المحددة لكل فرع، لأنها لا تُفهم إلا معًا.

ما الذي تدعمه الأداة؟

• الإصدارات: 4 و6 (يُتحقق منه بقواعد الإصدار 7) و7 و2019-09 و2020-12، بما في ذلك $defs/definitions، و$ref المحلي، وif/then/else، وdependentRequired، وdependentSchemas، وprefixItems، وunevaluatedProperties، وunevaluatedItems.
• الصيغ (formats): تُفحص الصيغ date وtime وdate-time وduration وemail وhostname وipv4 وipv6 وuri وuri-reference وuri-template وuuid وregex وjson-pointer وrelative-json-pointer. وتُتجاهل الصيغ غير المعروفة كما تسمح المواصفة.
• المراجع: يمكن أن يشير $ref إلى أي موضع داخل المخطط، بما في ذلك معرّف $id يصرّح به المخطط. لا تُنزَّل المخططات البعيدة أبدًا، ويُبلَّغ عن أي مرجع إلى عنوان URL آخر بأنه غير محلول.

تتحقق هذه الأداة من المستندات مقابل مخططك، ولا تفحص ما إذا كان المخطط نفسه يتبع المخطط الوصفي (meta-schema). لكنها تنبّهك إلى أسماء type غير المعروفة مثل "strin" أو "int"، وهو خطأ إملائي شائع تتجاهله المدقّقات الأخرى بصمت.

الأمثلة

• ملف تعريف مستخدم (2020-12): required، وأطوال السلاسل النصية، وformat: email، وenum داخل items، وuniqueItems، وadditionalProperties: false.
• قائمة منتجات مع $ref (draft-07): مصفوفة تشير عناصرها إلى #/definitions/product، مع pattern لرمز المنتج (SKU) وسعر مقيّد بـexclusiveMinimum.
• إعدادات مع if/then (2019-09): شهادة مطلوبة في وضع HTTPS فقط، وoneOf بين بريد إلكتروني وURI، وحدود رقمية.

يأتي كل مثال مع مستند يحتوي على أخطاء متعمَّدة، لترى كيف تبدو الأخطاء.