ระบบข้อมูลเมตาของข้อจำกัด

วัตถุประสงค์: ข้อมูลเมตาของข้อจำกัดที่ครอบคลุมสำหรับการสร้างด้วย 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: บังคับใช้ข้อจำกัดในขั้นตอน plan ไม่ใช่ apply
• ส่วนขยาย IDE: การตรวจสอบความถูกต้องแบบเรียลไทม์และคำแนะนำการเติมอัตโนมัติ
• ตัวตรวจสอบ API: การตรวจสอบความถูกต้องก่อนส่งเพื่อลดข้อผิดพลาด API

สถิติการครอบคลุม

• ข้อจำกัด 9,851 รายการ ครอบคลุม API spec ทั้งหมดของ F5 XC
• รูปแบบมากกว่า 50 ประเภท (string, array, numeric)
• ความเชื่อมั่น 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	แฟล็กความเชื่อมั่นสูง (ความเชื่อมั่น >= 0.9) สำหรับการสร้าง AI
category	string	หมวดหมู่ข้อจำกัดสำหรับการจัดกลุ่มและรายงาน
(constraint keys)	various	คีย์ข้อจำกัดเฉพาะประเภทที่ถูก flatten ไว้ที่ระดับบนสุด (เช่น 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 label ตาม RFC 1123 (1-63 ตัวอักษร)	my-service
fqdn	ชื่อโดเมนแบบเต็ม (Fully qualified domain name)	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
}

---

คำอธิบายภาษาธรรมชาติ

ข้อจำกัดรูปแบบ String

DNS Labels (format: "dns-label"):

• ชื่อ DNS label ต้องมีตัวอักษรพิมพ์เล็กและตัวเลข 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"):

• ชื่อโดเมนแบบเต็ม (Fully Qualified Domain Names) ต้องมี 1-253 ตัวอักษร
• DNS labels ที่คั่นด้วยจุด
• ตัวอย่าง: api.example.com, service.production.internal

URLs (format: "url"):

• URL ต้องเป็น URI ที่ถูกต้องตาม RFC 3986
• ต้องมี scheme (http/https)
• ตัวอย่าง: https://api.example.com/v1, http://localhost:8080

ที่อยู่ IPv4 (format: "ipv4"):

• ที่อยู่ IPv4 ต้องอยู่ในรูปแบบ dotted-decimal
• ตัวอย่าง: 192.168.1.1, 10.0.0.1

UUIDs (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

ข้อจำกัด Numeric

หมายเลขพอร์ต:

• หมายเลขพอร์ตต้องเป็นจำนวนเต็มระหว่าง 1 ถึง 65535
• พอร์ตมาตรฐาน: 80 (HTTP), 443 (HTTPS), 22 (SSH)

VLAN ID:

• VLAN ID ต้องเป็นจำนวนเต็มระหว่าง 1 ถึง 4094 (มาตรฐาน 802.1Q)

Timeouts:

• Timeouts ต้องอยู่ระหว่าง 1-3600 วินาที (สูงสุด 1 ชั่วโมง)

ข้อจำกัด Array

Origin Pools:

• Array ของ origin pools ต้องมีอย่างน้อย 1 รายการ สูงสุด 50 รายการ
• แต่ละรายการต้องไม่ซ้ำกัน

Tags:

• Array ของ tags อนุญาต 0-100 รายการ
• รายการไม่จำเป็นต้องไม่ซ้ำกัน

---

ตัวอย่างการตรวจสอบความถูกต้อง

ตัวอย่างที่ 1: การตรวจสอบความถูกต้องของชื่อ DNS Label

ข้อจำกัด:

{
  "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 (ไม่อนุญาตให้ใช้ underscore)
• ❌ 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" (string ไม่ใช่ number)

ตัวอย่างที่ 3: การตรวจสอบความถูกต้องของขนาด Array

ข้อจำกัด:

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

ค่าที่ถูกต้อง:

• ✅ ["origin-1"] (1 รายการ)
• ✅ ["origin-1", "origin-2", "origin-3"] (3 รายการ, ทั้งหมดไม่ซ้ำกัน)

ค่าที่ไม่ถูกต้อง:

• ❌ [] (ต่ำกว่าจำนวนขั้นต่ำ)
• ❌ ["origin-1", "origin-1"] (รายการซ้ำกัน)
• ❌ [array ที่มี 51 รายการ] (สูงกว่าจำนวนสูงสุด)

---

คะแนนความเชื่อมั่น

การตีความคะแนน

ช่วง	การตีความ	การใช้งาน
0.90-1.00	ความเชื่อมั่นสูง	เปิดใช้งานแฟล็ก deterministic, ใช้สำหรับการสร้าง AI
0.70-0.89	ความเชื่อมั่นปานกลาง	เป็นคำแนะนำ, แนะนำให้ผู้ใช้ยืนยัน
0.50-0.69	ความเชื่อมั่นต่ำ	เพื่อให้ข้อมูลเท่านั้น, ต้องให้ผู้ใช้ตรวจสอบ
< 0.50	ต่ำมาก	ไม่รวมอยู่ในข้อจำกัด

แฟล็ก Deterministic

แฟล็ก boolean 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 spec ต้นฉบับ
   • ไม่มีการแทนที่

2. DISCOVERY (ความเชื่อมั่น: 0.99)

   • ดึงมาจากการตอบสนอง F5 XC API จริง
   • รวมถึงกฎการตรวจสอบจาก x-ves-validation-rules
   • แทนที่ข้อจำกัดที่อนุมานได้

3. INFERRED (ความเชื่อมั่น: 0.50-0.95)

   • จับคู่รูปแบบจากชื่อฟิลด์
   • ลำดับความสำคัญต่ำสุด, ถูกแทนที่โดย discovery หรือ explicit

แหล่งข้อมูลการค้นพบ

ข้อจำกัดการค้นพบถูกดึงมาจาก:

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. Error Catalog: ข้อความแสดงข้อผิดพลาด API ที่ระบุการละเมิดข้อจำกัด

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

3. Response Validation: การตอบสนอง 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 Provider

การสร้างสคีมา:

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 Label	\bname$	String (1-63 ตัวอักษร, dns-label)	my-service
Namespace	\bnamespace$	String (1-63 ตัวอักษร, dns-label)	production
Port	\bport$	Number (1-65535)	443
VLAN ID	\b(vlan)?_?id$	Number (1-4094)	100
UUID	\buuid$	String (36 ตัวอักษร, รูปแบบ uuid)	550e8400-...
Email	\bemail$	String (สูงสุด 254 ตัวอักษร, email)	user@example.com
Timestamp	\b(timestamp|created_at|updated_at)$	String (ISO 8601)	2026-01-19T12:00:00Z

รูปแบบที่มีความเชื่อมั่นปานกลาง (0.80-0.94)

รูปแบบ	ชื่อฟิลด์ Regex	ประเภทข้อจำกัด	ตัวอย่าง
Username	\b(user|username)$	String (1-64 ตัวอักษร, alphanumeric)	admin
Display Name	\b(display_?)?name$	String (1-256 ตัวอักษร, free text)	My Service
Description	\b(comment|description|note)$	String (สูงสุด 4096 ตัวอักษร)	Service description
Path	\bpath$	String (สูงสุด 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: ดู repository f5xc-api-mcp สำหรับตัวอย่างการผสานรวม MCP server

---

เวอร์ชัน: 3.3.0 อัปเดตล่าสุด: 2026-01-19 ข้อจำกัดที่ประสานแล้ว: 9,851 การครอบคลุมรูปแบบ: มากกว่า 50 ประเภท