نظام البيانات الوصفية للقيود

الغرض: بيانات وصفية شاملة للقيود من أجل توليد الذكاء الاصطناعي الحتمي، والتحقق من صحة واجهة سطر الأوامر (CLI)، وإنفاذ مخطط Terraform.

الامتداد: x-f5xc-constraints الإصدار: 3.3.0 الحالة: في الإنتاج المستهلكون: مساعدو الذكاء الاصطناعي، أدوات CLI، موفرو Terraform، إضافات IDE، مدققو API

---

جدول المحتويات

1. نظرة عامة
2. هيكل الامتداد
3. أنواع القيود
4. أوصاف اللغة الطبيعية
5. أمثلة التحقق من الصحة
6. درجات الثقة
7. تكامل الاكتشاف
8. دليل تكامل الأدوات

---

نظرة عامة

يوفر امتداد x-f5xc-constraints معرفة حتمية بقيود التحقق من صحة الحقول، مما يتيح ما يلي:

• مساعدو الذكاء الاصطناعي: توليد تكوينات صحيحة دون الحاجة إلى إدخال المستخدم لتفاصيل القيود
• أدوات CLI: تقديم تلميحات إدخال دقيقة، والتحقق من الصحة، ورسائل الخطأ
• Terraform: إنفاذ القيود في وقت التخطيط، لا في وقت التطبيق
• إضافات IDE: التحقق من الصحة في الوقت الفعلي واقتراحات الإكمال التلقائي
• مدققو API: التحقق من الصحة قبل الإرسال للحد من أخطاء API

إحصاءات التغطية

• 9,851 قيدًا عبر جميع مواصفات API الخاصة بـ F5 XC
• أكثر من 50 نوعًا من الأنماط (نصوص، مصفوفات، أرقام)
• ثقة بنسبة 95% في الحقول ذات الأولوية العالية (الأسماء، المنافذ، المعرّفات)
• مطابقة ثلاثية المستويات: EXISTING > DISCOVERY > INFERRED

---

هيكل الامتداد

الحقول عالية المستوى

{
  "x-f5xc-constraints": {
    "constraintType": "string|array|number|object",
    "deterministic": true,
    "category": "length|size|range|pattern|character|format",

    "minLength": 1,
    "maxLength": 63,
    "pattern": "^[a-z0-9]+$",

    "metadata": {
      "source": "discovery|inferred|explicit",
      "confidence": 0.95,
      "category": "naming",
      "validatedAt": "2026-01-19T12:00:00Z"
    }
  }
}

أوصاف الحقول

الحقل	النوع	الوصف
constraintType	string	نوع البيانات (string، array، number، object)
deterministic	boolean	علامة الثقة العالية (الثقة >= 0.9) لتوليد الذكاء الاصطناعي
category	string	فئة القيد للتجميع وإعداد التقارير
(مفاتيح القيود)	متنوعة	مفاتيح القيود الخاصة بالنوع مسطّحة على المستوى الأعلى (مثل minLength وmaxItems وminimum)
metadata	object	تتبع المصدر، ودرجة الثقة، وختم زمن التحقق

---

أنواع القيود

قيود النصوص (String)

{
  "constraintType": "string",
  "category": "naming",
  "minLength": 1,
  "maxLength": 63,
  "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
  "characterSet": {
    "allowed": "[a-z0-9-]",
    "restricted": "[^a-z0-9-]",
    "required": "[a-z0-9]",
    "description": "Lowercase alphanumeric with hyphens, not at start/end"
  },
  "format": "dns-label",
  "formatDescription": "RFC 1123 DNS label: lowercase, alphanumeric, hyphens allowed but not at start/end",
  "byteLength": {
    "min": 1,
    "max": 63
  },
  "validation": {
    "rfc": "RFC 1123",
    "standard": "Kubernetes resource naming"
  },
  "metadata": {
    "source": "inferred",
    "confidence": 0.95
  },
  "deterministic": true
}

الصيغ المدعومة

الصيغة	الوصف	مثال
dns-label	تسمية DNS وفق RFC 1123 (1-63 حرفًا)	my-service
fqdn	اسم النطاق المؤهل بالكامل	api.example.com
email	عنوان البريد الإلكتروني وفق RFC 5322	user@example.com
url	URI/URL وفق RFC 3986	https://example.com/api
ipv4	عنوان IPv4	192.168.1.1
ipv6	عنوان IPv6	2001:db8::1
uuid	UUID وفق RFC 4122	550e8400-e29b-41d4-a716-446655440000
date-time	ختم زمني وفق ISO 8601	2026-01-19T12:00:00Z
date	تاريخ وفق ISO 8601	2026-01-19
time	وقت وفق ISO 8601	12:00:00
json	نص JSON (قابل للتحليل)	{"key": "value"}
yaml	نص YAML (قابل للتحليل)	key: value
base64	نص مشفّر بـ Base64	SGVsbG8gV29ybGQ=
hex	نص ست عشري	48656c6c6f
mac-address	عنوان MAC	00:1A:2B:3C:4D:5E
phone	رقم هاتف وفق E.164	+1-555-123-4567

قيود المصفوفات (Array)

{
  "constraintType": "array",
  "category": "collection",
  "minItems": 1,
  "maxItems": 50,
  "uniqueItems": true,
  "metadata": {
    "source": "inferred",
    "confidence": 0.90
  },
  "deterministic": true
}

قيود الأرقام (Numeric)

{
  "constraintType": "number",
  "category": "range",
  "minimum": 1,
  "maximum": 65535,
  "multipleOf": 1,
  "exclusiveMinimum": false,
  "exclusiveMaximum": false,
  "metadata": {
    "source": "inferred",
    "confidence": 0.99
  },
  "deterministic": true
}

---

أوصاف اللغة الطبيعية

قيود صيغة النصوص

تسميات DNS (format: "dns-label"):

• يجب أن تتكون أسماء تسميات DNS من 1 إلى 63 حرفًا أبجديًا رقميًا صغيرًا
• يُسمح بالشرطات لكن ليس في البداية أو النهاية (RFC 1123)
• مثال: my-service، api-gateway، lb-prod-01

عناوين البريد الإلكتروني (format: "email"):

• يجب أن تكون عناوين البريد الإلكتروني صحيحة وفق RFC 5322
• الحد الأقصى 254 حرفًا
• مثال: admin@example.com، api+webhook@service.io

أسماء النطاقات المؤهلة بالكامل (FQDNs) (format: "fqdn"):

• يجب أن تتكون أسماء النطاقات المؤهلة بالكامل من 1 إلى 253 حرفًا
• تسميات DNS مفصولة بنقاط
• مثال: api.example.com، service.production.internal

عناوين URL (format: "url"):

• يجب أن تكون عناوين URL معرّفات موارد موحّدة (URIs) صحيحة وفق RFC 3986
• يجب أن تتضمن المخطط (http/https)
• مثال: https://api.example.com/v1، http://localhost:8080

عناوين IPv4 (format: "ipv4"):

• يجب أن تكون عناوين IPv4 بالتدوين العشري المنقوط
• مثال: 192.168.1.1، 10.0.0.1

المعرّفات الفريدة (UUIDs) (format: "uuid"):

• يجب أن تتبع المعرّفات الفريدة تنسيق RFC 4122
• مثال: 550e8400-e29b-41d4-a716-446655440000

الختوم الزمنية (format: "date-time"):

• يجب أن تكون الختوم الزمنية بتنسيق ISO 8601
• مثال: 2026-01-19T12:00:00Z، 2026-01-19T12:00:00+00:00

قيود الأرقام

أرقام المنافذ:

• يجب أن تكون أرقام المنافذ أعدادًا صحيحة تتراوح بين 1 و65535
• المنافذ القياسية: 80 (HTTP)، 443 (HTTPS)، 22 (SSH)

معرّفات VLAN:

• يجب أن تكون معرّفات VLAN أعدادًا صحيحة تتراوح بين 1 و4094 (معيار 802.1Q)

مهل الانتظار:

• يجب أن تتراوح مهل الانتظار بين 1 و3600 ثانية (حد أقصى ساعة واحدة)

قيود المصفوفات

مجمّعات الأصل (Origin Pools):

• تتطلب مصفوفة مجمّعات الأصل عنصرًا واحدًا على الأقل، بحد أقصى 50 عنصرًا
• يجب أن يكون كل عنصر فريدًا

الوسوم (Tags):

• تسمح مصفوفة الوسوم بـ 0 إلى 100 عنصر
• لا يُشترط أن تكون العناصر فريدة

---

أمثلة التحقق من الصحة

مثال 1: التحقق من صحة اسم تسمية DNS

القيد:

{
  "constraintType": "string",
  "minLength": 1,
  "maxLength": 63,
  "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
  "format": "dns-label",
  "deterministic": true
}

القيم الصحيحة:

• ✅ my-service
• ✅ api-gateway
• ✅ lb-prod-01
• ✅ web

القيم غير الصحيحة:

• ❌ My-Service (الأحرف الكبيرة غير مسموح بها)
• ❌ -my-service (شرطة في البداية)
• ❌ my-service- (شرطة في النهاية)
• ❌ my_service (الشرطة السفلية غير مسموح بها)
• ❌ this-is-a-very-long-name-that-exceeds-the-sixty-three-character-limit (طويل جدًا)

مثال 2: التحقق من صحة رقم المنفذ

القيد:

{
  "constraintType": "number",
  "minimum": 1,
  "maximum": 65535,
  "deterministic": true
}

القيم الصحيحة:

• ✅ 80 (HTTP)
• ✅ 443 (HTTPS)
• ✅ 8080 (HTTP بديل شائع)
• ✅ 65535 (الحد الأقصى للمنفذ)

القيم غير الصحيحة:

• ❌ 0 (أقل من الحد الأدنى)
• ❌ 65536 (أعلى من الحد الأقصى)
• ❌ -1 (سالب)
• ❌ "80" (نص، ليس رقمًا)

مثال 3: التحقق من صحة حجم المصفوفة

القيد:

{
  "constraintType": "array",
  "minItems": 1,
  "maxItems": 50,
  "uniqueItems": true,
  "deterministic": true
}

القيم الصحيحة:

• ✅ ["origin-1"] (عنصر واحد)
• ✅ ["origin-1", "origin-2", "origin-3"] (3 عناصر، جميعها فريدة)

القيم غير الصحيحة:

• ❌ [] (أقل من الحد الأدنى)
• ❌ ["origin-1", "origin-1"] (عناصر مكررة)
• ❌ [مصفوفة بـ 51 عنصرًا] (أعلى من الحد الأقصى)

---

درجات الثقة

تفسير الدرجات

النطاق	التفسير	الاستخدام
0.90-1.00	ثقة عالية	تفعيل العلامة الحتمية، استخدامها لتوليد الذكاء الاصطناعي
0.70-0.89	ثقة متوسطة	استشاري، يُوصى بتأكيد المستخدم
0.50-0.69	ثقة منخفضة	للإعلام فقط، يتطلب التحقق من المستخدم
< 0.50	ثقة منخفضة جدًا	غير مضمّنة في القيود

العلامة الحتمية

تُضبط العلامة البوليانية deterministic عندما:

• تكون درجة الثقة >= 0.9
• يكون النمط قد تم التحقق من صحته مقابل بيانات الاكتشاف، أو
• يطابق النمط معايير راسخة (RFC، ISO، إلخ)

الاستخدام في توليد الذكاء الاصطناعي:

if constraint.get("deterministic"):
    # Generate value automatically without asking user
    value = generate_from_pattern(constraint)
else:
    # Ask user for input with constraint hints
    value = prompt_user_with_hints(constraint)

---

تكامل الاكتشاف

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

تتم مطابقة القيود باستخدام أولوية ثلاثية المستويات:

1. EXISTING (الثقة: 1.0)

   • مضبوط صراحةً في مواصفة OpenAPI الأصلية
   • لا يتم تجاوزه أبدًا

2. DISCOVERY (الثقة: 0.99)

   • مستخرج من استجابات F5 XC API الحيّة
   • يتضمن قواعد التحقق من x-ves-validation-rules
   • يتجاوز القيود المُستنتجة

3. INFERRED (الثقة: 0.50-0.95)

   • مطابَق بالنمط من أسماء الحقول
   • أدنى أولوية، يتم تجاوزه بالاكتشاف أو الصريح

مصادر بيانات الاكتشاف

تُستخرج قيود الاكتشاف من:

1. x-ves-validation-rules: امتدادات التحقق الأصلية لـ F5

   • ves.io.schema.rules.string.max_len ← maxLength
   • ves.io.schema.rules.string.pattern ← pattern
   • ves.io.schema.rules.repeated.max_items ← maxItems

2. كتالوج الأخطاء: رسائل أخطاء API التي تشير إلى انتهاكات القيود

   • “name must be 1-63 characters” ← minLength/maxLength
   • “port must be between 1 and 65535” ← minimum/maximum

3. التحقق من الاستجابات: استجابات API الناجحة التي تُظهر قيمًا صحيحة

   • نطاقات القيم الملاحظة
   • أنماط التنسيق الفعلية

---

دليل تكامل الأدوات

تكامل مساعد الذكاء الاصطناعي

توليد أسماء موارد صحيحة:

def generate_resource_name(schema_property):
    constraints = schema_property.get("x-f5xc-constraints", {})

    if not constraints.get("deterministic"):
        # Ask user for name
        return prompt_user("Enter resource name: ")

    # Generate automatically
    pattern = constraints.get("pattern")
    max_len = constraints.get("maxLength", 63)

    # Generate valid name matching pattern
    return generate_dns_label(max_length=max_len)

تكامل أداة CLI

توفير التحقق من صحة المدخلات:

def validate_cli_input(field_name, user_value, constraints):
    if not constraints:
        return True, None

    # Check length (constraint keys are at top level)
    if "minLength" in constraints and len(user_value) < constraints["minLength"]:
        return False, f"{field_name} must be at least {constraints['minLength']} characters"

    if "maxLength" in constraints and len(user_value) > constraints["maxLength"]:
        return False, f"{field_name} must be at most {constraints['maxLength']} characters"

    # Check pattern
    if "pattern" in constraints:
        import re
        if not re.match(constraints["pattern"], user_value):
            char_set = constraints.get("characterSet", {})
            desc = char_set.get("description", "valid format")
            return False, f"{field_name} must match {desc}"

    return True, None

تكامل موفر Terraform

توليد المخطط:

func generateTerraformSchema(property map[string]interface{}) *schema.Schema {
    constraints := property["x-f5xc-constraints"].(map[string]interface{})
    s := &schema.Schema{
        Type:     schema.TypeString,
        Required: true,
    }

    // Constraint keys are at top level (no nested "string" wrapper)
    if minLen, ok := constraints["minLength"].(float64); ok {
        s.ValidateDiagFunc = validation.StringLenBetween(int(minLen), int(constraints["maxLength"].(float64)))
    }

    if pattern, ok := constraints["pattern"].(string); ok {
        charSet := constraints["characterSet"].(map[string]interface{})
        s.ValidateDiagFunc = validation.StringMatch(regexp.MustCompile(pattern),
            charSet["description"].(string))
    }

    return s
}

تكامل إضافة IDE

الإكمال التلقائي والتحقق من الصحة:

function provideCompletions(field: FieldInfo): CompletionItem[] {
    const constraints = field.schema['x-f5xc-constraints'];
    if (!constraints) return [];

    const items: CompletionItem[] = [];

    // Add format-specific completions
    if (constraints.format === 'dns-label') {
        items.push({
            label: 'my-service',
            detail: 'Example DNS label',
            kind: CompletionItemKind.Value
        });
    }

    // Add validation hint
    if (constraints.deterministic) {
        items.push({
            label: '✨ Auto-generate',
            detail: 'Generate valid value automatically',
            kind: CompletionItemKind.Function,
            command: { command: 'f5xc.generateValue', arguments: [field] }
        });
    }

    return items;
}

---

الملحق: كتالوج أنماط القيود

الأنماط عالية الثقة (0.95-0.99)

النمط	تعبير اسم الحقل	نوع القيد	مثال
تسمية DNS	\bname$	نص (1-63 حرفًا، dns-label)	my-service
مساحة الأسماء	\bnamespace$	نص (1-63 حرفًا، dns-label)	production
المنفذ	\bport$	رقم (1-65535)	443
معرّف VLAN	\b(vlan)?_?id$	رقم (1-4094)	100
UUID	\buuid$	نص (36 حرفًا، تنسيق uuid)	550e8400-...
البريد الإلكتروني	\bemail$	نص (حد أقصى 254 حرفًا، email)	user@example.com
الختم الزمني	\b(timestamp|created_at|updated_at)$	نص (ISO 8601)	2026-01-19T12:00:00Z

الأنماط متوسطة الثقة (0.80-0.94)

النمط	تعبير اسم الحقل	نوع القيد	مثال
اسم المستخدم	\b(user|username)$	نص (1-64 حرفًا، أبجدي رقمي)	admin
الاسم المعروض	\b(display_?)?name$	نص (1-256 حرفًا، نص حر)	My Service
الوصف	\b(comment|description|note)$	نص (حد أقصى 4096 حرفًا)	Service description
المسار	\bpath$	نص (حد أقصى 2048 حرفًا)	/api/v1/resources

---

الدعم والملاحظات

• المشكلات: الإبلاغ عن مشكلات دقة القيود على https://github.com/f5-sales-demo/api-specs-enriched/issues
• التوثيق: التوثيق الكامل لـ API على https://f5-sales-demo.github.io/api-specs-enriched/
• تكامل MCP: راجع مستودع f5xc-api-mcp للاطلاع على أمثلة تكامل خادم MCP

---

الإصدار: 3.3.0 آخر تحديث: 2026-01-19 القيود المُطابَقة: 9,851 تغطية الأنماط: أكثر من 50 نوعًا