Sistema de Metadados de Restrições

Finalidade: Metadados abrangentes de restrições para geração determinística por IA, validação via CLI e aplicação de esquemas Terraform.

Extensão: x-f5xc-constraints Versão: 3.3.0 Status: Produção Consumidores: Assistentes de IA, ferramentas CLI, provedores Terraform, extensões de IDE, validadores de API

Visão Geral

A extensão x-f5xc-constraints fornece conhecimento determinístico sobre restrições de validação de campos, habilitando:

Assistentes de IA: Gerar configurações válidas sem necessitar de entrada do usuário para detalhes de restrições
Ferramentas CLI: Fornecer dicas de entrada precisas, validação e mensagens de erro
Terraform: Aplicar restrições no momento do plano, não no momento da execução
Extensões de IDE: Validação em tempo real e sugestões de autocompletar
Validadores de API: Validação pré-envio para reduzir erros de API

Estatísticas de Cobertura

9.851 restrições em todas as especificações da API F5 XC
Mais de 50 tipos de padrões (string, array, numérico)
95% de confiança nos campos de alta prioridade (nomes, portas, identificadores)
Reconciliação em 3 camadas: EXISTING > DISCOVERY > INFERRED

Estrutura da Extensão

Campos de Nível Superior

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

Descrições dos Campos

Campo	Tipo	Descrição
`constraintType`	string	Tipo de dado (string, array, number, object)
`deterministic`	boolean	Sinalizador de alta confiança (confiança >= 0,9) para geração por IA
`category`	string	Categoria de restrição para agrupamento e relatórios
(chaves de restrição)	variado	Chaves de restrição específicas do tipo niveladas no topo (ex.: `minLength`, `maxItems`, `minimum`)
`metadata`	object	Rastreamento de origem, confiança, carimbo de data/hora de validação

Tipos de Restrição

Restrições de 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
}

Formatos Suportados

Formato	Descrição	Exemplo
`dns-label`	Rótulo DNS RFC 1123 (1-63 caracteres)	`my-service`
`fqdn`	Nome de domínio totalmente qualificado	`api.example.com`
`email`	Endereço de e-mail RFC 5322	`user@example.com`
`url`	URI/URL RFC 3986	`https://example.com/api`
`ipv4`	Endereço IPv4	`192.168.1.1`
`ipv6`	Endereço IPv6	`2001:db8::1`
`uuid`	UUID RFC 4122	`550e8400-e29b-41d4-a716-446655440000`
`date-time`	Carimbo de data/hora ISO 8601	`2026-01-19T12:00:00Z`
`date`	Data ISO 8601	`2026-01-19`
`time`	Hora ISO 8601	`12:00:00`
`json`	String JSON (analisável)	`{"key": "value"}`
`yaml`	String YAML (analisável)	`key: value`
`base64`	String codificada em Base64	`SGVsbG8gV29ybGQ=`
`hex`	String hexadecimal	`48656c6c6f`
`mac-address`	Endereço MAC	`00:1A:2B:3C:4D:5E`
`phone`	Número de telefone E.164	`+1-555-123-4567`

Restrições de Array

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

Restrições Numéricas

{
  "constraintType": "number",
  "category": "range",
  "minimum": 1,
  "maximum": 65535,
  "multipleOf": 1,
  "exclusiveMinimum": false,
  "exclusiveMaximum": false,
  "metadata": {
    "source": "inferred",
    "confidence": 0.99
  },
  "deterministic": true
}

Descrições em Linguagem Natural

Restrições de Formato de String

Rótulos DNS (format: "dns-label"):

Os nomes de rótulos DNS devem ter de 1 a 63 caracteres alfanuméricos minúsculos
Hífens são permitidos, mas não no início ou no fim (RFC 1123)
Exemplo: my-service, api-gateway, lb-prod-01

Endereços de E-mail (format: "email"):

Os endereços de e-mail devem ser válidos conforme RFC 5322
Máximo de 254 caracteres
Exemplo: admin@example.com, api+webhook@service.io

FQDNs (format: "fqdn"):

Os Nomes de Domínio Totalmente Qualificados devem ter de 1 a 253 caracteres
Rótulos DNS separados por ponto
Exemplo: api.example.com, service.production.internal

URLs (format: "url"):

As URLs devem ser URIs válidas conforme RFC 3986
Devem incluir esquema (http/https)
Exemplo: https://api.example.com/v1, http://localhost:8080

Endereços IPv4 (format: "ipv4"):

Os endereços IPv4 devem estar em notação decimal com pontos
Exemplo: 192.168.1.1, 10.0.0.1

UUIDs (format: "uuid"):

Os UUIDs devem seguir o formato RFC 4122
Exemplo: 550e8400-e29b-41d4-a716-446655440000

Carimbos de Data/Hora (format: "date-time"):

Os carimbos de data/hora devem estar no formato ISO 8601
Exemplo: 2026-01-19T12:00:00Z, 2026-01-19T12:00:00+00:00

Restrições Numéricas

Números de Porta:

Os números de porta devem ser inteiros entre 1 e 65535
Portas padrão: 80 (HTTP), 443 (HTTPS), 22 (SSH)

IDs de VLAN:

Os IDs de VLAN devem ser inteiros entre 1 e 4094 (padrão 802.1Q)

Timeouts:

Os timeouts devem ser de 1 a 3600 segundos (máximo de 1 hora)

Restrições de Array

Pools de Origem:

O array de pools de origem requer pelo menos 1 item, com máximo de 50 itens
Cada item deve ser único

Tags:

O array de tags permite de 0 a 100 itens
Os itens não precisam ser únicos

Exemplos de Validação

Exemplo 1: Validação de Nome de Rótulo DNS

Restrição:

{
  "constraintType": "string",
  "minLength": 1,
  "maxLength": 63,
  "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
  "format": "dns-label",
  "deterministic": true
}

Valores Válidos:

✅ my-service
✅ api-gateway
✅ lb-prod-01
✅ web

Valores Inválidos:

❌ My-Service (maiúsculas não são permitidas)
❌ -my-service (hífen no início)
❌ my-service- (hífen no fim)
❌ my_service (sublinhado não é permitido)
❌ this-is-a-very-long-name-that-exceeds-the-sixty-three-character-limit (muito longo)

Exemplo 2: Validação de Número de Porta

Restrição:

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

Valores Válidos:

✅ 80 (HTTP)
✅ 443 (HTTPS)
✅ 8080 (HTTP alternativo comum)
✅ 65535 (porta máxima)

Valores Inválidos:

❌ 0 (abaixo do mínimo)
❌ 65536 (acima do máximo)
❌ -1 (negativo)
❌ "80" (string, não número)

Exemplo 3: Validação de Tamanho de Array

Restrição:

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

Valores Válidos:

✅ ["origin-1"] (1 item)
✅ ["origin-1", "origin-2", "origin-3"] (3 itens, todos únicos)

Valores Inválidos:

❌ [] (abaixo do mínimo)
❌ ["origin-1", "origin-1"] (itens duplicados)
❌ [array com 51 itens] (acima do máximo)

Pontuações de Confiança

Interpretação das Pontuações

Faixa	Interpretação	Uso
0,90-1,00	Alta confiança	Sinalizador determinístico habilitado, usar para geração por IA
0,70-0,89	Média confiança	Consultivo, recomenda confirmação do usuário
0,50-0,69	Baixa confiança	Apenas informativo, requer validação do usuário
< 0,50	Muito baixa	Não incluído nas restrições

Sinalizador Determinístico

O sinalizador booleano deterministic é definido quando:

A pontuação de confiança é >= 0,9
O padrão foi validado contra dados de discovery OU
O padrão corresponde a padrões bem estabelecidos (RFC, ISO, etc.)

Uso na geração por IA:

if constraint.get("deterministic"):
    # Gerar valor automaticamente sem perguntar ao usuário
    value = generate_from_pattern(constraint)
else:
    # Solicitar entrada do usuário com dicas de restrição
    value = prompt_user_with_hints(constraint)

Integração com Discovery

Prioridade de Origem

As restrições são reconciliadas usando prioridade em 3 camadas:

EXISTING (Confiança: 1,0)
- Definido explicitamente na especificação OpenAPI original
- Nunca sobrescrito
DISCOVERY (Confiança: 0,99)
- Extraído de respostas da API F5 XC em produção
- Inclui regras de validação de x-ves-validation-rules
- Substitui restrições inferidas
INFERRED (Confiança: 0,50-0,95)
- Correspondido por padrões a partir de nomes de campos
- Menor prioridade, substituído por discovery ou explícito

Fontes de Dados de Discovery

As restrições de discovery são extraídas de:

x-ves-validation-rules: Extensões nativas de validação F5
- ves.io.schema.rules.string.max_len → maxLength
- ves.io.schema.rules.string.pattern → pattern
- ves.io.schema.rules.repeated.max_items → maxItems
Catálogo de Erros: Mensagens de erro da API indicando violações de restrição
- “name must be 1-63 characters” → minLength/maxLength
- “port must be between 1 and 65535” → minimum/maximum
Validação de Respostas: Respostas bem-sucedidas da API demonstrando valores válidos
- Intervalos de valores observados
- Padrões de formato reais

Guia de Integração com Ferramentas

Integração com Assistente de IA

Gerar nomes de recursos válidos:

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

    if not constraints.get("deterministic"):
        # Solicitar nome ao usuário
        return prompt_user("Enter resource name: ")

    # Gerar automaticamente
    pattern = constraints.get("pattern")
    max_len = constraints.get("maxLength", 63)

    # Gerar nome válido correspondente ao padrão
    return generate_dns_label(max_length=max_len)

Integração com Ferramentas CLI

Fornecer validação de entrada:

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

    # Verificar comprimento (as chaves de restrição estão no nível superior)
    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"

    # Verificar padrão
    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

Integração com Provedor Terraform

Geração de esquema:

func generateTerraformSchema(property map[string]interface{}) *schema.Schema {
    constraints := property["x-f5xc-constraints"].(map[string]interface{})
    s := &schema.Schema{
        Type:     schema.TypeString,
        Required: true,
    }

    // As chaves de restrição estão no nível superior (sem wrapper "string" aninhado)
    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
}

Integração com Extensão de IDE

Autocompletar e validação:

function provideCompletions(field: FieldInfo): CompletionItem[] {
    const constraints = field.schema['x-f5xc-constraints'];
    if (!constraints) return [];

    const items: CompletionItem[] = [];

    // Adicionar completions específicos de formato
    if (constraints.format === 'dns-label') {
        items.push({
            label: 'my-service',
            detail: 'Example DNS label',
            kind: CompletionItemKind.Value
        });
    }

    // Adicionar dica de validação
    if (constraints.deterministic) {
        items.push({
            label: '✨ Auto-generate',
            detail: 'Generate valid value automatically',
            kind: CompletionItemKind.Function,
            command: { command: 'f5xc.generateValue', arguments: [field] }
        });
    }

    return items;
}

Apêndice: Catálogo de Padrões de Restrição

Padrões de Alta Confiança (0,95-0,99)

Padrão	Regex do Nome do Campo	Tipo de Restrição	Exemplo
Rótulo DNS	`\bname$`	String (1-63 caracteres, dns-label)	`my-service`
Namespace	`\bnamespace$`	String (1-63 caracteres, dns-label)	`production`
Porta	`\bport$`	Número (1-65535)	`443`
ID de VLAN	`\b(vlan)?_?id$`	Número (1-4094)	`100`
UUID	`\buuid$`	String (36 caracteres, formato uuid)	`550e8400-...`
E-mail	`\bemail$`	String (máx. 254 caracteres, email)	`user@example.com`
Carimbo de Data/Hora	`\b(timestamp\|created_at\|updated_at)$`	String (ISO 8601)	`2026-01-19T12:00:00Z`

Padrões de Média Confiança (0,80-0,94)

Padrão	Regex do Nome do Campo	Tipo de Restrição	Exemplo
Nome de Usuário	`\b(user\|username)$`	String (1-64 caracteres, alfanumérico)	`admin`
Nome de Exibição	`\b(display_?)?name$`	String (1-256 caracteres, texto livre)	`My Service`
Descrição	`\b(comment\|description\|note)$`	String (máx. 4096 caracteres)	`Service description`
Caminho	`\bpath$`	String (máx. 2048 caracteres)	`/api/v1/resources`

Suporte e Feedback

Problemas: Relate problemas de precisão de restrições em https://github.com/f5-sales-demo/api-specs-enriched/issues
Documentação: Documentação completa da API em https://f5-sales-demo.github.io/api-specs-enriched/
Integração MCP: Consulte o repositório f5xc-api-mcp para exemplos de integração com servidor MCP

Versão: 3.3.0 Última Atualização: 2026-01-19 Restrições Reconciliadas: 9.851 Cobertura de Padrões: Mais de 50 tipos