مولّد مخطط JSON

ما يُتقنه الاستنتاج

• الأنواع: string، number، integer، boolean، null، array، object.
• قابلية القيمة الفارغة: الحقل الذي يكون null في عيّنة وسلسلة نصية في أخرى يصبح ["string", "null"].
• عناصر المصفوفة: المصفوفات المتجانسة تُنتج مخطط items واحدًا؛ أما غير المتجانسة فتُنتج prefixItems.
• القيم المعدودة (enum): إذا كانت جميع القيم المرصودة من مجموعة صغيرة (قابلة للضبط، والقيمة الافتراضية 10 قيم مختلفة)، فإنه يُصدر enum.
• الإلزامية: مع عدة عيّنات، يصبح تقاطع المفاتيح required؛ ومع عيّنة واحدة تكون جميع المفاتيح إلزامية ما لم تختر خلاف ذلك.
• الصيغ: السلاسل النصية التي تطابق تواريخ ISO-8601 أو عناوين البريد الإلكتروني أو URI تحصل على format مستنتَج.

ما لا يستطيع الاستنتاج معرفته

• النية مقابل المثال: العيّنة age: 25 تستنتج type: integer، لكنها لا تستطيع معرفة أنك تقبل null أيضًا. مرّر عدة عيّنات تغطّي الحالات الحدّية.
• القيود: minLength وmaximum وpattern، عليك إضافتها يدويًا. لا يخمّن الاستنتاج الحدود من العيّنات.
• منطق العمل: شرط «يجب ضبط حقل واحد بالضبط من هذه الحقول الثلاثة» يتطلب oneOf، ولا يمكن استنتاجه.
• المراجع: يُصدر المولّد مخططًا مسطّحًا. إذا أردت فصل الأشكال المتكرّرة في $defs، فافعل ذلك بعد التوليد.

مثال على المخرجات

من عيّنة واحدة:

{ "name": "Alice", "age": 30, "tags": ["admin", "user"] }

المخطط المستنتَج (draft 2020-12):

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" },
    "tags": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["name", "age", "tags"]
}

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

• الاستنتاج من عيّنة واحدة. سيُبالِغ المخطط في المطابقة، يصبح كل حقل إلزاميًا دون أي سماح بـ null. قدّم دائمًا ما لا يقل عن 5 إلى 10 عيّنات متنوّعة.
• استخدام integer بينما كنت تقصد number. إذا احتوت أي عيّنة على رقم عشري، يصبح النوع المستنتَج number؛ وإذا كانت كلها أعدادًا صحيحة، يصبح integer. أما الحقول التي قد تكون من أيّ منهما، فضمّن عيّنة تحتوي على رقم عشري.
• نسيان الحقول الاختيارية. الحقل الموجود في 4 من 5 عيّنات والمفقود في واحدة يصبح اختياريًا، وهذا مقصود. أما إذا تضمّنته العيّنات الخمس جميعها، فسيعلّمه المخطط على أنه إلزامي رغم أنه في الواقع اختياري في واجهتك البرمجية.