Repérez les propriétés de schéma qui pourraient poser plusieurs questions à la fois — comparez les lectures concurrentes côte à côte et fixez chaque propriété à un sens unique avant la collecte des données.
Entity Enricher considère les LLM comme des bases de connaissances interrogeables, et un nom de propriété est la question que vous posez. Lorsque le nom admet plusieurs lectures, chaque modèle en choisit une en silence : size sur une entreprise revient sous forme d'effectif chez un modèle, de chiffre d'affaires chez un autre et de surface au sol chez un troisième. Les modèles ne sont pas en désaccord sur un fait. Ils ont répondu à des questions différentes, et votre colonne contient désormais un mélange de réponses qu'aucun consommateur en aval ne peut distinguer.
Fixer le sens est ce qui rend un enrichissement comparable d'un modèle à l'autre et stable dans le temps. Cela assainit aussi tout ce qui suit : la fusion multi-modèles cesse de voir des conflits qui sont en réalité deux questions distinctes, et les comparaisons de benchmark cessent de pénaliser les modèles parce qu'ils ont lu votre schéma autrement que la référence.
Un fait qui change simplement avec le temps n'est pas une ambiguïté. Un schéma est un contrat durable : un ceo nommé sans détour désigne « le PDG au moment de l'enrichissement », et réexécuter le schéma l'an prochain doit renvoyer le nouveau. La vérification ne propose jamais de figer une date dans un nom — cela casserait toutes les exécutions futures.
Toute la vérification tient en une question, posée pour chaque propriété : en lisant son nom dans le contexte de son objet parent, combien de choses distinctes pourrait-elle demander ? Le compte est le verdict.
| Interprétations | Verdict | Ce que cela signifie |
|---|---|---|
| Exactement une | Effacer | Tous les modèles recherchent la même chose. Aucun badge, rien à corriger. |
| Deux ou plus | Ambigu | Chaque modèle s'arrête sur sa propre lecture : la colonne mélange donc silencieusement des réponses à des questions différentes. La vérification nomme les lectures concurrentes et propose une formulation qui n'en retient qu'une. |
| Aucun | Non mappable | Le nom ne désigne rien que possède l'objet parent : le modèle ne peut donc pas retrouver de valeur — il en invente une. Les interprétations listées sont celles que l'analyseur a envisagées puis rejetées, et le remède est un renommage ou une suppression : aucune description ne peut donner à une entité une propriété qu'elle n'a pas. |
Une propriété qui ne désigne qu'une seule chose peut tout de même être signalée lorsque la valeur n'est pas cadrée : le lecteur sait ce qui est demandé, mais pas sous quelle forme la réponse arrive. Voici les cas récurrents :
| Sous-cas | Exemple | Ce qui reste ouvert |
|---|---|---|
| Référent peu clair | Companysize | Le nom renvoie à plusieurs faits distincts que le parent possède réellement — effectif, chiffre d'affaires, surface au sol. Rien dans le nom ne tranche. |
| Mesure ou unité peu claire | Companyannual_revenue | Un seul fait, mais aucune devise, aucune période et aucun cadrage brut/net — une réponse plausible peut se tromper de trois ordres de grandeur tout en restant « correcte ». |
| Échelle ou sens peu clairs | Supplierrisk_score | Aucune plage ni polarité indiquée : 0–10 ou 0–100, et une valeur élevée signifie-t-elle plus sûr ou plus risqué ? Deux modèles peuvent s'inverser l'un l'autre. |
| Périmètre ou limite flous | Companyemployees | Quel sous-ensemble, quel niveau d'agrégation, selon quel point de vue — l'ensemble du groupe ou ce site, effectif en personnes ou en équivalents temps plein, prestataires inclus ou exclus. |
| Non mappable | Authorrelease_year | Un auteur n'a pas d'année de parution — ses livres en ont une. Le modèle ne peut pas la trouver, il l'invente donc. Renommez-la avec quelque chose que le parent possède, ou déplacez-la vers l'objet qui la détient. |
Les propriétés rédactionnelles — description, summary, notes, bio — ne sont jamais signalées. Leur formulation varie évidemment d'un modèle à l'autre, mais la question posée est parfaitement claire, et c'est tout ce que juge cette vérification. L'ambiguïté porte sur la question, jamais sur la ressemblance des réponses.
Un verdict isolé (« ce n'est pas clair ») vous laisse deviner ce que l'analyseur avait en tête. Chaque constat est donc accompagné de ses interpretations : deux à quatre lectures courtes et distinctes que la propriété admet, la plus probable en premier. Cette liste constitue le constat — si l'analyseur ne parvient pas à nommer deux lectures, le constat est écarté comme du bruit plutôt que de vous être présenté.
annual_revenue sur une CompanyS'y ajoute une description suggérée qui n'en retient qu'une seule — ici, « chiffre d'affaires total du groupe en USD pour le dernier exercice clos, avant déduction des retours ». L'appliquer ne coûte rien : la description parvient au modèle d'enrichissement exactement comme le nom, mais la propriété conserve son nom, donc aucun contrat de données ne bouge. Lorsque c'est le nom lui-même qui induit en erreur, le constat comporte aussi des noms suggérés.
Voir les interprétations énoncées noir sur blanc tranche généralement la question plus vite que n'importe quelle explication : vous reconnaissez celle que vous aviez en tête, et les autres sont ce que vous receviez sans le savoir.
Après la génération d'un échantillon, l'analyseur examine les noms de ses propriétés et renvoie un rapport d'ambiguïté. Les renommages sans ambiguïté sont appliqués automatiquement aux clés inventées par l'IA (jamais aux champs que vous avez nommés vous-même), si bien que l'échantillon que vous relisez se lit déjà mieux. Il signale également les propriétés trop spécialisées — des traits issus de l'instance d'exemple qui ne conviennent qu'à un sous-type (les médailles d'un athlète sur une entité Person générique) — et suggère un type d'entité plus étroit. La vérification du périmètre d'identité s'exécute ici comme un appel distinct, juste après : elle fixe la forme des éléments liés avant que vous ne relisiez l'échantillon. Les échantillons fondés sur des pièces jointes sont ignorés — leurs valeurs proviennent du document source, et non de la mémoire du modèle.
Une fois un schéma généré enregistré, une passe finale annote chaque propriété avec son verdict d'ambiguïté et propose des renommages pour celles qui restent ouvertes. Les sites de relation sont déjà annotés à ce stade — la génération évalue elle-même leur cadrage, comme l'une de ses propres étapes — la passe finale ne couvre donc que les noms de propriétés. Cette étape se fait au mieux : en cas d'échec, la génération elle-même n'est pas affectée.
Le bouton Revérifier lance les deux vérifications — noms de propriétés et sites de relation — en deux appels parallèles. C'est le seul endroit qui propose une description réécrite plutôt qu'un renommage. Il n'analyse que ce qui n'est pas encore annoté, et bascule vers une réanalyse complète une fois que tout est annoté.
Le JSON d'exemple que vous collez pour créer un schéma peut être analysé sans état — vous obtenez un rapport des noms de propriétés ambigus ou non mappables, et des éléments liés qui mélangent des faits d'entité et des faits d'association, sans que rien ne soit modifié.
Un même constat propose un renommage à un endroit et une description à un autre, et la raison mérite d'être connue. Au moment de la génération, la description n'existe pas encore de façon indépendante — elle est rédigée à partir du nom, et ne peut donc que répéter l'ambiguïté. Le nom est la seule chose qui puisse être corrigée, et rien n'en dépend encore. C'est pourquoi la génération d'exemples et la passe finale de génération de schéma proposent toutes deux des renommages.
Une fois le schéma en production, renommer une propriété déplace des colonnes, casse des requêtes et re-clé les tables synchronisées, alors qu'une description plus précise atteint le modèle tout aussi directement sans rien changer d'autre. La règle est donc simple : tant que rien ne dépend du schéma, renommez ; une fois qu'il est en production, fixez la description — et gardez le renommage en réserve pour les cas où le nom lui-même est le problème.
La vérification est purement indicative. Rien n'analyse vos schémas enregistrés en arrière-plan : elle s'exécute à la génération, et lorsque vous cliquez sur Revérifier. Elle ne bloque jamais la génération, ne rejette jamais un enrichissement, et ses annotations sont retirées de chaque prompt envoyé aux modèles d'enrichissement — elle vous informe, vous, pas l'IA.
Les propriétés signalées affichent un badge « ambiguë » dans l'Éditeur de workflow : orange lorsque les lectures se recouvrent largement et ne diffèrent que sur des cas limites, rouge lorsque les lectures concurrentes produiraient des données sensiblement différentes. Les propriétés jugées claires ne portent aucun badge. Au survol du badge s'affichent la note de l'analyseur, les lectures concurrentes trouvées ainsi que la description ou les noms suggérés — la décision et le correctif se trouvent ainsi dans la même infobulle.
Un verdict porte à la fois sur le nom et la description d'une propriété : renommer une propriété ou modifier sa description supprime donc son annotation. L'éditeur met en évidence ces propriétés comme obsolètes et propose une nouvelle vérification, qui n'analyse que ce qui manque. C'est exactement ce que vous voulez après avoir appliqué un correctif suggéré : la nouvelle vérification confirme si la nouvelle formulation fixe réellement une lecture unique.
Le cadrage d'identité est une seconde vérification, exécutée via son propre appel de modèle en parallèle de la passe d'ambiguïté et rapportée avec elle. Elle examine chaque site de relation — les éléments d'un tableau lié et les objets imbriqués : lorsque l'un d'eux mêle des faits sur l'entité liée elle-même (son nom, son pays) et des faits sur l'association (un rôle tenu pour ce parent, une désignation propre à ce parent), les deux partagent une seule identité — et les ré-enrichissements écrasent les faits d'association d'un parent à l'autre. Ces sites portent une puce « faits mêlés » de couleur ambre dont l'infobulle indique la forme recommandée : les champs propres à l'entité imbriqués dans un sous-objet, les champs d'association conservés sur l'élément. Lorsque l'élément comporte déjà un tel sous-objet, la correction est plus légère — les champs mal placés y sont simplement déplacés.
La scission est appliquée lors de la génération de l'échantillon, avant que vous n'approuviez celui-ci : la structure est fixée sur le premier échantillon, chaque site restructuré est listé dans les avertissements de génération, et les autres échantillons du traitement par lot sont générés selon la structure ainsi fixée. Les schémas générés à partir d'un nouvel échantillon sont donc normalement propres. Les échantillons fondés sur des documents joints sont laissés tels que leurs sources l'impliquaient et reçoivent la puce à la place.
La génération de schéma ne restructure jamais l'échantillon que vous avez approuvé — elle évalue les mêmes sites et signale ce qu'elle trouve. Sur un schéma existant ou écrit à la main, c'est donc la puce qui porte la correction : elle propose une scission en un clic qui restructure l'échantillon et régénère le schéma à partir de celui-ci. La structure est le contrat : on la modifie en régénérant depuis un nouvel échantillon, jamais par une retouche sur place. Un site que vous choisissez de ne pas scinder continue de fonctionner — il conserve simplement une identité partagée, ainsi que la puce. La puce disparaît d'elle-même lorsque l'ensemble des champs de l'élément change.
La vérification peut être désactivée schéma par schéma depuis le menu déroulant de l'éditeur de workflow. Une fois désactivée, la passe post-génération est ignorée, les pastilles, le bouton Revérifier et les avertissements d'obsolescence sont masqués, et les points de terminaison d'analyse répondent par une erreur ambiguity_check_disabled. Les annotations existantes sont conservées (simplement masquées), et réactiver la vérification sur un schéma jamais analysé la lance automatiquement.
Tout schéma généré démarre avec la vérification activée, y compris les schémas générés à partir de documents joints. L'ambiguïté tient à la formulation du schéma, non à l'origine des valeurs d'une exécution : le document a fixé ces valeurs une fois, tandis que le schéma sera réutilisé sur des entités qu'il ne couvrait pas. Ce que le document change, c'est l'étape exemple — ses noms de propriétés proviennent du vocabulaire du document source, ils ne sont donc jamais renommés dans le code, et c'est le schéma construit à partir d'eux qui porte la vérification.
« Le chiffre d'affaires annuel de l'entreprise » n'apporte aucune information que le nom ne portait déjà : l'analyseur traite donc une telle description comme si elle était absente et juge le nom seul. Une description justifie sa présence en précisant l'unité, la période, l'échelle ou la limite.
Les notes et les interprétations de l'analyseur sont rédigées dans la langue de votre interface : un utilisateur français voit des lectures en français, un utilisateur japonais des lectures en japonais. Les noms de propriétés suggérés restent en anglais, conformément aux conventions de nommage des schémas.
Chaque analyse est un véritable appel de modèle (peu coûteux) — deux appels lancés en parallèle lorsqu'il y a aussi des sites de relation à délimiter. Chacun est enregistré comme un prompt à part entière sur l'enregistrement, sous le type ambiguity_analysis, et déduit des crédits comme tout autre usage de l'IA. Les nouvelles vérifications incrémentales ne facturent que les propriétés et les sites réellement analysés.
La génération d'exemples et de schémas est elle-même guidée pour ne nommer qu'une seule chose par propriété et pour rédiger des descriptions qui précisent l'unité, l'échelle et la limite — et, pour les listes discutables, une borne supérieure dans la description plutôt qu'un nombre imposé dans le nom. La plupart des schémas sortent donc propres, et l'analyseur n'a plus qu'à rattraper les retardataires.
Le contrôle est disponible par programmation :
| Surface | Description |
|---|---|
POST /api/schema/analyze-sample | Analyser un échantillon JSON collé — les deux vérifications en parallèle derrière une seule requête, rapport sans état, rien n'est modifié |
POST /api/schema/saved/{id}/analyze | Analyser un schéma enregistré et écrire les annotations des deux vérifications — incrémental par défaut, force=true réanalyse tout |
POST /api/schema/scoping-split | Appliquer une scission « faits mêlés » à un jeu d'échantillons — déterministe, gratuit, rien n'est enregistré ; réinjectez les échantillons renvoyés dans la génération de schéma |
analyze_sample | Outil MCP — le même rapport d'échantillon sans état, les deux vérifications, depuis Claude ou tout client MCP |
analyze_schema | Outil MCP — annote un schéma enregistré ; à combiner avec update_schema pour appliquer une description suggérée ou un renommage |
Les constats reviennent avec un kind (ambiguous ou unmappable), un level, une note, la liste interpretations et le correctif suggéré. Sur un schéma enregistré, ils sont stockés sur chaque propriété sous ambiguity ; la génération d'échantillon les renvoie sous ambiguity_report.
Consultez la référence de l'API et le guide du serveur MCP pour l'authentification et le catalogue complet des outils.
Comment les schémas sont générés avec autocorrection et post-traitement.
Les couches de défense qui empêchent les modèles de fabriquer des données.
Comparez les modèles sur un scénario enregistré, résultat et coût côte à côte.