Sistema de Metadatos de Restricciones

Propósito: Metadatos completos de restricciones para generación determinista con IA, validación mediante CLI y aplicación de esquemas en Terraform.

Extensión: x-f5xc-constraints Versión: 3.3.0 Estado: Producción Consumidores: Asistentes de IA, herramientas CLI, proveedores de Terraform, extensiones de IDE, validadores de API

---

Tabla de contenidos

1. Descripción general
2. Estructura de la extensión
3. Tipos de restricciones
4. Descripciones en lenguaje natural
5. Ejemplos de validación
6. Puntuaciones de confianza
7. Integración con descubrimiento
8. Guía de integración de herramientas

---

Descripción general

La extensión x-f5xc-constraints proporciona conocimiento determinista sobre las restricciones de validación de campos, lo que permite:

• Asistentes de IA: Generar configuraciones válidas sin necesidad de que el usuario especifique detalles de las restricciones
• Herramientas CLI: Proporcionar sugerencias de entrada precisas, validación y mensajes de error
• Terraform: Aplicar restricciones en tiempo de planificación, no en tiempo de aplicación
• Extensiones de IDE: Validación en tiempo real y sugerencias de autocompletado
• Validadores de API: Validación previa al envío para reducir errores de API

Estadísticas de cobertura

• 9.851 restricciones en todas las Especificaciones de API de F5 XC
• Más de 50 tipos de patrones (cadena, array, numérico)
• 95% de confianza en campos de alta prioridad (nombres, puertos, identificadores)
• Reconciliación de 3 niveles: EXISTENTE > DESCUBRIMIENTO > INFERIDO

---

Estructura de la extensión

Campos de nivel 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"
    }
  }
}

Descripción de campos

Campo	Tipo	Descripción
constraintType	string	Tipo de dato (string, array, number, object)
deterministic	boolean	Indicador de alta confianza (confianza >= 0.9) para generación con IA
category	string	Categoría de restricción para agrupación e informes
(claves de restricción)	varios	Claves de restricción específicas del tipo aplanadas en el nivel superior (p. ej., minLength, maxItems, minimum)
metadata	object	Seguimiento de origen, confianza, marca de tiempo de validación

---

Tipos de restricciones

Restricciones de cadena

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

Formato	Descripción	Ejemplo
dns-label	Etiqueta DNS RFC 1123 (1-63 caracteres)	my-service
fqdn	Nombre de dominio completamente calificado	api.example.com
email	Dirección de correo electrónico RFC 5322	user@example.com
url	URI/URL RFC 3986	https://example.com/api
ipv4	Dirección IPv4	192.168.1.1
ipv6	Dirección IPv6	2001:db8::1
uuid	UUID RFC 4122	550e8400-e29b-41d4-a716-446655440000
date-time	Marca de tiempo ISO 8601	2026-01-19T12:00:00Z
date	Fecha ISO 8601	2026-01-19
time	Hora ISO 8601	12:00:00
json	Cadena JSON (analizable)	{"key": "value"}
yaml	Cadena YAML (analizable)	key: value
base64	Cadena codificada en Base64	SGVsbG8gV29ybGQ=
hex	Cadena hexadecimal	48656c6c6f
mac-address	Dirección MAC	00:1A:2B:3C:4D:5E
phone	Número de teléfono E.164	+1-555-123-4567

Restricciones de array

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

Restricciones numéricas

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

---

Descripciones en lenguaje natural

Restricciones de formato de cadena

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

• Los nombres de etiquetas DNS deben tener entre 1 y 63 caracteres alfanuméricos en minúscula
• Se permiten guiones, pero no al inicio ni al final (RFC 1123)
• Ejemplo: my-service, api-gateway, lb-prod-01

Direcciones de correo electrónico (format: "email"):

• Las direcciones de correo electrónico deben ser válidas según RFC 5322
• Máximo 254 caracteres
• Ejemplo: admin@example.com, api+webhook@service.io

FQDN (format: "fqdn"):

• Los nombres de dominio completamente calificados deben tener entre 1 y 253 caracteres
• Etiquetas DNS separadas por puntos
• Ejemplo: api.example.com, service.production.internal

URL (format: "url"):

• Las URL deben ser URI válidas según RFC 3986
• Deben incluir el esquema (http/https)
• Ejemplo: https://api.example.com/v1, http://localhost:8080

Direcciones IPv4 (format: "ipv4"):

• Las direcciones IPv4 deben estar en notación decimal con puntos
• Ejemplo: 192.168.1.1, 10.0.0.1

UUID (format: "uuid"):

• Los UUID deben seguir el formato RFC 4122
• Ejemplo: 550e8400-e29b-41d4-a716-446655440000

Marcas de tiempo (format: "date-time"):

• Las marcas de tiempo deben estar en formato ISO 8601
• Ejemplo: 2026-01-19T12:00:00Z, 2026-01-19T12:00:00+00:00

Restricciones numéricas

Números de puerto:

• Los números de puerto deben ser enteros entre 1 y 65535
• Puertos estándar: 80 (HTTP), 443 (HTTPS), 22 (SSH)

ID de VLAN:

• Los ID de VLAN deben ser enteros entre 1 y 4094 (estándar 802.1Q)

Tiempos de espera:

• Los tiempos de espera deben ser entre 1 y 3600 segundos (máximo 1 hora)

Restricciones de array

Grupos de Servidor de origen:

• El array de grupos de Servidor de origen requiere al menos 1 elemento y un máximo de 50
• Cada elemento debe ser único

Etiquetas:

• El array de etiquetas permite entre 0 y 100 elementos
• Los elementos no necesitan ser únicos

---

Ejemplos de validación

Ejemplo 1: Validación de nombre de etiqueta DNS

Restricción:

{
  "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 (mayúsculas no permitidas)
• ❌ -my-service (guion al inicio)
• ❌ my-service- (guion al final)
• ❌ my_service (guion bajo no permitido)
• ❌ this-is-a-very-long-name-that-exceeds-the-sixty-three-character-limit (demasiado largo)

Ejemplo 2: Validación de número de puerto

Restricción:

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

Valores válidos:

• ✅ 80 (HTTP)
• ✅ 443 (HTTPS)
• ✅ 8080 (HTTP alternativo común)
• ✅ 65535 (puerto máximo)

Valores inválidos:

• ❌ 0 (por debajo del mínimo)
• ❌ 65536 (por encima del máximo)
• ❌ -1 (negativo)
• ❌ "80" (cadena, no número)

Ejemplo 3: Validación de tamaño de array

Restricción:

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

Valores válidos:

• ✅ ["origin-1"] (1 elemento)
• ✅ ["origin-1", "origin-2", "origin-3"] (3 elementos, todos únicos)

Valores inválidos:

• ❌ [] (por debajo del mínimo)
• ❌ ["origin-1", "origin-1"] (elementos duplicados)
• ❌ [array con 51 elementos] (por encima del máximo)

---

Puntuaciones de confianza

Interpretación de las puntuaciones

Rango	Interpretación	Uso
0.90-1.00	Alta confianza	Indicador determinista habilitado, usar para generación con IA
0.70-0.89	Confianza media	Orientativo, se recomienda confirmación del usuario
0.50-0.69	Baja confianza	Solo informativo, requiere validación del usuario
< 0.50	Muy baja	No se incluye en las restricciones

Indicador determinista

El indicador booleano deterministic se establece cuando:

• La puntuación de confianza es >= 0.9
• El patrón ha sido validado con datos de descubrimiento, O
• El patrón coincide con estándares bien establecidos (RFC, ISO, etc.)

Uso en generación con IA:

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)

---

Integración con descubrimiento

Prioridad de origen

Las restricciones se reconcilian utilizando una prioridad de 3 niveles:

1. EXISTENTE (Confianza: 1.0)

   • Establecido explícitamente en la especificación OpenAPI original
   • Nunca se reemplaza

2. DESCUBRIMIENTO (Confianza: 0.99)

   • Extraído de respuestas de la API de F5 XC en vivo
   • Incluye reglas de validación de x-ves-validation-rules
   • Reemplaza las restricciones inferidas

3. INFERIDO (Confianza: 0.50-0.95)

   • Coincidencia de patrones a partir de nombres de campo
   • Prioridad más baja, reemplazado por descubrimiento o explícito

Fuentes de datos de descubrimiento

Las restricciones de descubrimiento se extraen de:

1. x-ves-validation-rules: Extensiones de validación nativas de 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. Catálogo de errores: Mensajes de error de la API que indican violaciones de restricciones

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

3. Validación de respuestas: Respuestas exitosas de la API que demuestran valores válidos

   • Rangos de valores observados
   • Patrones de formato reales

---

Guía de integración de herramientas

Integración con asistentes de IA

Generar nombres de recursos válidos:

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)

Integración con herramientas CLI

Proporcionar validación de entrada:

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

Integración con el Proveedor de Terraform

Generación 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,
    }

    // 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
}

Integración con extensiones de IDE

Autocompletado y validación:

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;
}

---

Apéndice: Catálogo de patrones de restricciones

Patrones de alta confianza (0.95-0.99)

Patrón	Regex de nombre de campo	Tipo de restricción	Ejemplo
Etiqueta DNS	\bname$	Cadena (1-63 caracteres, dns-label)	my-service
Namespace	\bnamespace$	Cadena (1-63 caracteres, dns-label)	production
Puerto	\bport$	Número (1-65535)	443
ID de VLAN	\b(vlan)?_?id$	Número (1-4094)	100
UUID	\buuid$	Cadena (36 caracteres, formato uuid)	550e8400-...
Correo electrónico	\bemail$	Cadena (máx. 254 caracteres, email)	user@example.com
Marca de tiempo	\b(timestamp|created_at|updated_at)$	Cadena (ISO 8601)	2026-01-19T12:00:00Z

Patrones de confianza media (0.80-0.94)

Patrón	Regex de nombre de campo	Tipo de restricción	Ejemplo
Nombre de usuario	\b(user|username)$	Cadena (1-64 caracteres, alfanumérico)	admin
Nombre para mostrar	\b(display_?)?name$	Cadena (1-256 caracteres, texto libre)	My Service
Descripción	\b(comment|description|note)$	Cadena (máx. 4096 caracteres)	Service description
Ruta	\bpath$	Cadena (máx. 2048 caracteres)	/api/v1/resources

---

Soporte y comentarios

• Problemas: Informe problemas de precisión de restricciones en https://github.com/f5-sales-demo/api-specs-enriched/issues
• Documentación: Documentación completa de la API en https://f5-sales-demo.github.io/api-specs-enriched/
• Integración MCP: Consulte el repositorio f5xc-api-mcp para ver ejemplos de integración con servidores MCP

---

Versión: 3.3.0 Última actualización: 2026-01-19 Restricciones reconciliadas: 9.851 Cobertura de patrones: Más de 50 tipos