Sistema di Metadati per Vincoli

Scopo: Metadati completi sui vincoli per la generazione deterministica con IA, la validazione tramite CLI e l’applicazione degli schemi Terraform.

Estensione: x-f5xc-constraints Versione: 3.3.0 Stato: Produzione Consumatori: Assistenti IA, strumenti CLI, provider Terraform, estensioni IDE, validatori API

Panoramica

L’estensione x-f5xc-constraints fornisce informazioni deterministiche sui vincoli di validazione dei campi, abilitando:

Assistenti IA: Generano configurazioni valide senza richiedere all’utente i dettagli sui vincoli
Strumenti CLI: Forniscono suggerimenti di input accurati, validazione e messaggi di errore
Terraform: Applica i vincoli al momento della pianificazione, non dell’applicazione
Estensioni IDE: Validazione in tempo reale e suggerimenti di completamento automatico
Validatori API: Validazione pre-invio per ridurre gli errori API

Statistiche di copertura

9.851 vincoli in tutte le specifiche API F5 XC
50+ tipi di pattern (stringa, array, numerico)
95% di confidenza sui campi ad alta priorità (nomi, porte, identificatori)
Riconciliazione a 3 livelli: EXISTING > DISCOVERY > INFERRED

Struttura dell’estensione

Campi di primo livello

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

Descrizioni dei campi

Campo	Tipo	Descrizione
`constraintType`	string	Tipo di dato (string, array, number, object)
`deterministic`	boolean	Flag di alta confidenza (confidenza >= 0,9) per la generazione con IA
`category`	string	Categoria del vincolo per raggruppamento e reportistica
(chiavi di vincolo)	vario	Chiavi di vincolo specifiche per tipo appiattite al primo livello (es. `minLength`, `maxItems`, `minimum`)
`metadata`	object	Tracciamento della sorgente, confidenza, timestamp di validazione

Tipi di vincolo

Vincoli su stringhe

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

Formati supportati

Formato	Descrizione	Esempio
`dns-label`	Etichetta DNS RFC 1123 (1-63 caratteri)	`my-service`
`fqdn`	Nome di dominio completo (FQDN)	`api.example.com`
`email`	Indirizzo e-mail RFC 5322	`user@example.com`
`url`	URI/URL RFC 3986	`https://example.com/api`
`ipv4`	Indirizzo IPv4	`192.168.1.1`
`ipv6`	Indirizzo IPv6	`2001:db8::1`
`uuid`	UUID RFC 4122	`550e8400-e29b-41d4-a716-446655440000`
`date-time`	Timestamp ISO 8601	`2026-01-19T12:00:00Z`
`date`	Data ISO 8601	`2026-01-19`
`time`	Ora ISO 8601	`12:00:00`
`json`	Stringa JSON (analizzabile)	`{"key": "value"}`
`yaml`	Stringa YAML (analizzabile)	`key: value`
`base64`	Stringa codificata in Base64	`SGVsbG8gV29ybGQ=`
`hex`	Stringa esadecimale	`48656c6c6f`
`mac-address`	Indirizzo MAC	`00:1A:2B:3C:4D:5E`
`phone`	Numero di telefono E.164	`+1-555-123-4567`

Vincoli su array

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

Vincoli numerici

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

Descrizioni in linguaggio naturale

Vincoli su formato stringa

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

I nomi delle etichette DNS devono essere composti da 1-63 caratteri alfanumerici minuscoli
I trattini sono consentiti ma non in prima o ultima posizione (RFC 1123)
Esempio: my-service, api-gateway, lb-prod-01

Indirizzi e-mail (format: "email"):

Gli indirizzi e-mail devono essere validi secondo RFC 5322
Massimo 254 caratteri
Esempio: admin@example.com, api+webhook@service.io

FQDN (format: "fqdn"):

I nomi di dominio completi (FQDN) devono essere composti da 1-253 caratteri
Etichette DNS separate da punti
Esempio: api.example.com, service.production.internal

URL (format: "url"):

Gli URL devono essere URI validi secondo RFC 3986
Devono includere lo schema (http/https)
Esempio: https://api.example.com/v1, http://localhost:8080

Indirizzi IPv4 (format: "ipv4"):

Gli indirizzi IPv4 devono essere in notazione decimale puntata
Esempio: 192.168.1.1, 10.0.0.1

UUID (format: "uuid"):

Gli UUID devono seguire il formato RFC 4122
Esempio: 550e8400-e29b-41d4-a716-446655440000

Timestamp (format: "date-time"):

I timestamp devono essere in formato ISO 8601
Esempio: 2026-01-19T12:00:00Z, 2026-01-19T12:00:00+00:00

Vincoli numerici

Numeri di porta:

I numeri di porta devono essere interi compresi tra 1 e 65535
Porte standard: 80 (HTTP), 443 (HTTPS), 22 (SSH)

ID VLAN:

Gli ID VLAN devono essere interi compresi tra 1 e 4094 (standard 802.1Q)

Timeout:

I timeout devono essere compresi tra 1 e 3600 secondi (massimo 1 ora)

Vincoli su array

Pool di origine:

L’array di pool di origine richiede almeno 1 elemento, massimo 50 elementi
Ogni elemento deve essere univoco

Tag:

L’array di tag consente da 0 a 100 elementi
Gli elementi non devono necessariamente essere univoci

Esempi di validazione

Esempio 1: Validazione del nome come etichetta DNS

Vincolo:

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

Valori validi:

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

Valori non validi:

❌ My-Service (lettere maiuscole non consentite)
❌ -my-service (trattino in prima posizione)
❌ my-service- (trattino in ultima posizione)
❌ my_service (underscore non consentito)
❌ this-is-a-very-long-name-that-exceeds-the-sixty-three-character-limit (troppo lungo)

Esempio 2: Validazione del numero di porta

Vincolo:

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

Valori validi:

✅ 80 (HTTP)
✅ 443 (HTTPS)
✅ 8080 (HTTP alternativo comune)
✅ 65535 (porta massima)

Valori non validi:

❌ 0 (sotto il minimo)
❌ 65536 (sopra il massimo)
❌ -1 (negativo)
❌ "80" (stringa, non numero)

Esempio 3: Validazione della dimensione dell’array

Vincolo:

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

Valori validi:

✅ ["origin-1"] (1 elemento)
✅ ["origin-1", "origin-2", "origin-3"] (3 elementi, tutti univoci)

Valori non validi:

❌ [] (sotto il minimo)
❌ ["origin-1", "origin-1"] (elementi duplicati)
❌ [array con 51 elementi] (sopra il massimo)

Punteggi di confidenza

Interpretazione dei punteggi

Intervallo	Interpretazione	Utilizzo
0,90-1,00	Alta confidenza	Flag deterministico abilitato, utilizzare per la generazione con IA
0,70-0,89	Confidenza media	Consultivo, si raccomanda la conferma dell’utente
0,50-0,69	Bassa confidenza	Solo informativo, richiede la validazione dell’utente
< 0,50	Molto bassa	Non incluso nei vincoli

Flag deterministico

Il flag booleano deterministic viene impostato quando:

Il punteggio di confidenza è >= 0,9
Il pattern è stato validato rispetto ai dati di discovery OPPURE
Il pattern corrisponde a standard consolidati (RFC, ISO, ecc.)

Utilizzo nella generazione con IA:

if constraint.get("deterministic"):
    # Genera il valore automaticamente senza chiedere all'utente
    value = generate_from_pattern(constraint)
else:
    # Chiede input all'utente con suggerimenti sui vincoli
    value = prompt_user_with_hints(constraint)

Integrazione con il sistema di discovery

Priorità delle sorgenti

I vincoli vengono riconciliati utilizzando una priorità a 3 livelli:

EXISTING (Confidenza: 1,0)
- Impostato esplicitamente nella specifica OpenAPI originale
- Non viene mai sovrascritto
DISCOVERY (Confidenza: 0,99)
- Estratto dalle risposte live dell’API F5 XC
- Include le regole di validazione da x-ves-validation-rules
- Sovrascrive i vincoli inferiti
INFERRED (Confidenza: 0,50-0,95)
- Corrispondenza di pattern dai nomi dei campi
- Priorità più bassa, viene sovrascritto da discovery o explicit

Sorgenti dei dati di discovery

I vincoli di discovery vengono estratti da:

x-ves-validation-rules: Estensioni di validazione native F5
- ves.io.schema.rules.string.max_len → maxLength
- ves.io.schema.rules.string.pattern → pattern
- ves.io.schema.rules.repeated.max_items → maxItems
Catalogo degli errori: Messaggi di errore API che indicano violazioni dei vincoli
- “name must be 1-63 characters” → minLength/maxLength
- “port must be between 1 and 65535” → minimum/maximum
Validazione delle risposte: Risposte API andate a buon fine che dimostrano valori validi
- Intervalli di valori osservati
- Pattern di formato effettivi

Guida all’integrazione degli strumenti

Integrazione con assistenti IA

Generare nomi di risorse validi:

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

    if not constraints.get("deterministic"):
        # Chiede all'utente il nome
        return prompt_user("Enter resource name: ")

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

    # Genera un nome valido corrispondente al pattern
    return generate_dns_label(max_length=max_len)

Integrazione con strumenti CLI

Fornire la validazione dell’input:

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

    # Controlla la lunghezza (le chiavi di vincolo sono al primo livello)
    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"

    # Controlla il 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

Integrazione con il provider Terraform

Generazione dello schema:

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

    // Le chiavi di vincolo sono al primo livello (senza wrapper "string" annidato)
    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
}

Integrazione con estensioni IDE

Completamento automatico e validazione:

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

    const items: CompletionItem[] = [];

    // Aggiungi completamenti specifici per formato
    if (constraints.format === 'dns-label') {
        items.push({
            label: 'my-service',
            detail: 'Example DNS label',
            kind: CompletionItemKind.Value
        });
    }

    // Aggiungi suggerimento di validazione
    if (constraints.deterministic) {
        items.push({
            label: '✨ Auto-generate',
            detail: 'Generate valid value automatically',
            kind: CompletionItemKind.Function,
            command: { command: 'f5xc.generateValue', arguments: [field] }
        });
    }

    return items;
}

Appendice: Catalogo dei pattern di vincolo

Pattern ad alta confidenza (0,95-0,99)

Pattern	Regex nome campo	Tipo di vincolo	Esempio
Etichetta DNS	`\bname$`	String (1-63 caratteri, dns-label)	`my-service`
Namespace	`\bnamespace$`	String (1-63 caratteri, dns-label)	`production`
Porta	`\bport$`	Number (1-65535)	`443`
ID VLAN	`\b(vlan)?_?id$`	Number (1-4094)	`100`
UUID	`\buuid$`	String (36 caratteri, formato uuid)	`550e8400-...`
E-mail	`\bemail$`	String (max 254 caratteri, email)	`user@example.com`
Timestamp	`\b(timestamp\|created_at\|updated_at)$`	String (ISO 8601)	`2026-01-19T12:00:00Z`

Pattern a confidenza media (0,80-0,94)

Pattern	Regex nome campo	Tipo di vincolo	Esempio
Nome utente	`\b(user\|username)$`	String (1-64 caratteri, alfanumerico)	`admin`
Nome visualizzato	`\b(display_?)?name$`	String (1-256 caratteri, testo libero)	`My Service`
Descrizione	`\b(comment\|description\|note)$`	String (max 4096 caratteri)	`Service description`
Percorso	`\bpath$`	String (max 2048 caratteri)	`/api/v1/resources`

Supporto e feedback

Segnalazioni: Segnala problemi di accuratezza dei vincoli su https://github.com/f5-sales-demo/api-specs-enriched/issues
Documentazione: Documentazione API completa su https://f5-sales-demo.github.io/api-specs-enriched/
Integrazione MCP: Consulta il repository f5xc-api-mcp per esempi di integrazione con il server MCP

Versione: 3.3.0 Ultimo aggiornamento: 2026-01-19 Vincoli riconciliati: 9.851 Copertura dei pattern: 50+ tipi