JSON Toolkit

مخارجات LLM المنظمة التي تنهار: كيف تكتب Schema فعليًا لوضع strict

الخلاصة: تفعيل strict على JSON Schema عشوائية يعيد 400 في معظم الحالات: كل الحقول required، additionalProperties:false على كل كائن، و$ref وallOf تُرفض فورًا. يوضح هذا الدليل كيفية إعادة كتابة سكيما متساهلة إلى نسخة متوافقة مع strict — مع union nullable وحدود صارمة وقائمة تحقق لـ refusal.

متوسطقراءة نحو 8 دقيقةنُشر في 2026-11-19حُدِّث في 2026-11-19
مخطط قواعد إعادة كتابة JSON Schema لوضع strict في نماذج اللغة الكبيرة

الخلاصة: strict: true ليس مفتاح «كن أكثر جدية» — إنه عقد يقبل فقط مجموعة فرعية من JSON Schema. كل الحقول required، وadditionalProperties: false على كل كائن، و$ref وallOf ممنوعة فورًا. إذا أرسلت السكيما في وضع strict دون إعادة كتابتها، فالرد هو 400، لا مخرجات موثوقة.

في الممارسة اليومية يتكرر المشهد ذاته: لدى الفريق سكيما مصممة جيدًا، بحقول اختيارية و$defs قابلة لإعادة الاستخدام وadditionalProperties مفتوح من أجل التوافق. ثم يضيف أحدهم "strict": true إلى نداء الـ API واثقًا أن النموذج «سيحترم» السكيما الآن. النتيجة الفورية خطأ 400 برسالة طويلة، أو الأسوأ: سكيما تُقبل لكنها تنتج مخارجات غير متوقعة. وضع strict لا يفسر السكيما بتساهل: إنه يعيد كتابتها من الصفر إلى قواعد نحوية يستطيع محرك التوليد اتباعها حرفًا بحرف، وكل ما لا يتسع في تلك القواعد يُرفض أو يُتجاهل بصمت. فهم القواعد التي تسري فعلًا، قبل إرسال الطلب، هو الفارق بين خط أنابيب مستقيم وأسبوع كامل من التنقيح.

وضع strict = تُجمَّع JSON Schema الخاصة بك إلى قواعد نحوية يجب أن يتبعها النموذج كلمة بكلمة. كل ما لا تستطيع القواعد التعبير عنه يُرفض عند الإرسال أو يُتجاهل بصمت — وفي الحالتين تظهر المشكلة بعد أن يكون المستخدم قد رآها.

كيف يعمل محرك وضع strict فعليًا

النماذج لا تقرأ JSON Schema الخاصة بك كمدقق تقليدي. عند تفعيل strict: true، تتحول السكيما إلى قواعد نحوية مقيدة — آلة حالات منتهية تحكم، رمزًا برمز، على أي استكمالات مسموحة. ينتج النموذج الانتقالات المسموح بها من الآلة فقط؛ لا يوجد تحقق لاحق للإنتاج يصحح المخرجات — الصحة بنيوية.

هذه المعمارية تفسر كل سلوك يبدو غامضًا. إذا لم يكن الحقل ضمن required، على الآلة أن تقرر متى تتوقف: الحل الآمن الوحيد هو منح النموذج حرية إصدار null، وبالتالي فالسكيما الفعلية التي يتلقاها المحرك ستتضمن ذلك الحقل دائمًا. إذا سمح كائنٌ بخصائص إضافية، فالآلة لا تستطيع التنبؤ بالمفاتيح التي ستظهر، لذا يجب أن يُغلق كل كائن بإحكام. كل «ممنوع» في التوثيق ينشأ من قيد ملموس في هذه الآلة، لا من خيار أسلوبي لدى OpenAI.

النتيجة الثانية أخطر: بعض الكلمات المفتاحية في JSON Schema (مثل pattern وminLength وmaximum) صالحة للسكيما لكنها غير مفروضة من القواعد النحوية. تُقبل السكيما، ويرد الرد نظيفًا، لكن القيد لم يُراعَ أبدًا. إنه الطريق الأكثر صمتًا لإفساد خط الأنابيب: يفشل التحقق اللاحق في الإنتاج ولا يُظهر أي سجل خطأ سكيما.

ثلاث قواعد لا يجوز المساومة عليها

إن لم يكن لديك سوى وقت لإصلاح شيء واحد، فأصلح هذه الثلاثة. فهي تحل الغالبية العظمى من أخطاء 400.

1. كل الحقول في required، دائمًا. في وضع strict، يجب أن يظهر كل مفتاح معلن في properties في required — حتى الاختيارية. الحيلة الرسمية للقول «اختياري» هي union nullable:

{
  "type": "object",
  "properties": {
    "couponCode": { "type": ["string", "null"] }
  },
  "required": ["couponCode"],
  "additionalProperties": false
}

بهذا تعرف الآلة بدقة متى يكون المفتاح سليمًا، ويعبر النموذج عن «لا يوجد قسيمة» بقيمة null بدل إسقاط المفتاح.

2. additionalProperties: false على كل كائن. ليس على الكائن الجذر فقط: كل كائن متداخل، دون استثناء. طبقة واحدة مفتوحة تجعل السكيما كلها غير مطابقة.

3. $ref وallOf ممنوعتان. لا مراجع، ولا $defs، ولا تركيب. يجب أن تكون السكيما موسعة بالكامل، شجرة واحدة مستقلة بذاتها. وif/then/else وoneOf في الجذر لهما المصير ذاته.

جدول المصطلحات الممنوعة والعديمة الأثر

الكلمة المفتاحية النتيجة في وضع strict البديل الموصى به
$ref، $defs رفض مع 400 توسيع السكيما بالكامل
allOf رفض مع 400 دمج الخصائص يدويًا
if/then/else رفض مع 400 enum + معالجة لدى العميل
oneOf في الجذر مشاكل / رد غير مطابق كائن جذر واحد فقط
حقل خارج required يتحول إلى إلزامي دائمًا union nullable ["string", "null"]
pattern، minLength تُقبل السكيما لكن القيد يُتجاهل تحقق صريح بعد الرد
maximum، format تُقبل السكيما لكن القيد يُتجاهل فحص لدى التطبيق

أخطر سطر هو الزوج الأخير: السكيما تجتاز التحقق لكن القيد غير موجود. إذا اعتمد منطقك على pattern، فأنت تبني على الرمل.

الحدود الصارمة التي لا يقرأها أحد

قبل كتابة السكيما، تأكد أنك ضمن هذه الحدود — تجاوزها ينتج أخطاء عامة يصعب تشخيصها:

القيد الحد الأقصى
مجموع الخصائص لكل سكيما 5000
عمق التداخل 10 مستويات
حجم نص السكيما 120,000 حرف
مجموع قيم enum 1000

السكيما المولدة آليًا من أطر العمل أو تعريفات OpenAPI كثيرًا ما تتجاوز هذه الحدود دون أن يلاحظها أحد: 6000 خاصية إجمالًا، 12 مستوى تداخل، 1500 قيمة enum متناثرة. رسالة الخطأ من الـ API نادرًا ما تشير إلى أي عتبة تجاوزت، فالأفضل أن تفحص بنفسك قبل الإرسال.

إعادة الكتابة الآلية: سكربت make_strict

للسكيما الكبيرة، إعادة الكتابة اليدوية غير عملية. هذا السكربت بلغة بايثون يجتاز الشجرة ويطبق القواعد الثلاث بشكل تكراري:

import json

def make_strict(node):
    if isinstance(node, dict):
        if node.get("type") == "object":
            props = node.get("properties", {})
            # كل خاصية تصبح required
            node["required"] = list(props.keys())
            node["additionalProperties"] = False
            # الحقول "الاختيارية" عليك تمييزها nullable مسبقًا
        # احذف ما لا يقبه strict
        for k in ("$ref", "$defs", "allOf", "if", "then", "else"):
            node.pop(k, None)
        return {k: make_strict(v) for k, v in node.items()}
    if isinstance(node, list):
        return [make_strict(v) for v in node]
    return node

schema = json.load(open("schema.json"))
print(json.dumps(make_strict(schema), indent=2))

تحذيران. الأول: السكربت لا يخمن أي الحقول كانت اختيارية — عليك تمييز union nullable بنفسك، ويُستحسن ذلك في مصدر السكيما لا في الناتج. الثاني: بعد التحويل، نفّذ دائمًا طلبًا تجريبيًا: قد يتجاوز التوسيع حدود الحجم أو عدد الخصائص التي كنت تلتزم بها سابقًا.

المسار المكافئ في Anthropic

لا توفر Anthropic علم strict، لكنها تحقق النتيجة ذاتها عبر آلية tool: تعريف الأداة يؤدي دور السكيما، والنموذج مقيد بشكلها. النهج متطابق عمليًا:

const tool = {
  name: "extract_invoice",
  description: "يستخرج بيانات الفاتورة من النص",
  input_schema: {
    type: "object",
    properties: {
      invoiceNumber: { type: "string" },
      totalAmount: { type: ["number", "null"] },
      lineItems: {
        type: "array",
        items: {
          type: "object",
          properties: {
            description: { type: "string" },
            quantity: { type: "number" }
          },
          required: ["description", "quantity"],
          additionalProperties: false
        }
      }
    },
    required: ["invoiceNumber", "totalAmount", "lineItems"],
    additionalProperties: false
  }
};

// يرد النموذج بنداء tool مطابق
const response = await anthropic.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  tools: [tool],
  tool_choice: { type: "tool", name: "extract_invoice" },
  messages: [{ role: "user", content: invoiceText }]
});

القاعدة العملية واحدة: في Anthropic أيضًا، يحتاج كل كائن إلى required كامل وadditionalProperties: false. الفرق في قناة الرد — tool_use بدل المحتوى النصي — وأن حقل refusal خاص بـ OpenAI.

refusal والقطع والشكل المكسور: ثلاثة أعطال، ثلاثة علاجات

حتى مع سكيما مثالية، قد تفشل المخرجات لثلاثة أسباب مختلفة، والخلط بينها أسرع طريق لخسارة يوم:

1. refusal غير فارغ. قد تعيد OpenAI في وضع strict حقل refusal مع سبب رفضها الطلب. هذا ليس خطأ سكيما — النموذج امتنع عن المهمة دلاليًا. العلاج مراجعة البرومبت أو السياسة، لا السكيما.

2. القطع بسبب max_tokens. يتوقف التوليد في منتصف النص ولا يُغلق JSON. في وضع strict، الرد إن وصل فهو مطابق — لكن إن نُفدت ميزانية الرموز وصل مقطوعًا. ارفع max_tokens أو قلص حجم المخرجات المتوقع. وللسيناريوهات المتكررة، الإصلاح الآلي لـ JSON المقطوع يوفر أنماطًا جاهزة.

3. شكل مكسور غير مطابق. كانت السكيما مفتوحة (خصائص إضافية مسموحة، حقول خارج required) ولم يُفعّل strict: ينتج النموذج JSON سليمًا لا يلتزم بالعقد. العلاج إعادة كتابة السكيما كما في هذا الدليل، لا إضافة تحققات لاحقة للإنتاج.

التشخيص الصحيح يبدأ دائمًا بالتفريق بين هذه الحالات الثلاث: النظر إلى حقل finish_reason، ووجود refusal، ومقارنة الرد بالسكيما التي أُرسلت فعلًا.

قائمة التحقق النهائية قبل الإنتاج

نقطة الفحص ماذا تفحص
required كامل كل خاصية معلنة موجودة في required
nullable صريح الحقول الاختيارية هي union ["...", "null"]
additionalProperties: false على كل كائن، لا الجذر فقط
صفر $ref / allOf / if-then-else السكيما موسعة بالكامل
الحدود محترمة ≤ 5000 خاصية، ≤ 10 مستويات، ≤ 120k حرف
القيود العديمة الأثر منقولة pattern/format تُفحص لدى التطبيق
معالجة refusal الشفرة تميز الرفض عن خطأ السكيما
اختبار بطلب حقيقي الرد التجريبي مدقق قبل النشر

إن أردت فهم لماذا additionalProperties: false محورية إلى هذا الحد، فالتحليل العميق لكلمة additionalProperties المفتاحية يوضح كيف يوسع كل كائن مفتوح فضاء التوليد. ولمُدخلِ السكيما في خط CI مع اختبارات عقد آلية، يغلق المسار الموصوف في JSON Schema contract testing الانحدارات الصامتة. وإذا احتجت بناء سكيما من أمثلة JSON موجودة، فأداة التحويل إلى JSON Schema على المنصة تجعلك تبدأ من بيانات حقيقية — مع ذلك، لوضع strict ستحتاج حتمًا إلى إعادة الكتابة الموصوفة هنا.

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

لماذا يشترط التوثيق أن تكون كل الحقول required، حتى الاختيارية؟ لأن آلة الحالات المنتهية يجب أن تقرر مسبقًا متى يكون كل مفتاح سليمًا. «الاختيارية» تعبر عنها بـ null، لا بغياب المفتاح: union nullable هي الطريقة الرسمية لقول ذلك.

تُقبل السكيما لكن pattern لا يعمل. هل هذا خلل؟ لا. في وضع strict، لا تفرض القواعد النحوية للتوليد pattern ولا minLength ولا maximum ولا format. السكيما صحيحة نحويًا لكن القيد غير موجود: افحص لدى التطبيق.

هل يمكنني استخدام $ref إذا أعلنت $defs أيضًا؟ لا، كلاهما ممنوع. يجب أن تكون السكيما شجرة واحدة موسعة بالكامل. سكربتات إعادة الكتابة الآلية تتولى التوسيع.

ما الفرق بين refusal وخطأ السكيما؟ refusal ردٌ مطابق يعلن فيه النموذج دلاليًا أنه لا يريد تنفيذ المهمة. خطأ السكيما هو 400 عند الإرسال أو مخرجات غير مطابقة. مشكلتان مختلفتان بعلاجين مختلفين.

إلى أي عمق يمكنني تداخل الكائنات؟ 10 مستويات تداخل كحد أقصى و5000 خاصية إجمالًا لكل سكيما. السكيما المولدة آليًا كثيرًا ما تتجاوز هذه الحدود: افحص قبل الإرسال.

الخلاصة

وضع strict ليس خيارًا تجميليًا: إنه الانتقال من «أرجو أن يحترم النموذج السكيما» إلى «القواعد النحوية تمنع فيزيائيًا المخرجات غير المطابقة». ثمنه مجموعة فرعية صارمة من JSON Schema — required كامل، كائنات مغلقة، بلا مراجع — وبعض القيود التي تعبر بلا انتباه لكنها لا تفرض. استثمر نصف ساعة في إعادة الكتابة بسكربت make_strict، وميّز union nullable بعناية، واختبر دائمًا بطلب حقيقي قبل النشر: خط الأنابيب الناتج مختلف جودةً عن الذي يُبنى على إعادة المحاولة والإصلاح بعد وقوع الأعطال.

المراجع

مقالات ذات صلة

اختبارات العقود مع JSON Schema: لحام قواعد التحقق في CI

المخطط لا ينتهي عندما يُكتب — هناك يبدأ التدهور. خطأ مطبعي واحد يُرخي التحقق بصمت، وإعادة هيكلة واحدة تكسر جميع العينات. يشرح هذا الدليل منظومة اختبارات عقود قابلة للتنفيذ: عينات إيجابية وسلبية ولقطات حالة، وفحص lint للمخطط نفسه، وتجميع لمرة واحدة مع إعادة استخدام، وأربع بوابات CI تحوّل التغييرات الكاسرة للعقود إلى بنيات حمراء.

متوسطقراءة نحو 8 دقيقةحُدِّث في 2026-11-05

JSON من نموذج لغوي مقطوع في المنتصف: اقرأ سبب التوقف أولاً ثم تحدث عن الإصلاح

يعيد النموذج JSON مقطوعاً في وسط قيمة، والمحلل لا يعطيك إلا رقم عمود. إغلاق الأقواس يعيده قابلاً للتحليل، لكن كل حقل مفقود أصبح الآن مخفياً داخل البيانات. يضع هذا المقال حداً بين ما يستطيع إصلاح القطع استعادته بأمانة وما يجب طلبه من جديد.

تطبيقيقراءة نحو 5 دقيقةحُدِّث في 2026-11-14

بدون additionalProperties، لا يتحقق تحقق المخطط من أي شيء

اجتياز التحقق لا يعني بيانات نظيفة. Pydantic يتجاهل الحقول غير المعروفة افتراضيًا، وZod يزيلها، وAjv يمررها — المعاملات المتخيلة والمفاتيح المكتوبة خطأً تعبر بصمت. يعرض هذا المقال ثلاث صور للقبول الصامت ويقدم طرقًا كاملة: إغلاق الكائنات، والتحكم في تحويل الأنواع، وشد كل مستوى تداخل.

Intermediateقراءة نحو 8 دقيقةحُدِّث في 2026-11-02