Tipos admitidos y esquemas JSON
En esta página
Los bloques de construcción de tus esquemas
Para definir la estructura de tus respuestas, dispones de siete tipos JSON. Cada uno cubre una necesidad específica a la hora de modelar tus datos. Entender estos tipos es esencial para diseñar esquemas eficaces.
Los siete tipos admitidos
string
El tipo más común. Se utiliza para nombres, descripciones, identificadores y cualquier contenido de texto.
{
"type": "object",
"properties": {
"name": { "type": "string" },
"description": { "type": "string" }
}
}
number
Abarca enteros y decimales. No hay distinción entre integer y float: un único tipo number gestiona ambos.
{
"properties": {
"price": { "type": "number" },
"quantity": { "type": "number" }
}
}
boolean
Verdadero o falso. Ideal para indicadores, validaciones y decisiones binarias.
{
"properties": {
"in_stock": { "type": "boolean" },
"express_delivery": { "type": "boolean" }
}
}
object
Te permite anidar estructuras. Un objeto puede contener otros objetos, arrays o escalares, sin límite de profundidad.
{
"type": "object",
"properties": {
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"postal_code": { "type": "string" }
}
}
}
}
array
Listas de elementos del mismo tipo. Puedes tener arrays de cadenas, números, objetos o incluso arrays.
{
"properties": {
"skills": {
"type": "array",
"items": { "type": "string" }
}
}
}
enum
Un conjunto finito de valores permitidos. Esencial para categorizaciones y clasificaciones.
{
"properties": {
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"]
}
}
}
anyOf
Te permite definir uniones de tipos. Un campo puede aceptar varias estructuras diferentes. Útil cuando un único campo puede adoptar formas variadas.
{
"properties": {
"contact": {
"anyOf": [
{
"type": "object",
"properties": {
"email": { "type": "string" }
}
},
{
"type": "object",
"properties": {
"phone": { "type": "string" }
}
}
]
}
}
}
Combinación de tipos
La potencia de los esquemas reside en combinar estos tipos. Aquí tienes un esquema realista para analizar un producto:
{
"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 mezcla escalares, un enum, un array y un objeto anidado. El modelo respetará todas las restricciones en cada llamada.
Campos opcionales
Para hacer que un campo sea opcional, usa anyOf con null:
{
"properties": {
"phone": {
"anyOf": [
{ "type": "string" },
{ "type": "null" }
]
}
}
}
En Pydantic, esto corresponde a phone: str | None.
Puntos clave
- Siete tipos disponibles:
string,number,object,array,boolean,enum,anyOf - Los tipos se combinan libremente para modelar estructuras complejas
- Los campos opcionales usan
anyOfconnull - Sin distinción entre entero y decimal: un único tipo
number enumobliga a usar valores predefinidos para clasificaciones