مكتبة مرجع OpenAPI

الهدف

هذا الدليل هو عقد الاكتشاف لحزم مرجعية مدعومة بـ OpenAPI لDecision Gate. إنه يجيب، عن كل حزمة:

1. أين هو ملف OpenAPI القياسي؟
2. هل هو مؤلف يدويًا أم مستمد من مصدر أعلى؟
3. أي اختبار نظام يفرض سلامة الكتالوج والمرايا غير المتصلة؟
4. أين توجد وثائق واجهة برمجة التطبيقات للمستخدمين البشر؟

العقد القياسي

المصدر القابل للقراءة آليًا هو:

• references/openapi/reference_library.json

تم التحقق منه بواسطة المخطط:

• references/openapi/reference_library.schema.json

يجب أن تمر كل حزمة مدرجة هناك بفحوصات البوابة الصعبة في:

• system-tests/src/suites/openapi_reference_library.rs

كتالوج الحزم الحالي

معرف الحزمة	المجال	OpenAPI القياسي	المرايا	اختبار النظام	المستندات العلوية
courtlistener-legal-citation-v1	التحقق من الاقتباس القانوني	references/openapi/courtlistener-legal-citation-v1/openapi.json	system-tests/tests/fixtures/legal_citation/courtlistener_reference_openapi.json و examples/agentic/legal-citation-verification/courtlistener_reference_openapi.json	openapi_reference_library_canonical_and_mirrors_are_byte_equal في system-tests/src/suites/openapi_reference_library.rs	نظرة عامة على REST، بحث الاقتباس، جذر API (v4)

بيانات التغطية والتنفيذ

كل إدخال حزمة يعلن عن بيانات وصفية لبحث العناصر:

1. execution_modes: وضع الكتالوج المدعوم الحالي هو offline_fixture فقط.
2. coverage: الأعداد الحتمية المطلوبة:
   • operations
   • fabricated_cases
   • known_good_cases
   • ambiguous_cases
   • invalid_cases
3. live_mode: بيانات وصفية لالتقاط المصدر فقط؛ سياسة CI الحالية هي disabled:
   • enabled_by_env
   • required_env
   • optional_env
   • ci_policy (manual_only أو disabled)

بالنسبة لـ CourtListener، ينتمي COURTLISTENER_API_TOKEN فقط إلى برنامج التقاط العناصر اليدوي المستقل. إنه ليس مسار اعتماد وقت تشغيل DG، و لا يمكن تمكين الحزمة كمزود من خلال التكوين.

قاعدة تأليف الإسقاط (معيارية)

يتم تقييم بيانات التعريف الخاصة بالإسقاط على مخطط الاستجابة الموحد/المحلول. بيانات التعريف الخاصة بالإسقاط على مستوى المكونات المشار إليها عبر $ref هي من الدرجة الأولى وموضوعة في الاعتبار.

لا تقم بإدراج مخططات استجابة مكررة فقط لتلبية فحوصات المستورد. احتفظ بموقع عرض قياسي واحد (عادةً هو مخطط المكون المرجعي) وكرر ذلك بايتًا مقابل بايت عبر نسخ الحزمة القياسية/النظامية/المثال.

سياسة أصل المصدر

لكل حزمة، يجب أن يعلن كتالوج provenance بوضوح عن الأصل:

• hand_authored_fixture
• upstream_openapi_snapshot
• generated_from_upstream_docs

تستخدم CourtListener حاليًا hand_authored_fixture.

تغطية البوابة الصعبة

تفرض CI القياسية بوابات حتمية غير متصلة بالإنترنت:

1. كتالوج JSON صالح وفقًا للمخطط.
2. جميع المسارات المفهرسة موجودة.
3. تعتبر العناصر الفنية لـ OpenAPI القياسية والمعكوسة متساوية بايت (بما في ذلك operation_fixture_corpus.json وملفات بيان الالتقاط المصدر).
4. كتالوج system_test_name موجود في Docs/generated/testing/proof_catalog.json.
5. كتالوج docs_paths موجود في Docs/verification/registry.toml.
6. عناوين URL العلوية هي https:// مطلقة وكاملة البيانات الوصفية.
7. تعتبر بيانات التغطية وبيانات الالتقاط المصدر صالحة هيكليًا وتم تعطيل CI المباشر.

لا يتم تشغيل أي فحوصات للوصول إلى الشبكة الحية في CI القياسي.

قائمة التحقق للحزمة الجديدة (جاهز لـ PubMed/arXiv)

استخدم هذه القائمة عند إضافة DG + PubMed، DG + arXiv، أو ما شابه:

1. إنشاء دليل قياسي: references/openapi/<pack-id>/
2. أضف الملفات المرجعية:
   • openapi.json
   • citation_cases.json (أو مجموعة بيانات حتمية مكافئة للنطاق)
   • README.md
3. أضف نسخاً مطابقة ضمن:
   • system-tests/tests/fixtures/<domain_pack>/
   • examples/agentic/<domain-pack>/
4. أضف/مدد مجموعة اختبارات النظام تحت system-tests/src/suites/.
5. تسجيل مجموعة الاختبارات في system-tests/tests/providers.rs.
6. تحديث إعلان إثبات Rust المجاور للسلسلة وإعادة توليد system-tests/TEST_MATRIX.md.
7. أضف إدخال الحزمة إلى references/openapi/reference_library.json.
8. تأكد من تسجيل docs_paths في Docs/verification/registry.toml.
9. تضمين روابط ماركداون المسماة إلى وثائق API في README الحزمة.
10. أعلن عن بيانات التعريف execution_modes و coverage و live_mode.

قالب البيانات الوصفية

{
  "pack_id": "<kebab-case-pack-id>",
  "version": "v1",
  "domain": "<domain>",
  "status": "experimental",
  "provenance": "hand_authored_fixture",
  "canonical_openapi_path": "references/openapi/<pack-id>/openapi.json",
  "system_fixture_openapi_path": "system-tests/tests/fixtures/<pack>/openapi.json",
  "example_openapi_path": "examples/agentic/<pack>/openapi.json",
  "system_suite_path": "system-tests/src/suites/<suite>.rs",
  "system_test_name": "<exact_test_name>",
  "docs_paths": [
    "Docs/guides/openapi_reference_library.md"
  ],
  "upstream_docs": [
    {
      "label": "<human label>",
      "url": "https://...",
      "kind": "rest_overview",
      "verified_on_utc": "2026-02-21"
    }
  ],
  "execution_modes": [
    "offline_fixture"
  ],
  "coverage": {
    "operations": 4,
    "fabricated_cases": 6,
    "known_good_cases": 3,
    "ambiguous_cases": 1,
    "invalid_cases": 1
  },
  "live_mode": {
    "enabled_by_env": "COURTLISTENER_LIVE",
    "required_env": [
      "COURTLISTENER_API_TOKEN"
    ],
    "optional_env": [
      "COURTLISTENER_BASE_URL"
    ],
    "ci_policy": "disabled"
  },
  "notes": "<deterministic note>"
}

المستندات ذات الصلة

• تمت إزالة كتاب تنفيذ الشبكة المخصصة مع القطع الصارم للملف الشخصي الأولي. هذه المكتبة المرجعية هي مواد بحثية فقط حتى يفتح PF-08 ويؤهل عائلة اكتساب الشبكة.
• دليل مرجع الاقتباس القانوني
• دليل الاقتباس القانوني