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

Tipos não suportados e limitações

Aula 3 de 12 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. O que os esquemas não conseguem fazer
  2. As três principais restrições
  3. Outras limitações a conhecer
  4. A estratégia: esquema + prompt
  5. Pontos-chave

O que os esquemas não conseguem fazer

Compreender os limites das saídas estruturadas é tão importante quanto dominar as suas capacidades. A API do Grok não suporta certas restrições do JSON Schema. Tentar utilizá-las irá desencadear um erro ou causar um comportamento inesperado.

As três principais restrições

allOf — composição não permitida

No JSON Schema, a palavra-chave allOf combina vários subesquemas que um objeto deve satisfazer simultaneamente. A API do Grok não suporta esta funcionalidade.

// DOES NOT WORK
{
  "allOf": [
    { "properties": { "nom": { "type": "string" } } },
    { "properties": { "age": { "type": "number" } } }
  ]
}

Alternativa: utilize um único objeto com todas as propriedades:

// WORKS
{
  "type": "object",
  "properties": {
    "nom": { "type": "string" },
    "age": { "type": "number" }
  }
}

minLength / maxLength — sem restrições de comprimento de cadeia

Não pode obrigar o modelo a produzir uma cadeia com um comprimento mínimo ou máximo.

// DOES NOT WORK
{
  "properties": {
    "code": {
      "type": "string",
      "minLength": 3,
      "maxLength": 10
    }
  }
}

Alternativa: especifique a restrição no prompt em vez de no esquema:

messages=[{
    "role": "user",
    "content": "Generate a product code between 3 and 10 characters."
}]

O modelo seguirá a instrução na maioria dos casos, mas isso não é garantido como aconteceria com uma restrição de esquema.

minItems / maxItems — sem restrições de tamanho de matriz

Não pode impor um número mínimo ou máximo de elementos numa matriz.

// DOES NOT WORK
{
  "properties": {
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "maxItems": 5
    }
  }
}

Alternativa: utilize o prompt para orientar o modelo:

messages=[{
    "role": "user",
    "content": "List between 1 and 5 relevant tags for this article."
}]

Outras limitações a conhecer

Sem padrões regex

A API não suporta restrições pattern em cadeias. Não pode impor um formato de e-mail, UUID ou número de telefone através do esquema.

// DOES NOT WORK
{
  "properties": {
    "email": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9+_.-]+@[a-zA-Z0-9.-]+$"
    }
  }
}

Sem valores predefinidos

A palavra-chave default não tem qualquer efeito. Se um campo estiver no esquema, o modelo irá sempre preenchê-lo.

Sem condicionais

As palavras-chave do JSON Schema if, then e else não estão disponíveis.

A estratégia: esquema + prompt

A melhor abordagem combina ambos:

  1. O esquema garante a estrutura: nomes dos campos, tipos, aninhamento
  2. O prompt orienta o conteúdo: comprimentos, formatos específicos, regras de negócio
class Report(BaseModel):
    title: str
    summary: str
    key_points: list[str]
    score: float
    category: str

messages=[{
    "role": "user",
    "content": """Analyze this text and produce a report.
    - The summary must be 2-3 sentences.
    - List exactly 5 key points.
    - The score is between 0 and 10.
    - Category among: positive, negative, neutral."""
}]

O esquema garante os tipos e a estrutura. O prompt controla os valores e as restrições de conteúdo.

Pontos-chave

  • allOf, minLength, maxLength, minItems e maxItems não são suportados
  • As restrições pattern, default e if/then/else também não são suportadas
  • Utilize anyOf em vez de allOf sempre que possível
  • Transfira as restrições de conteúdo para o prompt
  • Combinar esquema (estrutura) + prompt (conteúdo) é a estratégia ótima