コンテンツにスキップ
API Enriched

制約メタデータシステム

目的: 決定論的 AI 生成、CLI バリデーション、および Terraform スキーマ強制のための包括的な制約メタデータ。

拡張子: x-f5xc-constraints バージョン: 3.3.0 ステータス: 本番環境 利用者: AI アシスタント、CLI ツール、Terraform プロバイダー、IDE 拡張機能、API バリデーター

目次

Section titled “目次”
  1. 概要
  2. 拡張構造
  3. 制約タイプ
  4. 自然言語による説明
  5. バリデーション例
  6. 信頼スコア
  7. ディスカバリー統合
  8. ツール統合ガイド

概要

Section titled “概要”

x-f5xc-constraints 拡張は、フィールドバリデーション制約に関する決定論的な知識を提供し、以下を可能にします。

  • AI アシスタント: 制約の詳細についてユーザー入力なしに有効な設定を生成
  • CLI ツール: 正確な入力ヒント、バリデーション、およびエラーメッセージの提供
  • Terraform: プラン時（適用時ではなく）に制約を強制
  • IDE 拡張機能: リアルタイムバリデーションとオートコンプリート候補
  • API バリデーター: API エラーを削減するための送信前バリデーション

カバレッジ統計

Section titled “カバレッジ統計”
  • すべての F5 XC API 仕様にわたる 9,851 件の制約
  • 50 以上のパターンタイプ（文字列、配列、数値）
  • 高優先度フィールド（名前、ポート、識別子）における 95% の信頼度
  • 3 段階の照合: EXISTING > DISCOVERY > INFERRED

拡張構造

Section titled “拡張構造”

トップレベルフィールド

Section titled “トップレベルフィールド”
{
  "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"
    }
  }
}

フィールドの説明

Section titled “フィールドの説明”
フィールド型説明
constraintTypestringデータ型（string、array、number、object）
deterministicbooleanAI 生成用の高信頼度フラグ（信頼度 >= 0.9）
categorystringグループ化およびレポート用の制約カテゴリ
（制約キー）各種トップレベルにフラット化された型固有の制約キー（例: minLength、maxItems、minimum）
metadataobjectソース追跡、信頼度、バリデーションタイムスタンプ

制約タイプ

Section titled “制約タイプ”

文字列制約

Section titled “文字列制約”
{
  "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
}

サポートされるフォーマット

Section titled “サポートされるフォーマット”
フォーマット説明例
dns-labelRFC 1123 DNS ラベル（1-63 文字）my-service
fqdn完全修飾ドメイン名api.example.com
emailRFC 5322 メールアドレスuser@example.com
urlRFC 3986 URI/URLhttps://example.com/api
ipv4IPv4 アドレス192.168.1.1
ipv6IPv6 アドレス2001:db8::1
uuidRFC 4122 UUID550e8400-e29b-41d4-a716-446655440000
date-timeISO 8601 タイムスタンプ2026-01-19T12:00:00Z
dateISO 8601 日付2026-01-19
timeISO 8601 時刻12:00:00
jsonJSON 文字列（解析可能）{"key": "value"}
yamlYAML 文字列（解析可能）key: value
base64Base64 エンコード文字列SGVsbG8gV29ybGQ=
hex16 進数文字列48656c6c6f
mac-addressMAC アドレス00:1A:2B:3C:4D:5E
phoneE.164 電話番号+1-555-123-4567

配列制約

Section titled “配列制約”
{
  "constraintType": "array",
  "category": "collection",
  "minItems": 1,
  "maxItems": 50,
  "uniqueItems": true,
  "metadata": {
    "source": "inferred",
    "confidence": 0.90
  },
  "deterministic": true
}

数値制約

Section titled “数値制約”
{
  "constraintType": "number",
  "category": "range",
  "minimum": 1,
  "maximum": 65535,
  "multipleOf": 1,
  "exclusiveMinimum": false,
  "exclusiveMaximum": false,
  "metadata": {
    "source": "inferred",
    "confidence": 0.99
  },
  "deterministic": true
}

自然言語による説明

Section titled “自然言語による説明”

文字列フォーマット制約

Section titled “文字列フォーマット制約”

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 アドレスはドット区切り 10 進数表記である必要があります
  • 例: 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

数値制約

Section titled “数値制約”

ポート番号:

  • ポート番号は 1 以上 65535 以下の整数である必要があります
  • 標準ポート: 80（HTTP）、443（HTTPS）、22（SSH）

VLAN ID:

  • VLAN ID は 1 以上 4094 以下の整数である必要があります（802.1Q 標準）

タイムアウト:

  • タイムアウトは 1 秒以上 3600 秒以下（最大 1 時間）である必要があります

配列制約

Section titled “配列制約”

オリジンサーバープール:

  • オリジンサーバープールの配列は最低 1 件、最大 50 件のアイテムが必要です
  • 各アイテムは一意である必要があります

タグ:

  • タグ配列は 0-100 件のアイテムを許可します
  • アイテムは一意である必要はありません

バリデーション例

Section titled “バリデーション例”

例 1: DNS ラベル名のバリデーション

Section titled “例 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: ポート番号のバリデーション

Section titled “例 2: ポート番号のバリデーション”

制約:

{
  "constraintType": "number",
  "minimum": 1,
  "maximum": 65535,
  "deterministic": true
}

有効な値:

  • ✅ 80（HTTP）
  • ✅ 443（HTTPS）
  • ✅ 8080（代替 HTTP としてよく使用される）
  • ✅ 65535（最大ポート番号）

無効な値:

  • ❌ 0（最小値未満）
  • ❌ 65536（最大値超過）
  • ❌ -1（負の数）
  • ❌ "80"（文字列、数値ではない）

例 3: 配列サイズのバリデーション

Section titled “例 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 件のアイテムを含む配列]（最大値超過）

信頼スコア

Section titled “信頼スコア”

スコアの解釈

Section titled “スコアの解釈”
範囲解釈使用方法
0.90-1.00高信頼度決定論的フラグ有効、AI 生成に使用
0.70-0.89中信頼度アドバイザリー、ユーザーによる確認を推奨
0.50-0.69低信頼度参考情報のみ、ユーザーによるバリデーションが必要
< 0.50非常に低い制約には含まれない

決定論的フラグ

Section titled “決定論的フラグ”

deterministic ブール値フラグは以下の場合に設定されます。

  • 信頼スコアが 0.9 以上
  • パターンがディスカバリーデータに対してバリデーション済み、または
  • パターンが確立された標準（RFC、ISO 等）と一致する

AI 生成における使用方法:

if constraint.get("deterministic"):
    # ユーザーに確認せずに自動的に値を生成
    value = generate_from_pattern(constraint)
else:
    # 制約のヒントを表示してユーザーに入力を促す
    value = prompt_user_with_hints(constraint)

ディスカバリー統合

Section titled “ディスカバリー統合”

ソースの優先度

Section titled “ソースの優先度”

制約は 3 段階の優先度を使用して照合されます。

  1. EXISTING（信頼度: 1.0）

    • 元の OpenAPI 仕様に明示的に設定済み
    • 上書きされることはない

  2. DISCOVERY（信頼度: 0.99）

    • ライブ F5 XC API レスポンスから抽出
    • x-ves-validation-rules からのバリデーションルールを含む
    • 推論された制約を上書きする

  3. INFERRED（信頼度: 0.50-0.95）

    • フィールド名からパターンマッチング
    • 最も低い優先度、ディスカバリーまたは明示的な設定によって上書きされる

ディスカバリーデータソース

Section titled “ディスカバリーデータソース”

ディスカバリー制約は以下から抽出されます。

  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 レスポンス

    • 観測された値の範囲
    • 実際のフォーマットパターン

ツール統合ガイド

Section titled “ツール統合ガイド”

AI アシスタントの統合

Section titled “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 ツールの統合

Section titled “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 プロバイダーの統合

Section titled “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 拡張機能の統合

Section titled “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;
}

付録: 制約パターンカタログ

Section titled “付録: 制約パターンカタログ”

高信頼度パターン（0.95-0.99）

Section titled “高信頼度パターン（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）

Section titled “中信頼度パターン（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

サポートとフィードバック

Section titled “サポートとフィードバック”

バージョン: 3.3.0 最終更新: 2026-01-19 照合済み制約数: 9,851 パターンカバレッジ: 50 以上のタイプ