Detecte las propiedades del esquema que podrían estar formulando más de una pregunta: compare las lecturas rivales en paralelo y fije cada propiedad a un único significado antes de recopilar los datos.
Entity Enricher trata los LLM como bases de conocimiento consultables, y el nombre de una propiedad es la pregunta que usted formula. Cuando el nombre admite varias lecturas, cada modelo elige una sin avisar: así, size en una empresa vuelve como una plantilla en un modelo, una cifra de ingresos en otro y una superficie en un tercero. Los modelos no discreparon sobre un hecho: respondieron a preguntas distintas, y su columna contiene ahora una mezcla de respuestas que ningún consumidor posterior puede distinguir.
Fijar el significado es lo que hace que un enriquecimiento sea comparable entre modelos y estable en el tiempo. Además, ordena todo lo que viene después: la fusión multimodelo deja de ver conflictos que en realidad son dos preguntas distintas, y las comparaciones de benchmark dejan de penalizar a los modelos por leer su esquema de forma distinta a como lo hizo la referencia.
Un dato que sencillamente cambia con el tiempo no es una ambigüedad. Un esquema es un contrato duradero: una propiedad llamada simplemente ceo significa “el CEO en el momento del enriquecimiento”, y volver a ejecutar el esquema el año que viene debería devolver el nuevo. La comprobación nunca propone fijar una fecha en el nombre; eso rompería todas las ejecuciones futuras.
Toda la comprobación es una sola pregunta, planteada a cada propiedad: al leer su nombre en el contexto de su objeto padre, ¿cuántas cosas distintas podría estar pidiendo? El recuento es el veredicto.
| Interpretaciones | Veredicto | Qué significa |
|---|---|---|
| Exactamente una | Limpiar | Todos los modelos consultan lo mismo. Sin etiqueta, nada que corregir. |
| Dos o más | Ambiguo | Cada modelo se decanta por su propia lectura, así que la columna mezcla en silencio respuestas a preguntas distintas. La comprobación nombra las lecturas rivales y propone una redacción que conserva solo una. |
| Ninguno | No asignable | El nombre no designa nada que el objeto padre tenga, de modo que el modelo no puede buscar un valor: lo inventa. Las interpretaciones enumeradas son las que el analizador consideró y descartó, y la solución es renombrar o eliminar: ninguna descripción puede dar a una entidad una propiedad que no tiene. |
Una propiedad que designa una sola cosa puede señalarse igualmente cuando el valor carece de marco: se sabe qué se pide, pero no en qué términos se devuelve. Estos son los casos recurrentes:
| Subcaso | Ejemplo | Qué queda abierto |
|---|---|---|
| Referente poco claro | Companysize | El nombre apunta a varios datos distintos que el padre sí tiene: plantilla, ingresos, superficie. Nada en el nombre permite elegir. |
| Medida o unidad poco clara | Companyannual_revenue | Un solo dato, pero sin moneda, sin periodo y sin marco bruto/neto: una respuesta plausible puede desviarse tres órdenes de magnitud y seguir siendo "correcta". |
| Escala o dirección poco clara | Supplierrisk_score | Sin rango ni polaridad declarados: ¿0–10 o 0–100? ¿Y un número alto es más seguro o más arriesgado? Dos modelos pueden interpretarlo de forma inversa. |
| Alcance o límite poco claro | Companyemployees | Qué subconjunto, qué nivel de agregación, desde qué perspectiva — todo el grupo o esta sede, número de personas o equivalentes a tiempo completo, con o sin contratistas. |
| No asignable | Authorrelease_year | Un autor no tiene año de publicación; sus libros sí. El modelo no puede consultar este dato, así que lo inventa. Renómbrelo con algo que pertenezca al elemento padre o muévalo al objeto que sí lo tiene. |
Las propiedades de texto libre —description, summary, notes, bio— nunca se marcan. Es evidente que su redacción varía de un modelo a otro, pero la pregunta que se plantea es perfectamente clara, y eso es lo único que evalúa esta comprobación. La ambigüedad tiene que ver con la pregunta, nunca con cuánto se parecen las respuestas entre sí.
Un veredicto por sí solo (“esto no está claro”) le obliga a adivinar qué tenía en mente el analizador. Por eso cada hallazgo incluye sus interpretaciones: de dos a cuatro lecturas breves y distintas que admite la propiedad, empezando por la más probable. Esa lista es el hallazgo: si el analizador no puede nombrar dos lecturas, el hallazgo se descarta como ruido en lugar de mostrarse.
annual_revenue en una EmpresaJunto a ellas se ofrece una descripción sugerida que conserva exactamente una: aquí, “ingresos totales del grupo en USD del último ejercicio fiscal cerrado, antes de devoluciones”. Aplicarla no cuesta nada: la descripción llega al modelo de enriquecimiento igual que el nombre, pero la propiedad conserva su nombre, por lo que ningún contrato de datos se altera. Cuando lo que induce a error es el propio nombre, el hallazgo incluye además nombres sugeridos.
Ver las interpretaciones desglosadas suele resolver la propiedad más rápido que cualquier explicación: reconoce la que tenía en mente, y las demás son las que ha estado recibiendo sin saberlo.
Una vez generada una muestra, el analizador revisa sus nombres de propiedad y devuelve un informe de ambigüedad. Los renombrados inequívocos se aplican automáticamente a las claves inventadas por la IA (nunca a los campos que usted mismo ha nombrado), de modo que la muestra que revisa ya se lee mejor. También señala las propiedades demasiado especializadas —rasgos filtrados desde la instancia de ejemplo que solo encajan en un subtipo (las medallas de un atleta en una Person genérica)— y sugiere un tipo de entidad más restringido. La comprobación de alcance de identidad se ejecuta aquí como una llamada propia, justo después: fija la forma de los elementos relacionados antes de que usted revise la muestra. Las muestras basadas en documentos adjuntos se omiten: sus valores proceden del documento de origen, no del recuerdo del modelo.
Una vez guardado un esquema generado, una pasada posterior anota cada propiedad con su veredicto de ambigüedad y sugiere nuevos nombres para las que siguen abiertas. Para entonces, los puntos de relación ya están anotados —la generación juzga su alcance por sí misma, como uno de sus propios pasos—, por lo que la pasada posterior solo cubre los nombres de las propiedades. Este paso es de mejor esfuerzo: si falla, la generación no se ve afectada.
El botón Volver a comprobar ejecuta ambas comprobaciones —nombres de propiedad y puntos de relación— como dos llamadas paralelas. Es el único lugar que sugiere reescribir la descripción en lugar de renombrar. Solo analiza lo que aún no tiene anotación y pasa a un reanálisis completo cuando todo está anotado.
El JSON de muestra que pega para crear un esquema puede analizarse sin estado: obtiene un informe de los nombres de propiedad ambiguos o no asignables y de los elementos relacionados que mezclan datos de la entidad con datos del emparejamiento, sin que se modifique nada.
El mismo hallazgo sugiere un cambio de nombre en un sitio y una descripción en otro, y conviene saber por qué. En el momento de la generación, la descripción aún no existe de forma independiente: se escribe a partir del nombre, por lo que solo puede repetir la ambigüedad. El nombre es lo único que se puede corregir, y todavía no depende nada de él. Por eso tanto la generación de muestras como la pasada posterior a la generación del esquema proponen cambios de nombre.
Una vez que el esquema está en producción, renombrar una propiedad mueve columnas, rompe consultas y cambia las claves de las tablas sincronizadas, mientras que una descripción más precisa llega al modelo con la misma inmediatez y no altera nada más. Por eso la regla es simple: antes de que nada dependa del esquema, renombre; una vez en producción, fije la descripción, y reserve el cambio de nombre para los casos en los que el problema sea el nombre en sí.
La comprobación es solo orientativa. Nada analiza sus esquemas guardados en segundo plano: se ejecuta en la generación y cuando pulsa Volver a comprobar. Nunca bloquea la generación ni rechaza un enriquecimiento, y sus anotaciones se eliminan de todos los prompts enviados a los modelos de enriquecimiento: le informa a usted, no a la IA.
Las propiedades señaladas muestran una etiqueta “ambigua” en el Editor de flujos de trabajo: ámbar cuando las lecturas se solapan en su mayoría y solo difieren en casos límite; roja cuando las lecturas rivales darían datos sustancialmente distintos. Las propiedades consideradas claras no llevan etiqueta. Al pasar el cursor sobre la etiqueta se muestran la nota del analizador, las lecturas rivales encontradas y la descripción o los nombres sugeridos, de modo que la decisión y la corrección están en el mismo tooltip.
El veredicto se emite sobre el nombre y la descripción de una propiedad en conjunto, de modo que renombrar una propiedad o editar su descripción elimina su anotación. El editor resalta esas propiedades como obsoletas y ofrece una nueva comprobación, que analiza solo lo que falta. Es justo lo que se necesita tras aplicar una corrección sugerida: la nueva comprobación confirma si la nueva redacción fija realmente una única lectura.
El alcance de identidad es una segunda comprobación, que se ejecuta como una llamada al modelo independiente junto a la pasada de ambigüedad y se comunica con ella. Revisa cada punto de relación —los elementos de un array relacionado y los objetos anidados—: cuando uno mezcla datos sobre la entidad relacionada en sí (su nombre, su país) con datos sobre la asociación (un cargo ocupado para este padre, una designación específica de cada padre), ambos comparten una única identidad, y los reenriquecimientos sobrescriben los datos de la asociación entre padres. Esos puntos llevan un chip «datos mezclados» ámbar cuyo tooltip muestra la forma recomendada: los campos propios de la entidad anidados en un subobjeto y los campos de la asociación mantenidos en el elemento. Cuando el elemento ya tiene ese subobjeto, la corrección es menor: los campos mal ubicados se trasladan al que ya existe.
La división se aplica durante la generación de la muestra, antes de que usted la apruebe: la estructura se fija en la primera muestra, todos los puntos reestructurados se enumeran en las advertencias de generación y las demás muestras del lote se generan según la estructura ya fijada. Por eso los esquemas generados a partir de una muestra nueva suelen salir limpios. Las muestras basadas en documentos adjuntos se dejan tal como sus fuentes las plantean y reciben el chip en su lugar.
La generación del esquema nunca reestructura la muestra que usted aprobó: evalúa los mismos puntos e informa de lo que encuentra. Por eso, en un esquema existente o escrito a mano, la corrección vive en el chip: ofrece una división en un clic que reestructura la muestra y regenera el esquema a partir de ella. La estructura es el contrato, así que se cambia regenerando desde una muestra nueva, nunca parcheándola sobre la marcha. Un punto que decida no dividir sigue funcionando: simplemente mantiene una única identidad compartida, y el chip. El chip desaparece por sí solo cuando cambia el conjunto de campos del elemento.
La comprobación puede desactivarse por esquema desde el menú de opciones adicionales del Editor de flujos de trabajo. Cuando está desactivada, se omite la pasada posterior a la generación, se ocultan los chips, el botón Volver a comprobar y los avisos de desactualización, y los endpoints de análisis responden con un error ambiguity_check_disabled. Las anotaciones existentes se conservan (solo se ocultan) y, al volver a activar la comprobación en un esquema que nunca se analizó, esta se ejecuta automáticamente.
Todo esquema generado empieza con la comprobación activada, incluidos los esquemas generados a partir de documentos adjuntos. La ambigüedad es una propiedad de cómo está redactado el esquema, no de dónde procedían los valores de una ejecución concreta: el documento fijó esos valores una vez, pero el esquema se seguirá reutilizando con entidades que nunca cubrió. Lo que el documento sí cambia es el paso de muestra: sus nombres de propiedad proceden del vocabulario del propio documento de origen, por lo que nunca se renombran en el código, y es el esquema construido a partir de ellos el que lleva la comprobación.
“Los ingresos anuales de la empresa” no añade ninguna información que el nombre no transmitiera ya, por lo que el analizador trata esa descripción como si no existiera y juzga únicamente el nombre. Una descripción se gana su lugar cuando precisa la unidad, el periodo, la escala o el límite.
Las notas e interpretaciones del analizador se redactan en el idioma de su interfaz: un usuario francés ve lecturas en francés; uno japonés, en japonés. Los nombres de propiedad sugeridos se mantienen en inglés, conforme a las convenciones de nomenclatura de los esquemas.
Cada análisis es una llamada real (económica) al modelo: dos, ejecutadas en paralelo, cuando además hay puntos de relación cuyo alcance definir. Cada una se registra como un prompt propio en el registro, bajo el tipo ambiguity_analysis, y se descuenta de los créditos como cualquier otro uso de IA. Las comprobaciones incrementales solo cobran las propiedades y los puntos realmente analizados.
La generación de muestras y de esquemas ya tiene la instrucción de nombrar una sola cosa por propiedad y de escribir descripciones que indiquen la unidad, la escala y el límite y, en las listas discutibles, un máximo en la descripción en lugar de un recuento forzado en el nombre. Por eso la mayoría de los esquemas salen limpios y el analizador solo tiene que detectar los casos rezagados.
La comprobación está disponible mediante programación:
| Superficial | Descripción |
|---|---|
POST /api/schema/analyze-sample | Analiza la muestra JSON pegada: ambas comprobaciones en paralelo tras una sola solicitud, informe sin estado, no se modifica nada |
POST /api/schema/saved/{id}/analyze | Analiza un esquema guardado y escribe las anotaciones de ambas comprobaciones: incremental por defecto; con force=true se reanaliza todo |
POST /api/schema/scoping-split | Aplica una división de «datos mezclados» a un conjunto de muestras: determinista, gratuita y sin guardar nada; reinyecte las muestras devueltas en la generación del esquema |
analyze_sample | Herramienta MCP: el mismo informe de muestra sin estado, con ambas comprobaciones, desde Claude o cualquier cliente MCP |
analyze_schema | Herramienta MCP: anota un esquema guardado; combínela con update_schema para aplicar una descripción sugerida o un cambio de nombre |
Los hallazgos se devuelven con un tipo (ambiguous o unmappable), un nivel, una nota, la lista de interpretaciones y la corrección sugerida. En un esquema guardado se almacenan en cada propiedad como ambiguity; la generación de muestras los devuelve bajo ambiguity_report.
Consulte la Referencia de la API y la guía del servidor MCP para la autenticación y el catálogo completo de herramientas.