Tipos não suportados e limitações
Nesta página
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:
- O esquema garante a estrutura: nomes dos campos, tipos, aninhamento
- 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,minItemsemaxItemsnão são suportados- As restrições
pattern,defaulteif/then/elsetambém não são suportadas - Utilize
anyOfem vez deallOfsempre que possível - Transfira as restrições de conteúdo para o prompt
- Combinar esquema (estrutura) + prompt (conteúdo) é a estratégia ótima