Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Esquemas JSON e Validação

Aula 2 de 20 Programador
Nesta página
  1. Esquemas JSON e Validação
  2. Estrutura do Esquema de Função
  3. Modo Estrito
  4. Validação no Lado do Cliente
  5. Descrições Eficazes
  6. Esquemas Aninhados e Referências
  7. Pontos-chave

Esquemas JSON e Validação

Um esquema de função não é apenas uma tubagem de validação: é o único contrato entre o modelo e o seu código. Não existe outro canal. O modelo não lê a sua implementação, desconhece as suas convenções internas e não adivinhará que um campo date espera o formato ISO em vez do formato francês.

Tudo o que não estiver escrito no esquema será decidido pelas inferências aleatórias do modelo. Isto explica o desequilíbrio de esforço recomendado nesta lição: é preferível gastar dez minutos num esquema do que duas horas a depurar argumentos erráticos.

Estrutura do Esquema de Função

Todas as funções declaradas em tools seguem o formato JSON Schema. Eis a estrutura completa:

tool_definition = {
    "type": "function",
    "name": "creer_facture",
    "description": "Create an invoice for an existing customer",
    "parameters": {
        "type": "object",
        "properties": {
            "client_id": {
                "type": "string",
                "description": "Unique customer identifier (format: CLI-XXXXX)"
            },
            "lignes": {
                "type": "array",
                "description": "List of billing line items",
                "items": {
                    "type": "object",
                    "properties": {
                        "description": {
                            "type": "string",
                            "description": "Product or service description"
                        },
                        "quantite": {
                            "type": "integer",
                            "minimum": 1,
                            "description": "Number of units"
                        },
                        "prix_unitaire": {
                            "type": "number",
                            "minimum": 0,
                            "description": "Unit price excluding tax in euros"
                        }
                    },
                    "required": ["description", "quantite", "prix_unitaire"]
                }
            },
            "devise": {
                "type": "string",
                "enum": ["EUR", "USD", "GBP"],
                "default": "EUR"
            },
            "echeance_jours": {
                "type": "integer",
                "enum": [30, 45, 60, 90],
                "description": "Payment deadline in days"
            }
        },
        "required": ["client_id", "lignes"],
        "additionalProperties": False
    },
    "strict": True
}

Modo Estrito

O modo estrito transforma a probabilidade numa garantia. Sem ele, o modelo produz geralmente argumentos conformes — e você descobre as exceções em produção, em casos limite. Com ele, a conformidade é assegurada por construção ao nível da descodificação. Ative-o por predefinição: as restrições que impõe, detalhadas logo abaixo, são um pequeno preço a pagar para eliminar toda uma classe de erros.

tools = [{
    "type": "function",
    "name": "enregistrer_commande",
    "description": "Record a new order",
    "parameters": {
        "type": "object",
        "properties": {
            "produit": {"type": "string"},
            "quantite": {"type": "integer"},
            "urgent": {"type": "boolean"}
        },
        "required": ["produit", "quantite", "urgent"],
        "additionalProperties": False
    },
    "strict": True
}]

Restrições do Modo Estrito

No modo estrito, aplicam-se certas regras:

  • Todos os campos devem estar em required
  • additionalProperties deve ser false
  • Tipos opcionais utilizam anyOf com null
  • Sem pattern, minLength, maxLength ao nível superior
# Campo opcional no modo estrito
"commentaire": {
    "anyOf": [
        {"type": "string"},
        {"type": "null"}
    ],
    "description": "Optional free-text comment"
}

Validação no Lado do Cliente

O modo estrito garante a forma, nunca o significado. Uma data bem formada pode estar no passado, um identificador bem tipado pode não corresponder a nenhum cliente e um valor válido pode exceder o limite autorizado. Estas regras são lógica de negócio: nenhum esquema JSON as expressa, e devem ser verificadas no seu código — com, em caso de rejeição, uma mensagem de erro enviada de volta ao modelo a explicar o que correu mal.

import json
from jsonschema import validate, ValidationError

SCHEMA_FACTURE = {
    "type": "object",
    "properties": {
        "client_id": {"type": "string", "pattern": "^CLI-[0-9]{5}$"},
        "lignes": {
            "type": "array",
            "minItems": 1,
            "items": {
                "type": "object",
                "properties": {
                    "description": {"type": "string", "minLength": 1},
                    "quantite": {"type": "integer", "minimum": 1},
                    "prix_unitaire": {"type": "number", "minimum": 0}
                },
                "required": ["description", "quantite", "prix_unitaire"]
            }
        }
    },
    "required": ["client_id", "lignes"]
}

def executer_fonction(name: str, arguments: str) -> str:
    args = json.loads(arguments)

    try:
        validate(instance=args, schema=SCHEMA_FACTURE)
    except ValidationError as e:
        return json.dumps({"error": f"Invalid arguments: {e.message}"})

    # Lógica de negócio após validação
    return creer_facture(**args)

Descrições Eficazes

Escreva a descrição de uma função como instruções para um novo colega: quando chamá-la e, especialmente, quando não chamá-la. É essa segunda parte que sistematicamente esquecemos, no entanto, resolve a maioria das chamadas erróneas — «não utilizar para encomendas arquivadas» evita uma ida e volta desnecessária que três frases de descrição positiva não teriam impedido.

# Mau: demasiado vago
{
    "name": "get_data",
    "description": "Retrieve data"
}

# Bom: específico e contextual
{
    "name": "rechercher_produits_catalogue",
    "description": "Search for products in the e-commerce catalog. "
                   "Returns name, price, stock, and category. "
                   "Use for questions about availability or pricing."
}

Descrições de Parâmetros

Ao nível dos parâmetros, o inimigo é o implícito. Uma unidade (euros ou cêntimos?), um formato (ISO ou local?), uma convenção (ID interno ou referência do cliente?) que não estejam escritos serão adivinhados — por vezes corretamente, por vezes não, sem qualquer sinal em nenhum dos sentidos. O enum é a sua melhor ferramenta aqui: não descreve o valor esperado, restringe-o.

"properties": {
    "date_debut": {
        "type": "string",
        "description": "Start date in ISO 8601 format (YYYY-MM-DD). "
                       "Defaults to today's date if not specified."
    },
    "statut": {
        "type": "string",
        "enum": ["actif", "inactif", "suspendu"],
        "description": "Filter by account status. "
                       "'actif' = accounts in service, "
                       "'suspendu' = temporarily frozen accounts."
    }
}

Esquemas Aninhados e Referências

Um esquema profundamente aninhado é difícil de reler para si e de preencher corretamente para o modelo. Se chegar a três níveis, a pergunta a fazer não é como escrevê-lo melhor, mas sim se a função não está a fazer demasiado: duas funções com âmbito claro são quase sempre preferíveis a uma função configurável que cubra ambos os casos.

adresse_schema = {
    "type": "object",
    "properties": {
        "rue": {"type": "string"},
        "code_postal": {"type": "string"},
        "ville": {"type": "string"},
        "pays": {"type": "string", "enum": ["FR", "BE", "CH", "LU"]}
    },
    "required": ["rue", "code_postal", "ville", "pays"]
}

tools = [{
    "type": "function",
    "name": "creer_livraison",
    "description": "Create a delivery with shipping and destination addresses",
    "parameters": {
        "type": "object",
        "properties": {
            "expedition": adresse_schema,
            "destination": adresse_schema,
            "poids_kg": {"type": "number", "minimum": 0.1}
        },
        "required": ["expedition", "destination", "poids_kg"],
        "additionalProperties": False
    },
    "strict": True
}]

Pontos-chave

  • Ative strict: true para garantir a conformidade dos argumentos
  • Valide ainda assim no lado do cliente com jsonschema para regras de negócio
  • Escreva descrições precisas: são a principal alavanca de qualidade
  • Utilize enum para restringir os valores aceites
  • Divida esquemas complexos em subestruturas reutilizáveis