बाधा मेटाडेटा प्रणाली

उद्देश्य: निर्धारक AI जनरेशन, CLI सत्यापन, और Terraform स्कीमा प्रवर्तन के लिए व्यापक बाधा मेटाडेटा।

एक्सटेंशन: x-f5xc-constraints संस्करण: 3.3.0 स्थिति: प्रोडक्शन उपभोक्ता: AI सहायक, CLI उपकरण, Terraform प्रोवाइडर, IDE एक्सटेंशन, API सत्यापनकर्ता

---

विषय-सूची

1. अवलोकन
2. एक्सटेंशन संरचना
3. बाधा प्रकार
4. प्राकृतिक भाषा विवरण
5. सत्यापन उदाहरण
6. विश्वास स्कोर
7. डिस्कवरी एकीकरण
8. उपकरण एकीकरण मार्गदर्शिका

---

अवलोकन

x-f5xc-constraints एक्सटेंशन फ़ील्ड सत्यापन बाधाओं के बारे में निर्धारक ज्ञान प्रदान करता है, जो निम्नलिखित को सक्षम बनाता है:

• AI सहायक: बाधा विवरण के लिए उपयोगकर्ता इनपुट के बिना वैध कॉन्फ़िगरेशन तैयार करें
• CLI उपकरण: सटीक इनपुट संकेत, सत्यापन, और त्रुटि संदेश प्रदान करें
• Terraform: प्लान टाइम पर बाधाएं लागू करें, अप्लाई टाइम पर नहीं
• IDE एक्सटेंशन: रीयल-टाइम सत्यापन और ऑटोकम्पलीट सुझाव
• API सत्यापनकर्ता: API त्रुटियों को कम करने के लिए प्री-सबमिशन सत्यापन

कवरेज आँकड़े

• सभी F5 XC API विनिर्देश में 9,851 बाधाएं
• 50+ पैटर्न प्रकार (स्ट्रिंग, ऐरे, न्यूमेरिक)
• उच्च-प्राथमिकता फ़ील्ड (नाम, पोर्ट, पहचानकर्ता) पर 95% विश्वास
• 3-स्तरीय समाधान: 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	AI जनरेशन के लिए उच्च-विश्वास फ्लैग (confidence >= 0.9)
category	string	समूहीकरण और रिपोर्टिंग के लिए बाधा श्रेणी
(constraint keys)	विभिन्न	शीर्ष स्तर पर फ्लैट किए गए प्रकार-विशिष्ट बाधा कुंजियाँ (जैसे minLength, maxItems, minimum)
metadata	object	स्रोत ट्रैकिंग, विश्वास, सत्यापन टाइमस्टैम्प

---

बाधा प्रकार

स्ट्रिंग बाधाएं

{
  "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	RFC 1123 DNS लेबल (1-63 अक्षर)	my-service
fqdn	पूर्ण योग्य डोमेन नाम	api.example.com
email	RFC 5322 ईमेल पता	user@example.com
url	RFC 3986 URI/URL	https://example.com/api
ipv4	IPv4 पता	192.168.1.1
ipv6	IPv6 पता	2001:db8::1
uuid	RFC 4122 UUID	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

ऐरे बाधाएं

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

न्यूमेरिक बाधाएं

{
  "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

FQDN (format: "fqdn"):

• पूर्ण योग्य डोमेन नाम 1-253 अक्षर होने चाहिए
• डॉट-विभाजित DNS लेबल
• उदाहरण: api.example.com, service.production.internal

URL (format: "url"):

• URL RFC 3986 के अनुसार वैध URI होने चाहिए
• स्कीम (http/https) शामिल होना चाहिए
• उदाहरण: https://api.example.com/v1, http://localhost:8080

IPv4 पते (format: "ipv4"):

• IPv4 पते डॉटेड-डेसिमल नोटेशन में होने चाहिए
• उदाहरण: 192.168.1.1, 10.0.0.1

UUID (format: "uuid"):

• 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 ID:

• VLAN ID 1 से 4094 के बीच पूर्णांक होने चाहिए (802.1Q मानक)

टाइमआउट:

• टाइमआउट 1-3600 सेकंड होने चाहिए (अधिकतम 1 घंटा)

ऐरे बाधाएं

ऑरिजिन पूल:

• ऑरिजिन पूल के ऐरे में कम से कम 1 आइटम, अधिकतम 50 आइटम आवश्यक हैं
• प्रत्येक आइटम अद्वितीय होना चाहिए

टैग:

• टैग ऐरे में 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"] (1 आइटम)
• ✅ ["origin-1", "origin-2", "origin-3"] (3 आइटम, सभी अद्वितीय)

अवैध मान:

• ❌ [] (न्यूनतम से कम)
• ❌ ["origin-1", "origin-1"] (डुप्लीकेट आइटम)
• ❌ [51 आइटम वाला ऐरे] (अधिकतम से अधिक)

---

विश्वास स्कोर

स्कोर व्याख्या

रेंज	व्याख्या	उपयोग
0.90-1.00	उच्च विश्वास	निर्धारक फ्लैग सक्षम, AI जनरेशन के लिए उपयोग करें
0.70-0.89	मध्यम विश्वास	सलाहकार, उपयोगकर्ता पुष्टि की अनुशंसा करें
0.50-0.69	कम विश्वास	केवल सूचनात्मक, उपयोगकर्ता सत्यापन आवश्यक
< 0.50	बहुत कम	बाधाओं में शामिल नहीं

निर्धारक फ्लैग

deterministic बूलियन फ्लैग तब सेट किया जाता है जब:

• विश्वास स्कोर >= 0.9 हो
• पैटर्न को डिस्कवरी डेटा के विरुद्ध सत्यापित किया गया हो, या
• पैटर्न सुस्थापित मानकों (RFC, ISO, आदि) से मेल खाता हो

AI जनरेशन में उपयोग:

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)

---

डिस्कवरी एकीकरण

स्रोत प्राथमिकता

बाधाओं को 3-स्तरीय प्राथमिकता का उपयोग करके समाधान किया जाता है:

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 प्रतिक्रियाएं जो वैध मान प्रदर्शित करती हैं

   • अवलोकित मान रेंज
   • वास्तविक फॉर्मेट पैटर्न

---

उपकरण एकीकरण मार्गदर्शिका

AI सहायक एकीकरण

वैध संसाधन नाम तैयार करें:

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)

पैटर्न	फ़ील्ड नाम Regex	बाधा प्रकार	उदाहरण
DNS लेबल	\bname$	स्ट्रिंग (1-63 अक्षर, dns-label)	my-service
नेमस्पेस	\bnamespace$	स्ट्रिंग (1-63 अक्षर, dns-label)	production
पोर्ट	\bport$	नंबर (1-65535)	443
VLAN ID	\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)

पैटर्न	फ़ील्ड नाम Regex	बाधा प्रकार	उदाहरण
उपयोगकर्ता नाम	\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 पर बाधा सटीकता संबंधी समस्याएं रिपोर्ट करें
• दस्तावेज़ीकरण: https://f5-sales-demo.github.io/api-specs-enriched/ पर पूर्ण API दस्तावेज़ीकरण
• MCP एकीकरण: MCP सर्वर एकीकरण उदाहरणों के लिए f5xc-api-mcp रिपॉजिटरी देखें

---

संस्करण: 3.3.0 अंतिम अपडेट: 2026-01-19 बाधाएं समाधान: 9,851 पैटर्न कवरेज: 50+ प्रकार