ข้อกำหนดการตรวจสอบ

เอกสารนี้อธิบายโครงสร้างและเนื้อหาของข้อกำหนดการตรวจสอบที่เผยแพร่โดยโปรเจกต์ api-specs-enriched

ภาพรวม

ข้อกำหนดการตรวจสอบรวบรวมข้อจำกัดการตรวจสอบ API ค่าเริ่มต้น และข้อมูลเมตาของการกำหนดค่าไว้ในไฟล์ JSON เดียว ข้อกำหนดนี้ถูกสร้างจาก OpenAPI specs ที่เพิ่มประสิทธิภาพแล้วและเผยแพร่ควบคู่กัน

ตำแหน่งที่เผยแพร่: 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 web console	การวิเคราะห์ UI
advanced_options	ค่าเริ่มต้นที่ซ้อนกันภายในออบเจกต์ advanced_options	การค้นพบ API
oneof_choices	การเลือก OneOf variant เริ่มต้น	พฤติกรรม API
oneof_recommended	OneOf variants ที่แนะนำ	ค่าเริ่มต้นของคอนโซล
nested_recommended	ค่าที่แนะนำสำหรับ schema ที่ซ้อนกัน	การวิเคราะห์ 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 Extension

OpenAPI specs ที่เพิ่มประสิทธิภาพแล้วฝังข้อมูลเมตาการตรวจสอบโดยใช้ extensions เหล่านี้:

Extension	วัตถุประสงค์	ตำแหน่ง
x-f5xc-required-for	ฟิลด์ที่จำเป็นตามบริบท	Schema properties
x-f5xc-server-default	ทำเครื่องหมายค่าเริ่มต้นที่ server นำไปใช้	Schema properties
x-f5xc-recommended-value	ค่าเริ่มต้นที่แนะนำ	Schema properties
x-f5xc-recommended-oneof-variant	OneOf variant ที่แนะนำ	Schema definitions
x-f5xc-conditions	ข้อกำหนดตามเงื่อนไข	Schema properties
x-f5xc-minimum-configuration	ตัวอย่างการกำหนดค่าขั้นต่ำ	Schema definitions
x-f5xc-validation	ข้อจำกัดที่ได้จากการค้นพบ	Schema properties

การเข้าถึงข้อมูล

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

เส้นทางในเครื่อง

หลังจากรัน pipeline: docs/specifications/api/validation.json

การกำหนดเวอร์ชัน

ข้อกำหนดการตรวจสอบใช้ semantic versioning ในฟิลด์ version:

ประเภทการเปลี่ยนแปลง	การเพิ่มเวอร์ชัน	ตัวอย่าง
การเปลี่ยนแปลงโครงสร้างที่ทำให้ระบบเดิมทำงานไม่ได้	Major	การเปลี่ยนชื่อฟิลด์, การลบส่วนต่างๆ
กฎการตรวจสอบหรือทรัพยากรใหม่	Minor	ค่าเริ่มต้นทรัพยากรใหม่
การแก้ไขข้อผิดพลาดหรืออัปเดตคำอธิบาย	Patch	การแก้ไขคำผิด

ลำดับความสำคัญในการประสาน

เมื่อแหล่งข้อมูลหลายแหล่งให้ข้อจำกัด ลำดับความสำคัญในการประสานคือ:

1. Existing - ข้อจำกัดใน OpenAPI spec ต้นฉบับ (ความสำคัญสูงสุด)
2. Discovery - ข้อจำกัดจากการค้นพบ API แบบสด
3. Inferred - ข้อจำกัดจากการจับคู่รูปแบบ (ความสำคัญต่ำสุด)

เอกสารที่เกี่ยวข้อง

• Healthcheck Enhancements - การเพิ่มประสิทธิภาพ schema ของ Healthcheck
• Origin Pool Enhancements - การเพิ่มประสิทธิภาพ schema ของ Origin Pool
• CLAUDE.md - คำแนะนำสำหรับผู้ช่วย AI
• DEVELOPMENT.md - คู่มือสำหรับนักพัฒนา

บันทึกการเปลี่ยนแปลง

เวอร์ชัน	วันที่	การเปลี่ยนแปลง
2.1.2	2026-01-18	เขียนใหม่เป็น API reference แบบบริสุทธิ์; เพิ่มหมวดหมู่ oneof_recommended และ nested_recommended
2.1.0	2026-01-18	โครงสร้าง defaults แบบรวมที่แทนที่ส่วนที่กระจัดกระจาย
2.0.0	2026-01-15	ข้อกำหนดการตรวจสอบเริ่มต้น