📐 معيار JSON Schema Draft 2020-12

مخططات JSON ومحرك التصحيح الذاتي التلقائي

عقود التحقق الصارمة لكافة الـ 114 تسليمة، معايير وتنسيقات RFC الإلزامية، ومحرك التغذية الراجعة التلقائية لإصلاح أخطاء نماذج الذكاء الاصطناعي.

الأقسام الفنية: 📖 بوابة المطورين ⌨️ أداة الطرفية والأتمتة 🐍 مكتبة بايثون (SDK)🔌 خادم بروتوكول MCP 📐 المخططات والتحقق 🤖 أسراب الوكلاء و CI/CD

1. لماذا اعتمدنا معيار JSON Schema Draft 2020-12؟

في البيئات المؤسسية والحكومية الخاضعة للتدقيق الصارم، لا يمكن الاعتماد على التوليد النصي الحر لنماذج الذكاء الاصطناعي؛ إذ تعاني النماذج من الهلوسة بابتكار حقول غير معتمدة، أو إغفال التوقيعات الإلزامية، أو كتابة التواريخ بصيغ عشوائية. لذلك، تفرض منظومة تسليمات مخطط JSON Schema Draft 2020-12 كعقد إلزامي لكل تسليمة.

مزايا معيار Draft 2020-12:

unevaluatedProperties: false: حظر أي حقول إضافية غير معلنة في المخطط منعاً تاماً للهلوسة.
dependentRequired: قواعد الارتباط الشرطي (مثال: إذا كان للمشروع أثر تعاقدي، يصبح توقيع مسؤول المشتريات إلزامياً).
prefixItems: التحقق من الترتيب الزمني لمصفوفات الموافقات وبوابات المراجعة.

2. معايير RFC الإلزامية وأوضاع التحقق

يتحقق محرك الفحص الآلي من صحة التنسيقات وفق المعايير الدولية التالية:

معيار RFC	الكلمة المفتاحية	قواعد ودلالات التحقق
RFC 3339	`date`	صيغة التاريخ الكامل `YYYY-MM-DD` مع التحقق الحسابي من السنوات الكبيسة وأيام الأشهر.
RFC 3339	`date-time`	التوقيت الكامل `YYYY-MM-DDTHH:MM:SSZ` مع التحقق من دقة المنطقة الزمنية UTC.
RFC 4122	`uuid`	المعرف الفريد بطول 128 بت بصيغة الستة عشري القياسية (8-4-4-4-12).
RFC 3986	`uri`	صحة هيكلية الروابط ومطابقتها لبروتوكولات ومسارات الويب المعتمدة.
RFC 5322	`email`	الصيغة القياسية لصناديق البريد الإلكتروني مع التحقق من صحة النطاق واسم المستخدم.

أوضاع التحقق: الصارم (Strict) مقابل المسودة (Draft)

mode="strict": التدقيق الصارم بدون تساهل. يفرض وجود كافة الحقول الإلزامية، ويرفض النصوص الفارغة والحقول غير المعلنة. إلزامي لبوابات المراجعة واعتمادات اللجان التوجيهية.
mode="draft": التدقيق المرن للتطوير التدريجي. يسمح بترك الحقول الاختيارية فارغة مع التحقق من صحة أنواع وتنسيقات الحقول المعبأة. يُستخدم أثناء التخطيط المبكر وسبرنتات العمل الأولى.

3. حلقة التصحيح الذاتي التلقائي للوكلاء الأذكياء

محرك المعالجة الذاتية

النماذج اللغوية الرائدة (مثل Gemini و Claude و GPT-4o) لا تحتاج إلى تدخل بشري لتعديل الأخطاء الطفيفة؛ فعندما ينتج النموذج بيانات تخالف المخطط، ترجع دالة tasleemat.validate_artifact_data مسار الخطأ بدقة (عبر JSON Pointer). يقوم الوكيل بإعادة توجيه الخطأ للنموذج ليصلح نفسه تلقائياً في جولة واحدة:


sequenceDiagram
    autonumber
    actor User as الممارس / مدير المشروع
    participant Agent as الوكيل الذكي (PMO Agent)
    participant Engine as محرك التحقق في تسليمات
    participant LLM as نموذج الذكاء الاصطناعي (LLM)

    User->>Agent: "قم بإعداد سجل المخاطر لمشروع السحابة"
    Agent->>Engine: get_artifact_asset("PMO-04.08.02", "schema")
    Engine-->>Agent: مخطط Draft 2020-12
    Agent->>LLM: الأمر + قيود المخطط البرمجي
    LLM-->>Agent: بيانات JSON الأولية (المسودة 1)
    Agent->>Engine: validate_artifact_data("PMO-04.08.02", المسودة 1, mode="strict")
    Engine-->>Agent: ValidationReport(valid=False, error="نقص حقل إلزامي في /risks/0/score")
    Note over Agent,LLM: جولة التصحيح الذاتي التلقائي
    Agent->>LLM: "فشل التحقق في المسار /risks/0/score. أصلح الخطأ فوراً."
    LLM-->>Agent: بيانات JSON المصححة (المسودة 2)
    Agent->>Engine: validate_artifact_data("PMO-04.08.02", المسودة 2, mode="strict")
    Engine-->>Agent: ValidationReport(valid=True)
    Agent->>User: "تم توليد سجل المخاطر بنجاح وتأكيد صحته وفق المخطط 100%"

4. أدلة تطبيقية عملية (Tutorials)

الدليل 1: كود برمجي متكامل لحلقة التصحيح الذاتي التلقائي

سكربت بايثون تنفيذي مكتمل لتطبيق حلقة التصحيح الذاتي مع قياس أداء التعافي:

import json
import tasleemat

def run_autonomous_synthesis(artifact_id: str, prompt_notes: str, llm_callable, max_retries: int = 3):
    # توليد بيانات الوثائق مع المعالجة الذاتية التلقائية للأخطاء
    schema = tasleemat.get_artifact_asset(artifact_id, "schema", lang="ar")
    current_prompt = prompt_notes
    telemetry = {"attempts": 0, "healed": False}

    for attempt in range(1, max_retries + 1):
        telemetry["attempts"] = attempt
        print(f"محاولة التوليد رقم {attempt} للتسليمة {artifact_id}...")
        
        # 1. استدعاء نموذج الذكاء الاصطناعي
        candidate_json_str = llm_callable(prompt=current_prompt, schema=schema)
        candidate_data = json.loads(candidate_json_str)

        # 2. التحقق الآلي من المخطط المعياري
        report = tasleemat.validate_artifact_data(artifact_id, candidate_data, mode="strict")
        if report.valid:
            print(f"✅ نجاح كامل! تم التوافق التام مع المخطط في المحاولة رقم {attempt}.")
            telemetry["healed"] = attempt > 1
            return candidate_data, telemetry

        # 3. صياغة توجيه التصحيح المركز للنموذج
        error_lines = [f"- في المسار '{e.path}': {e.message} (القاعدة: {e.keyword})" for e in report.errors]
        current_prompt = (
            f"{prompt_notes}\n\n"
            f"[تنبيه: فشلت المحاولة رقم {attempt} في التحقق للأسباب التالية:]\n"
            + "\n".join(error_lines)
            + "\nقم بتصحيح مسارات JSON هذه بدقة وأعد إرسال الكائن النهائي الصحيح."
        )

    raise RuntimeError(f"تعذر الوصول لبيانات مطابقة بعد {max_retries} محاولات.")

الدليل 2: كتابة وتصميم مخطط تسليمة مؤسسية مخصصة

تصميم مخطط Draft 2020-12 لتسليمة اعتماد أمان السحابة المؤسسي:

custom_schema = {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://company.org/schemas/pmo-sec-01.json",
    "title": "اعتماد أمان السحابة",
    "type": "object",
    "required": ["project_id", "security_officer", "signoff_date", "vulnerability_count"],
    "properties": {
        "project_id": {"type": "string", "pattern": "^PRJ-[0-9]{4}-[A-Z]+$"},
        "security_officer": {"type": "string", "minLength": 3},
        "signoff_date": {"type": "string", "format": "date"},
        "vulnerability_count": {"type": "integer", "minimum": 0, "maximum": 0},
        "audit_passed": {"type": "boolean", "const": True}
    },
    "unevaluatedProperties": False
}