مواصفة التحقق

يصف هذا المستند هيكل ومحتويات مواصفة التحقق المنشورة من مشروع api-specs-enriched.

نظرة عامة

تدمج مواصفة التحقق قيود التحقق من صحة API وقيم الإعداد الافتراضية وبيانات تعريف التهيئة في ملف JSON واحد. تُولَّد هذه المواصفة من مواصفات OpenAPI المحسّنة وتُنشر جنبًا إلى جنب معها.

موقع النشر: docs/specifications/api/validation.json

هيكل المواصفة

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "version": "2.1.0",
  "generated_at": "2026-01-17T12:00:00Z",
  "source": "api-specs-enriched",

  "required_fields": { ... },
  "enum_values": { ... },
  "constraints": { ... },
  "patterns": [ ... ],
  "conditional_requirements": { ... },
  "minimum_configurations": { ... },
  "defaults": { ... },
  "extensions": { ... }
}

الأقسام

required_fields

يحدد الحقول المطلوبة لكل نوع عملية لكل مورد.

{
  "required_fields": {
    "common": {
      "all_operations": ["metadata.name", "metadata.namespace"]
    },
    "resources": {
      "origin_pool": {
        "create": ["metadata.name", "metadata.namespace", "spec.origin_servers", "spec.port"],
        "update": ["metadata.name", "metadata.namespace"],
        "minimum_config": ["metadata.name", "metadata.namespace", "spec.origin_servers", "spec.port"]
      }
    }
  }
}

enum_values

يعرّف القيم المسموح بها للحقول المقيّدة.

{
  "enum_values": {
    "loadbalancer_algorithm": {
      "description": "Load balancing algorithm for distributing traffic across origin servers",
      "values": [
        {"value": "ROUND_ROBIN", "description": "Each healthy endpoint selected in round robin order"},
        {"value": "LEAST_REQUEST", "description": "Endpoint with fewest active requests selected"},
        {"value": "RING_HASH", "description": "Consistent hashing using ring hash of endpoint names"},
        {"value": "RANDOM", "description": "Random healthy endpoint selection"},
        {"value": "LB_OVERRIDE", "description": "Hash policy inherited from parent load balancer"}
      ],
      "default": "ROUND_ROBIN"
    }
  }
}

constraints

الإعدادات الافتراضية للتحقق على مستوى النوع والقواعد المستندة إلى الأنماط.

{
  "constraints": {
    "type_defaults": {
      "string": {"minLength": 0, "maxLength": 1024},
      "integer": {"minimum": 0, "maximum": 2147483647}
    }
  }
}

patterns

قواعد التحقق المستندة إلى أنماط أسماء الحقول مع درجات الثقة.

{
  "patterns": [
    {
      "pattern": "\\bport$",
      "constraints": {"minimum": 1, "maximum": 65535},
      "confidence": 0.99,
      "description": "Valid TCP/UDP port range"
    },
    {
      "pattern": "\\bname$",
      "constraints": {
        "minLength": 1,
        "maxLength": 63,
        "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"
      },
      "confidence": 0.90,
      "description": "Kubernetes-style naming convention"
    }
  ]
}

defaults

جميع القيم الافتراضية منظّمة حسب نوع المورد في هيكل موحّد.

{
  "defaults": {
    "description": "All default values organized by resource type",
    "resources": {
      "healthcheck": {
        "server_applied": {
          "jitter": 0,
          "jitter_percent": 0
        },
        "recommended": {
          "timeout": 3,
          "interval": 15,
          "unhealthy_threshold": 1,
          "healthy_threshold": 3,
          "jitter_percent": 30
        },
        "oneof_recommended": {
          "health_check": "http_health_check"
        },
        "nested_recommended": {
          "http_health_check": {
            "path": "/",
            "use_http2": false,
            "expected_status_codes": ["200"],
            "use_origin_server_name": {}
          }
        }
      },
      "origin_pool": {
        "server_applied": {
          "no_tls": {},
          "healthcheck": [],
          "loadbalancer_algorithm": "ROUND_ROBIN",
          "endpoint_selection": "DISTRIBUTED"
        },
        "recommended": {
          "port": 443,
          "connection_timeout": 2000,
          "http_idle_timeout": 300000
        },
        "advanced_options": {
          "connection_timeout": 2000,
          "http_idle_timeout": 300000,
          "same_as_endpoint_port": {},
          "default_circuit_breaker": {},
          "disable_outlier_detection": {}
        },
        "oneof_choices": {
          "port_choice": "port",
          "tls_choice": "no_tls",
          "circuit_breaker_choice": "default_circuit_breaker"
        },
        "ui_vs_server": {
          "loadbalancer_algorithm": {
            "ui_default": "LB_OVERRIDE",
            "server_default": "ROUND_ROBIN",
            "note": "UI preselects LB_OVERRIDE but server applies ROUND_ROBIN if omitted"
          }
        }
      },
      "app_firewall": {
        "server_applied": {
          "allow_all_response_codes": {},
          "default_anonymization": {},
          "monitoring": {}
        }
      }
    }
  }
}

فئات الإعدادات الافتراضية

الفئة	الوصف	المصدر
`server_applied`	القيم التي يطبّقها API عند حذف الحقول	اختبار API المباشر
`recommended`	القيم المُعبّأ مسبقًا في وحدة تحكم F5 XC على الويب	تحليل واجهة المستخدم
`advanced_options`	الإعدادات الافتراضية المتداخلة داخل كائنات advanced_options	اكتشاف API
`oneof_choices`	اختيارات متغير OneOf الافتراضية	سلوك API
`oneof_recommended`	متغيرات OneOf الموصى بها	إعدادات وحدة التحكم الافتراضية
`nested_recommended`	القيم الموصى بها للمخططات المتداخلة	تحليل واجهة المستخدم
`ui_vs_server`	الحالات التي تختلف فيها إعدادات واجهة المستخدم عن إعدادات API الافتراضية	تحليل مقارن

conditional_requirements

الحقول المتنافية وتبعيات الشرط.

{
  "conditional_requirements": {
    "resources": {
      "healthcheck": {
        "mutually_exclusive": [
          {
            "fields": ["spec.http_health_check", "spec.tcp_health_check", "spec.udp_icmp_health_check"],
            "reason": "Choose exactly one health check type"
          }
        ],
        "conditional": []
      }
    }
  }
}

minimum_configurations

الحدّ الأدنى من التهيئات القابلة للتطبيق مع أمثلة عملية.

{
  "minimum_configurations": {
    "resources": {
      "origin_pool": {
        "description": "Backend origin servers for load balancing",
        "example": {
          "metadata": {"name": "backend-pool", "namespace": "default"},
          "spec": {
            "origin_servers": [{"public_name": {"dns_name": "backend1.example.com"}}],
            "port": 8080
          }
        }
      }
    }
  }
}

تعيين امتداد OpenAPI

تُضمّن مواصفات OpenAPI المحسّنة بيانات تعريف التحقق باستخدام هذه الامتدادات:

الامتداد	الغرض	الموقع
`x-f5xc-required-for`	الحقول المطلوبة حسب السياق	خصائص المخطط
`x-f5xc-server-default`	يُشير إلى الإعدادات الافتراضية المطبّقة من الخادم	خصائص المخطط
`x-f5xc-recommended-value`	قيمة افتراضية موصى بها	خصائص المخطط
`x-f5xc-recommended-oneof-variant`	متغير OneOf الموصى به	تعريفات المخطط
`x-f5xc-conditions`	المتطلبات الشرطية	خصائص المخطط
`x-f5xc-minimum-configuration`	أمثلة الحدّ الأدنى من التهيئة	تعريفات المخطط
`x-f5xc-validation`	القيود المستخلصة من الاكتشاف	خصائص المخطط

الوصول إلى البيانات

روابط النشر

المصدر	الرابط
GitHub Pages	`https://f5-sales-demo.github.io/api-specs-enriched/specifications/api/validation.json`
Raw GitHub	`https://raw.githubusercontent.com/f5-sales-demo/api-specs-enriched/main/docs/specifications/api/validation.json`

المسار المحلي

بعد تشغيل خط الأنابيب: docs/specifications/api/validation.json

الإصدار

تتبع مواصفة التحقق الإصدار الدلالي في حقل version:

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

أولوية التوفيق

عند توفير قيود من مصادر متعددة، تكون أولوية التوفيق على النحو التالي:

موجود - القيود في مواصفة OpenAPI الأصلية (الأولوية الأعلى)
اكتشاف - القيود من اكتشاف API المباشر
مُستنتج - القيود من مطابقة الأنماط (الأولوية الأدنى)

الوثائق ذات الصلة

تحسينات Healthcheck - تحسينات مخطط Healthcheck
تحسينات Origin Pool - تحسينات مخطط Origin Pool
CLAUDE.md - تعليمات مساعد الذكاء الاصطناعي
DEVELOPMENT.md - دليل المطور

سجل التغييرات

الإصدار	التاريخ	التغييرات
2.1.2	2026-01-18	إعادة كتابة كمرجع API خالص؛ إضافة فئتَي oneof_recommended وnested_recommended
2.1.0	2026-01-18	هيكل موحّد للإعدادات الافتراضية يحلّ محل الأقسام المتفرقة
2.0.0	2026-01-15	مواصفة التحقق الأولية