सत्यापन विनिर्देश

यह दस्तावेज़ 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 वेब कंसोल में पूर्व-भरे मान	UI विश्लेषण
`advanced_options`	advanced_options ऑब्जेक्ट के भीतर नेस्टेड डिफ़ॉल्ट	API खोज
`oneof_choices`	डिफ़ॉल्ट OneOf वैरिएंट चयन	API व्यवहार
`oneof_recommended`	अनुशंसित OneOf वैरिएंट	कंसोल डिफ़ॉल्ट
`nested_recommended`	नेस्टेड स्कीमा के लिए अनुशंसित मान	UI विश्लेषण
`ui_vs_server`	ऐसे मामले जहाँ UI डिफ़ॉल्ट 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`	खोज-व्युत्पन्न बाधाएँ	स्कीमा गुण

डेटा पहुँच

प्रकाशन URL

स्रोत	URL
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 फ़ील्ड में सिमेंटिक वर्शनिंग का अनुसरण करता है:

परिवर्तन प्रकार	संस्करण वृद्धि	उदाहरण
संरचना में ब्रेकिंग परिवर्तन	Major	फ़ील्ड का नाम बदलना, अनुभाग हटाना
नए सत्यापन नियम या संसाधन	Minor	नए संसाधन डिफ़ॉल्ट
बग फ़िक्स या विवरण अपडेट	Patch	टाइपो सुधार

समाधान प्राथमिकता

जब एकाधिक स्रोत बाधाएँ प्रदान करते हैं, तो समाधान प्राथमिकता इस प्रकार है:

Existing - मूल OpenAPI विनिर्देश में बाधाएँ (सर्वोच्च प्राथमिकता)
Discovery - लाइव API खोज से बाधाएँ
Inferred - पैटर्न मिलान से बाधाएँ (न्यूनतम प्राथमिकता)

परिवर्तन लॉग

संस्करण	तिथि	परिवर्तन
2.1.2	2026-01-18	शुद्ध API संदर्भ के रूप में पुनर्लिखित; oneof_recommended और nested_recommended श्रेणियाँ जोड़ी गईं
2.1.0	2026-01-18	खंडित अनुभागों को प्रतिस्थापित करने वाली एकीकृत डिफ़ॉल्ट संरचना
2.0.0	2026-01-15	प्रारंभिक सत्यापन विनिर्देश