Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Patronen complexen: geneste lijsten, enums, unions

Les 12 van 16 Bijgewerkt op 28 juli 2026 Ontwikkelaar
Op deze pagina
  1. Patronen complexen: geneste lijsten, enums, unions
  2. Geneste lijsten
  3. Enums om waarden te beperken
  4. Type-unions simuleren
  5. Recursieve objecten
  6. Patroon: multi-entity extractie
  7. Best practices voor complexe schema’s
  8. Het geval dat alles test: het organigram
  9. Belangrijkste punten

Patronen complexen: geneste lijsten, enums, unions

Eenvoudige extractiegevallen (een plat object met tekstvelden) zijn eenvoudig af te handelen. De echte uitdagingen ontstaan bij complexe structuren: geneste objectlijsten, conditionele typen en polymorfe velden. Deze les leert u hoe u robuuste schema’s ontwerpt voor deze geavanceerde gevallen.

Geneste lijsten

Het meest voorkomende patroon in productieomgevingen betreft het extraheren van een lijst objecten waarbij elk object zijn eigen sublijsten bevat. Het onderstaande schema beschrijft een trainingsprogramma met drie niveaus: het programma-object met titel en duur, een array van modules met elk een titel en tekstuele doelstellingen, en tot slot de lessen per module, beschreven door een titel, een duur in minuten en een type beperkt door een enum.

Wat het model hier moet presteren, gaat verder dan lezen: het moet elke les aan de juiste module koppelen. Dit betekent dat het een hiërarchie moet begrijpen die soms alleen wordt overgebracht via kopniveaus. Vandaar de zeer concrete velden op het derde niveau: een duur in minuten in plaats van een generieke “duur” die soms in uren, soms in sessies wordt uitgedrukt. Hoe preciezer de bladknooppunten van de boom, hoe minder het model aarzelt.

import json
from openai import OpenAI

client = OpenAI()

# Schema: extract a training program with modules and lessons
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
}

Enums om waarden te beperken

Enums zijn de meest betrouwbare manier om de mogelijke waarden van een veld te beperken. Structured Output past deze toe op generatieniveau: in tegenstelling tot een instructie in de prompt, kunnen ze niet genegeerd worden op een dag van statistische vermoeidheid. Dit maakt ze waardevol wanneer de geëxtraheerde waarde dient als input voor een switch-statement, een geïndexeerde kolom of een routeringsregel – drie situaties waarin een onverwachte waarde niet leidt tot een harde fout, maar tot stilte.

Het onderstaande classificatieschema sorteert inkomende verzoeken langs vier assen: categorie_principale lokaliseert de relevante afdeling, sous_categorie verfijnt dit binnen die afdeling, priorite dient voor wachtrijsortering en action_requise bepaalt wat er met het ticket moet gebeuren. Eén ontwerppunt verdient aandacht: de twaalf waarden van sous_categorie zijn afgeplat in plaats van gekoppeld aan hun oudercategorie, omdat de strikte modus geen conditionele afhankelijkheid tussen twee enums biedt. Niets verhindert dus de combinatie “juridique” en “recrutement”; deze consistentie moet na ontvangst worden geverifieerd.

# Multi-level classification system
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
}

Type-unions simuleren

JSON Schema ondersteunt anyOf voor conditionele typen, maar OpenAI’s strikte Structured Output kent beperkingen. Het aanbevolen patroon is het gebruik van een discriminatorveld: u definieert één object, breed genoeg om alle gevallen te dekken, en een type-veld geeft aan welk geval wordt beschreven.

# Pattern: an event can be a meeting, a task, or a reminder
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
}

De truc is om elk veld dat specifiek is voor één type nullable te maken, met de notatie "type": ["string", "null"]. Voor een vergadering zijn participants en lieu ingevuld; voor een herinnering zijn ze gelijk aan null. Uw code leest vervolgens eerst de discriminator en weet direct welke sleutels zinvol zijn – precies zoals u een tagged union in een getypte taal zou lezen. De prijs die u betaalt, een uitgebreider schema en het verwerken van null-waarden, blijft te verkiezen boven drie aparte calls.

Recursieve objecten

Voor boomstructuren – menu’s, organigrammen, discussiethreads – gebruikt u $defs voor recursieve referenties. Het principe is om de terugkerende vorm één keer een naam te geven en deze vervolgens vanuit zichzelf te refereren. Hier bevat een commentaar een array van antwoorden waarbij elk element op zijn beurt weer een commentaar is: de diepte is niet vooraf vastgelegd, maar volgt die van het geanalyseerde document. Dit is de enige redelijke manier om een discussiethread te verwerken zonder vooraf te weten of deze twee of zeven niveaus van antwoorden heeft.

# Structure of a comment with nested replies
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
        }
    }
}

Patroon: multi-entity extractie

Wanneer een tekst meerdere soorten entiteiten bevat, is de verleiding groot om per familie één extractie uit te voeren. Het multi-entity schema doet het beter: het vraagt om personen, organisaties, datums en bedragen in één enkele pass. Het voordeel is niet alleen het besparen van calls; het model ziet de tekst één keer en kan relaties leggen tussen wat het vindt – een persoon koppelen aan zijn organisatie, een bedrag associëren met de context die er betekenis aan geeft.

De duplicatie bij datums, date_brute en date_iso, verdient het om in uw eigen schema’s behouden te blijven: dit behoudt de oorspronkelijke formulering voor auditing terwijl het een genormaliseerde waarde levert. Het veld contexte, aanwezig bij datums en bedragen, speelt dezelfde rol: zonder dit veld weet niemand of 12.000 euro een offerte, een boete of een jaarbudget was.

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
}

Best practices voor complexe schema’s

Vier gewoonten voorkomen de meeste teleurstellingen. Begin eenvoudig: valideer een plat object op uw echte data voordat u nesting toevoegt, anders weet u niet of een fout voortkomt uit het schema of uit de moeilijkheidsgraad van de taak. Geef vervolgens het optionele veld op, wat de strikte modus verbiedt, en maak het in plaats daarvan nullable. Respecteer ook een empirische limiet: voorbij drie of vier niveaus van nesting daalt de kwaliteit, en het is beter de extractie in twee passen te splitsen: eerst de lijst van modules, vervolgens één call per module om de lessen te detailleren. Houd tot slot de taakverdeling in gedachten: het schema en zijn enums beperken de structuur, de systeemprompt stuurt de inhoud. Als het model correct sorteert maar de verkeerde informatie extraheert, is het de prompt die u moet bijstellen.

Het geval dat alles test: het organigram

Pak het recursieve geval aan, het meest leerzame deel van de les. Definieer een schema om een bedrijfsorganigram te extraheren, waarbij elke medewerker ondergeschikten kan hebben die zelf ook medewerkers zijn. Test dit op een tekst die een organisatie van vijftien tot twintig personen beschrijft, geschreven in proza en niet als lijst: dit is waar het model rapportagelijnen moet afleiden uit zinnen als “rapporteert aan” of “binnen het team van”.

Verifieer of hiërarchische relaties correct genest zijn, en let op personen die ver verwijderd van hun manager worden genoemd – dit is het gebruikelijke breekpunt. Voeg tot slot enums toe op rollen (directie, management, operationeel) en observeer of de beperking de rapportagelijn verbetert of verslechtert: het afdwingen van een categorisering kan het model helpen of het juist naar willekeurige keuzes duwen bij hybride profielen.

Belangrijkste punten

  • Geneste lijsten zijn het meest voorkomende patroon in productie
  • Enums worden toegepast op generatieniveau – maak er gebruik van
  • Simuleer unions met een discriminatorveld en nullable velden
  • $defs maakt recursieve structuren mogelijk (commentaren, bomen)
  • Beperk de nestingdiepte tot 3-4 niveaus