제약 조건 메타데이터 시스템

목적: 결정론적 AI 생성, CLI 유효성 검사 및 Terraform 스키마 적용을 위한 포괄적인 제약 조건 메타데이터.

확장: x-f5xc-constraints 버전: 3.3.0 상태: 프로덕션 사용 대상: AI 어시스턴트, CLI 도구, Terraform 프로바이더, IDE 확장, API 유효성 검사기

개요

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 생성을 위한 고신뢰도 플래그 (신뢰도 >= 0.9)
`category`	string	그룹화 및 보고를 위한 제약 조건 범주
(constraint keys)	various	최상위 수준에서 평탄화된 유형별 제약 조건 키 (예: `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`	16진수 문자열	`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"):
    # 사용자에게 묻지 않고 자동으로 값 생성
    value = generate_from_pattern(constraint)
else:
    # 제약 조건 힌트와 함께 사용자에게 입력 요청
    value = prompt_user_with_hints(constraint)

디스커버리 통합

소스 우선순위

제약 조건은 3단계 우선순위를 사용하여 조정됩니다:

EXISTING (신뢰도: 1.0)
- 원본 OpenAPI 사양에 명시적으로 설정됨
- 절대 재정의되지 않음
DISCOVERY (신뢰도: 0.99)
- 라이브 F5 XC API 응답에서 추출됨
- x-ves-validation-rules의 유효성 검사 규칙 포함
- 추론된 제약 조건을 재정의함
INFERRED (신뢰도: 0.50-0.95)
- 필드 이름에서 패턴 매칭으로 생성됨
- 가장 낮은 우선순위, 디스커버리 또는 명시적 값에 의해 재정의됨

디스커버리 데이터 소스

디스커버리 제약 조건은 다음에서 추출됩니다:

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
오류 카탈로그: 제약 조건 위반을 나타내는 API 오류 메시지
- “name must be 1-63 characters” → minLength/maxLength
- “port must be between 1 and 65535” → minimum/maximum
응답 유효성 검사: 유효한 값을 보여주는 성공적인 API 응답
- 관찰된 값 범위
- 실제 형식 패턴

도구 통합 가이드

AI 어시스턴트 통합

유효한 리소스 이름 생성:

def generate_resource_name(schema_property):
    constraints = schema_property.get("x-f5xc-constraints", {})

    if not constraints.get("deterministic"):
        # 사용자에게 이름 요청
        return prompt_user("Enter resource name: ")

    # 자동으로 생성
    pattern = constraints.get("pattern")
    max_len = constraints.get("maxLength", 63)

    # 패턴과 일치하는 유효한 이름 생성
    return generate_dns_label(max_length=max_len)

CLI 도구 통합

입력 유효성 검사 제공:

def validate_cli_input(field_name, user_value, constraints):
    if not constraints:
        return True, None

    # 길이 확인 (제약 조건 키는 최상위 수준에 있음)
    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"

    # 패턴 확인
    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,
    }

    // 제약 조건 키는 최상위 수준에 있음 (중첩된 "string" 래퍼 없음)
    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[] = [];

    // 형식별 자동 완성 항목 추가
    if (constraints.format === 'dns-label') {
        items.push({
            label: 'my-service',
            detail: 'Example DNS label',
            kind: CompletionItemKind.Value
        });
    }

    // 유효성 검사 힌트 추가
    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)

패턴	필드 이름 정규식	제약 조건 유형	예시
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)

패턴	필드 이름 정규식	제약 조건 유형	예시
사용자 이름	`\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개 이상의 유형

제약 조건 메타데이터 시스템

목차

개요

커버리지 통계

확장 구조

최상위 필드

필드 설명

제약 조건 유형

문자열 제약 조건

지원되는 형식

배열 제약 조건

숫자 제약 조건

자연어 설명

문자열 형식 제약 조건

숫자 제약 조건

배열 제약 조건

유효성 검사 예시

예시 1: DNS 레이블 이름 유효성 검사

예시 2: 포트 번호 유효성 검사

예시 3: 배열 크기 유효성 검사

신뢰도 점수

점수 해석

결정론적 플래그

디스커버리 통합

소스 우선순위

디스커버리 데이터 소스

도구 통합 가이드

AI 어시스턴트 통합

CLI 도구 통합

Terraform 프로바이더 통합

IDE 확장 통합

부록: 제약 조건 패턴 카탈로그

높은 신뢰도 패턴 (0.95-0.99)

중간 신뢰도 패턴 (0.80-0.94)

지원 및 피드백