Ir al contenido principal
Español— Elegir un idioma
Menú

Patrones complejos: listas anidadas, enumeraciones y uniones

Lección 12 de 16 Actualizado el 28 de julio de 2026 Desarrollador
En esta página
  1. Patrones complejos: listas anidadas, enumeraciones y uniones
  2. Listas anidadas
  3. Enumeraciones para restringir valores
  4. Simulación de uniones de tipos
  5. Objetos recursivos
  6. Patrón: extracción de múltiples entidades
  7. Mejores prácticas para esquemas complejos
  8. El caso que lo pone todo a prueba: el organigrama
  9. Puntos clave

Patrones complejos: listas anidadas, enumeraciones y uniones

Los casos de extracción sencillos (un objeto plano con campos de texto) son fáciles de gestionar. Los verdaderos desafíos surgen con estructuras complejas: listas de objetos anidados, tipos condicionales y campos polimórficos. Esta lección te muestra cómo diseñar esquemas robustos para estos casos avanzados.

Listas anidadas

El patrón más habitual en producción consiste en extraer una lista de objetos donde cada objeto contiene sus propias sub-listas. El esquema de abajo describe un programa de formación con tres niveles: el objeto programa con su título y duración, un array de módulos con título y objetivos textuales, y finalmente las lecciones de cada módulo, descritas por un título, una duración en minutos y un tipo restringido mediante un enum.

Lo que el modelo debe lograr aquí va más allá de la lectura: necesita asociar cada lección al módulo correcto, lo que implica comprender una jerarquía que a veces solo se transmite mediante niveles de encabezado. De ahí la importancia de campos muy concretos en el tercer nivel: una duración en minutos en lugar de una genérica «duración» expresada a veces en horas y otras en sesiones. Cuanto más precisos sean los nodos hoja del árbol, menos dudará el modelo.

import json
from openai import OpenAI

client = OpenAI()

# Esquema: extraer un programa de formación con módulos y lecciones
formation_schema = {
    "type": "object",
    "properties": {
        "titre": {"type": "string"},
        "duree_totale_heures": {"type": "number"},
        "modules": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "titre_module": {"type": "string"},
                    "objectifs": {
                        "type": "array",
                        "items": {"type": "string"}
                    },
                    "lecons": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "titre_lecon": {"type": "string"},
                                "duree_minutes": {"type": "integer"},
                                "type": {
                                    "type": "string",
                                    "enum": ["theorie", "pratique",
                                             "évaluation"]
                                }
                            },
                            "required": ["titre_lecon",
                                         "duree_minutes", "type"],
                            "additionalProperties": False
                        }
                    }
                },
                "required": ["titre_module", "objectifs", "lecons"],
                "additionalProperties": False
            }
        }
    },
    "required": ["titre", "duree_totale_heures", "modules"],
    "additionalProperties": False
}

Enumeraciones para restringir valores

Las enumeraciones (enum) son la forma más fiable de limitar los valores posibles de un campo. La Salida Estructurada las aplica a nivel de generación: a diferencia de una instrucción escrita en el prompt, no pueden ignorarse un día de fatiga estadística. Esto las hace valiosas cuando el valor extraído alimenta una sentencia switch, una columna indexada o una regla de enrutamiento; tres lugares donde un valor inesperado no provoca un error crítico, sino silencio.

El esquema de clasificación que sigue ordena las solicitudes entrantes según cuatro ejes: categorie_principale localiza el departamento pertinente, sous_categorie lo refina dentro de ese departamento, priorite sirve para ordenar la cola y action_requise determina qué hacer con el ticket. Un punto de diseño merece atención: los doce valores de sous_categorie están aplanados en lugar de adjuntarse a su categoría padre, porque el modo estricto no ofrece dependencia condicional entre dos enum. Nada impide, por tanto, la combinación «juridique» y «recrutement», y esta coherencia debe verificarse tras la recepción.

# Sistema de clasificación multinivel
classification_schema = {
    "type": "object",
    "properties": {
        "categorie_principale": {
            "type": "string",
            "enum": ["technique", "commercial", "juridique",
                     "rh", "finance"]
        },
        "sous_categorie": {
            "type": "string",
            "enum": [
                "bug", "feature", "performance",
                "devis", "facturation", "contrat",
                "recrutement", "conge", "formation",
                "budget", "audit", "conformite"
            ]
        },
        "priorite": {
            "type": "string",
            "enum": ["critique", "haute", "moyenne", "basse"]
        },
        "action_requise": {
            "type": "string",
            "enum": ["repondre", "escalader", "archiver",
                     "planifier", "deleguer"]
        }
    },
    "required": ["categorie_principale", "sous_categorie",
                  "priorite", "action_requise"],
    "additionalProperties": False
}

Simulación de uniones de tipos

JSON Schema soporta anyOf para tipos condicionales, pero la Salida Estructurada estricta de OpenAI tiene limitaciones. El patrón recomendado es usar un campo discriminador: defines un único objeto, lo bastante amplio para cubrir todos los casos, y un campo type indica cuál estás describiendo.

# Patrón: un evento puede ser una reunión, una tarea o un recordatorio
event_schema = {
    "type": "object",
    "properties": {
        "type": {
            "type": "string",
            "enum": ["reunion", "tache", "rappel"]
        },
        "titre": {"type": "string"},
        "date": {"type": "string"},
        "heure_debut": {"type": ["string", "null"]},
        "heure_fin": {"type": ["string", "null"]},
        "participants": {
            "type": "array",
            "items": {"type": "string"}
        },
        "lieu": {"type": ["string", "null"]},
        "priorite": {
            "type": ["string", "null"],
            "enum": ["haute", "moyenne", "basse", None]
        },
        "description": {"type": "string"}
    },
    "required": ["type", "titre", "date", "heure_debut",
                  "heure_fin", "participants", "lieu",
                  "priorite", "description"],
    "additionalProperties": False
}

El truco consiste en hacer nulos cualquier campo específico de un único tipo, usando la notación "type": ["string", "null"]. Para una reunión, participants y lieu se rellenan; para un recordatorio, valen null. Tu código lee primero el discriminador y sabe inmediatamente qué claves tienen sentido; exactamente la misma lectura que harías de una unión etiquetada en un lenguaje tipado. El precio a pagar, un esquema más verboso y null que gestionar, sigue siendo preferible a tres llamadas separadas.

Objetos recursivos

Para estructuras de árbol (menús, organigramas, hilos de discusión), usa $defs para referencias recursivas. El principio consiste en nombrar la forma repetitiva una sola vez y luego referenciarla desde dentro de sí misma. Aquí, un comentario contiene un array de respuestas donde cada elemento es a su vez un comentario: la profundidad no se fija en tiempo de escritura, sino que sigue la del documento analizado. Esta es la única forma razonable de procesar un hilo de discusión sin saber de antemano si tiene dos niveles de respuestas o siete.

# Estructura de un comentario con respuestas anidadas
comment_schema = {
    "type": "object",
    "properties": {
        "commentaires": {
            "type": "array",
            "items": {"$ref": "#/$defs/comment"}
        }
    },
    "required": ["commentaires"],
    "additionalProperties": False,
    "$defs": {
        "comment": {
            "type": "object",
            "properties": {
                "auteur": {"type": "string"},
                "contenu": {"type": "string"},
                "sentiment": {
                    "type": "string",
                    "enum": ["positif", "negatif", "neutre"]
                },
                "reponses": {
                    "type": "array",
                    "items": {"$ref": "#/$defs/comment"}
                }
            },
            "required": ["auteur", "contenu", "sentiment",
                          "reponses"],
            "additionalProperties": False
        }
    }
}

Patrón: extracción de múltiples entidades

Cuando un texto contiene varios tipos de entidades, la tentación es ejecutar una extracción por familia. El esquema multi-entidad hace algo mejor: solicita personas, organizaciones, fechas e importes en una única pasada. El beneficio no es solo ahorrar llamadas; es que el modelo ve el texto una sola vez y puede relacionar lo que encuentra allí: asociar una persona a su organización, vincular un importe con el contexto que le da sentido.

La duplicación en fechas, date_brute y date_iso, merece mantenerse tal cual en tus propios esquemas: preserva la formulación original para auditoría mientras proporciona un valor normalizado. El campo contexte, presente en fechas e importes, juega el mismo papel: sin él, nadie sabrá si 12.000 euros fue un presupuesto, una penalización o un presupuesto anual.

multi_entity_schema = {
    "type": "object",
    "properties": {
        "personnes": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "nom": {"type": "string"},
                    "role": {"type": "string"},
                    "organisation": {"type": ["string", "null"]}
                },
                "required": ["nom", "role", "organisation"],
                "additionalProperties": False
            }
        },
        "organisations": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "nom": {"type": "string"},
                    "type": {
                        "type": "string",
                        "enum": ["entreprise", "association",
                                 "administration", "autre"]
                    },
                    "secteur": {"type": ["string", "null"]}
                },
                "required": ["nom", "type", "secteur"],
                "additionalProperties": False
            }
        },
        "dates": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "date_brute": {"type": "string"},
                    "date_iso": {"type": "string"},
                    "contexte": {"type": "string"}
                },
                "required": ["date_brute", "date_iso", "contexte"],
                "additionalProperties": False
            }
        },
        "montants": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "valeur": {"type": "number"},
                    "devise": {"type": "string"},
                    "contexte": {"type": "string"}
                },
                "required": ["valeur", "devise", "contexte"],
                "additionalProperties": False
            }
        }
    },
    "required": ["personnes", "organisations", "dates", "montants"],
    "additionalProperties": False
}

Mejores prácticas para esquemas complejos

Cuatro hábitos evitan la mayoría de decepciones. Empieza simple: valida un objeto plano con tus datos reales antes de añadir cualquier anidamiento; de lo contrario, no sabrás si un fallo proviene del esquema o de la dificultad de la tarea. A continuación, renuncia al campo opcional, que el modo estricto prohíbe, y hazlo nulo en su lugar. Respeta también un límite empírico: más allá de tres o cuatro niveles de anidamiento la calidad cae, y es mejor dividir la extracción en dos pasadas: primero la lista de módulos, luego una llamada por módulo para detallar sus lecciones. Por último, ten presente la división del trabajo: el esquema y sus enums restringen la estructura, el prompt del sistema guía el contenido. Si el modelo clasifica correctamente pero extrae la información errónea, es el prompt lo que debes ajustar.

El caso que lo pone todo a prueba: el organigrama

Aborda el caso recursivo, la parte más didáctica de la lección. Define un esquema para extraer el organigrama de una empresa, donde cada empleado puede tener subordinados que son a su vez empleados. Pruébalo con un texto que describa una organización de quince a veinte personas, escrito en prosa y no como una lista: aquí es donde el modelo debe inferir las líneas de reporte a partir de frases como «reports to» o «within the team of».

Verifica que las relaciones jerárquicas estén correctamente anidadas, prestando atención a las personas mencionadas lejos de su gestor; este es el punto de ruptura habitual. Por último, añade enums sobre los roles (directivo, mando, operativo) y observa si la restricción mejora o degrada la línea de reporte: forzar una categorización puede ayudar al modelo o empujarlo hacia elecciones arbitrarias en perfiles híbridos.

Puntos clave

  • Las listas anidadas son el patrón más común en producción
  • Los enums se aplican a nivel de generación: aprovéchalos
  • Simula uniones con un campo discriminador y campos nulos
  • $defs permite estructuras recursivas (comentarios, árboles)
  • Limita la profundidad de anidamiento a 3-4 niveles