Tipos suportados e esquemas JSON
Nesta página
Os blocos de construção dos seus esquemas
Para definir a estrutura das suas respostas, dispõe de sete tipos JSON. Cada um serve uma necessidade específica na modelação dos seus dados. Compreender estes tipos é essencial para conceber esquemas eficazes.
Os sete tipos suportados
string
O tipo mais comum. Utilizado para nomes, descrições, identificadores e qualquer conteúdo de texto.
{
"type": "object",
"properties": {
"name": { "type": "string" },
"description": { "type": "string" }
}
}
number
Abrange inteiros e números de vírgula flutuante. Não há distinção entre integer e float — um único tipo number gere ambos.
{
"properties": {
"price": { "type": "number" },
"quantity": { "type": "number" }
}
}
boolean
Verdadeiro ou falso. Perfeito para sinalizadores, validações e decisões binárias.
{
"properties": {
"in_stock": { "type": "boolean" },
"express_delivery": { "type": "boolean" }
}
}
object
Permite aninhar estruturas. Um objeto pode conter outros objetos, arrays ou escalares — sem limite de profundidade.
{
"type": "object",
"properties": {
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"postal_code": { "type": "string" }
}
}
}
}
array
Listas de elementos do mesmo tipo. Pode ter arrays de strings, números, objetos ou mesmo arrays.
{
"properties": {
"skills": {
"type": "array",
"items": { "type": "string" }
}
}
}
enum
Um conjunto finito de valores permitidos. Essencial para categorizações e classificações.
{
"properties": {
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"]
}
}
}
anyOf
Permite definir uniões de tipos. Um campo pode aceitar várias estruturas diferentes. Útil quando um único campo pode assumir formas variadas.
{
"properties": {
"contact": {
"anyOf": [
{
"type": "object",
"properties": {
"email": { "type": "string" }
}
},
{
"type": "object",
"properties": {
"phone": { "type": "string" }
}
}
]
}
}
}
Combinação de tipos
O poder dos esquemas reside na combinação destes tipos. Eis um esquema realista para analisar um produto:
{
"type": "object",
"properties": {
"name": { "type": "string" },
"price": { "type": "number" },
"in_stock": { "type": "boolean" },
"category": {
"type": "string",
"enum": ["electronics", "clothing", "grocery", "other"]
},
"tags": {
"type": "array",
"items": { "type": "string" }
},
"manufacturer": {
"type": "object",
"properties": {
"name": { "type": "string" },
"country": { "type": "string" }
}
}
}
}
Este esquema mistura escalares, um enum, um array e um objeto aninhado. O modelo respeitará todas as restrições em cada chamada.
Campos opcionais
Para tornar um campo opcional, utilize anyOf com null:
{
"properties": {
"phone": {
"anyOf": [
{ "type": "string" },
{ "type": "null" }
]
}
}
}
No Pydantic, isto corresponde a phone: str | None.
Pontos-chave
- Sete tipos disponíveis:
string,number,object,array,boolean,enum,anyOf - Os tipos combinam-se livremente para modelar estruturas complexas
- Campos opcionais utilizam
anyOfcomnull - Sem distinção entre inteiro e vírgula flutuante — um único tipo
number - O
enumimpõe valores predefinidos para classificações