أداة التحقق من مخطط JSON

الكلمات المفتاحية المدعومة

الأساسية: type، enum، const، multipleOf، maximum، minimum، exclusiveMaximum، exclusiveMinimum، maxLength، minLength، pattern، maxItems، minItems، uniqueItems، maxContains، minContains، maxProperties، minProperties، required، dependentRequired.

التركيب: allOf، anyOf، oneOf، not.

أدوات التطبيق: properties، patternProperties، additionalProperties، items، prefixItems، contains، propertyNames.

الشرطية: if، then، else، dependentSchemas.

المراجع: $ref، $defs، $id، $anchor.

الصيغ (مع التحقق منها عند تفعيلها): date-time، date، time، duration، email، hostname، ipv4، ipv6، uri، uuid، regex.

مخرجات الخطأ

FAIL  /user/email        format            "not-an-email" is not a valid "email"
FAIL  /user/age          minimum           -3 is less than the minimum 0
FAIL  /orders/0/total    type              "42" is not of type "number"
FAIL  /                  required          missing required property "shippingAddress"

يتضمن كل خطأ المسار والكلمة المفتاحية التي فشلت، مما يسمح بتحديد موقعه بسهولة في محررك.

اختلافات المسودات التي تسبب المشكلات

اضبط المسودة الصحيحة؛ فالتحقق من مخطط المسودة 04 على أنه 2020-12 سيؤدي إلى تفسير خاطئ للكلمة id وبعض التفاصيل الدقيقة الأخرى.

سير العمل النموذجي

• اختبار عقد واجهة برمجة التطبيقات (API): قبل النشر، شغّل مخطط OpenAPI المُولَّد أو المُحدَّث على استجابات نموذجية حقيقية.
• تعزيز الإعدادات: تحقق من صحة كل ملف إعدادات بصيغة YAML/JSON في مرحلة الـ CI وفقًا لمخطط محدد قبل الدمج.
• استيعاب البيانات: ارفض مبكرًا الحمولات التي لا تطابق الشكل المتوقع، مع رسالة خطأ واضحة.

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

• إغفال فرض format. بشكل افتراضي، تتعامل معظم أدوات التحقق مع الصيغ غير المعروفة كتعليقات توضيحية فقط. فعّل التحقق الصارم من الصيغة لرفض عناوين البريد الإلكتروني والتواريخ غير الصالحة فعليًا.
• الإفراط في استخدام oneOf. إذا تداخل فرعان من oneOf، فسيفشل المستند (يجب أن يطابق فرعًا واحدًا بالضبط). استخدم anyOf أو أنماط التمييز.
• المخططات الصارمة مع additionalProperties: false. تصبح إضافة حقل اختياري جديد تغييرًا كاسرًا للتوافق. تجنّب استخدامها ما لم تكن ترغب فعلًا في كائن مغلق.