IDP — Build Schema

IDP — Build Schema

Tipo: idp-build-schema  ·  Paquete: IDP Activities v1.20.4  ·  Salida: List<object>

Desde: v1.1.0

Traduce una taxonomía a los JSON Schema que consume AI — Extract. Por cada campo pide tres cosas: el valor interpretado, el texto literal del documento del que sale y el número de línea donde aparece — que es lo que IDP — Ground usa después para localizarlo. En el Designer en español aparece como IDP — Construir esquema.

El flujo normal ya no la usa

IDP — Extract extrae todos los campos en una sola llamada (sin gramática estricta), así que no trocea el esquema en lotes ni usa esta actividad. IDP — Build Schema queda como pieza de bajo nivel para quien monte un pipeline de extracción a mano.

Cómo funciona

Valida la taxonomía y la trocea en lotes: un modelo con salida garantizada compila el esquema antes de generar, y un esquema demasiado grande se rechaza. Cada lote lleva como máximo maxFields celdas: un campo escalar cuenta 1 y una tabla cuenta una por columna. Una tabla nunca se parte entre lotes, porque sus columnas tienen que ir juntas para devolver filas completas.

El log dice cuántos campos (y celdas) hay y en cuántos lotes quedaron. Si una tabla tiene por sí sola más columnas que maxFields, va en su propio lote igualmente y el log lo advierte: si el modelo rechaza ese esquema, ese es el motivo.

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
taxonomy	string | Dictionary	—	La taxonomía: la ruta de un .json, el JSON como texto, o el objeto. Describe un tipo de documento, no un layout.

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
maxFields	int	7	Cuántas celdas van en cada lote (entero positivo). Una tabla cuenta una vez por columna y nunca se parte. Subirlo reduce el número de llamadas, pero el modelo rechaza un esquema demasiado grande: cámbialo solo si puedes volver a probar la taxonomía. Desde la versión 1.5.0.

Salida

Devuelve una List<object>: un JSON Schema por lote, cada uno listo para pasárselo tal cual a AI — Extract. Una taxonomía pequeña devuelve una lista de un solo elemento.

Cada esquema tiene raíz "type": "object" con una propiedad por campo del lote. Por campo se pide { value, valueRaw, line }: line siempre (-1 si el campo no aparece), y value/valueRaw se omiten cuando el campo no está, en vez de inventarse. Un campo date se pide como texto con formato de fecha, y un boolean se lee como casilla (☑ marcada, ☐ vacía). Una tabla pide una lista de filas con esa misma forma por celda. Pasa todas las respuestas, en una lista, a IDP — Ground: ahí se juntan.

La taxonomía

Describe un tipo de documento, no una plantilla. Ahí está el negocio: la capa visual cambia de un emisor a otro, pero la semántica no. Un solo factura-proveedor.json sirve para todos los proveedores.

{
  "documentType": "factura-proveedor",
  "description": "Factura de compra de un proveedor. El formato varía entre emisores.",
  "fields": [
    {
      "name": "numero",
      "type": "string",
      "description": "Número de la factura, tal y como aparece impreso",
      "minConfidence": 0.95
    },
    {
      "name": "proveedor",
      "type": "string",
      "description": "Razón social de quien emite la factura",
      "minConfidence": 0.6
    }
  ]
}

Clave	Obligatoria	Qué es
documentType	sí	Identificador del tipo de documento.
description	no	Qué es este documento. Se le pasa al modelo como contexto.
fields	sí	Lista de campos; no puede estar vacía ni repetir nombres.
fields[].name	sí	Nombre del campo en el resultado.
fields[].type	no	string (por defecto), number, integer, boolean, date o table.
fields[].description	sí	Qué es este campo.
fields[].minConfidence	no	Confianza exigida para darlo por bueno, entre 0 y 1. Por defecto 0.8.
fields[].fields	solo en table	Las columnas de la tabla.

Tablas: campos que se repiten

Un campo de tipo table es un campo que se repite: una fila por cada aparición en el documento. Es lo que permite extraer las líneas de una factura, un listado de repuestos o cualquier cosa con N entradas.

{
  "name": "items",
  "type": "table",
  "description": "Líneas de detalle de la factura",
  "fields": [
    { "name": "descripcion", "type": "string", "description": "Descripción del producto o servicio", "minConfidence": 0.7 },
    { "name": "cantidad",    "type": "number", "description": "Cantidad facturada",                 "minConfidence": 0.9 },
    { "name": "valor",       "type": "number", "description": "Valor total de la línea",            "minConfidence": 0.9 }
  ]
}

Las columnas se declaran igual que un campo normal, con su propia description y su propio minConfidence — porque una cantidad y una descripción no se leen con la misma fiabilidad. La tabla en sí no lleva minConfidence: no se verifica como un todo, se verifica celda a celda.

Sin tablas dentro de tablas

Las columnas solo pueden ser escalares (string, number, integer, boolean, date). Una tabla anidada no existe en estos documentos, y permitirla complicaría el esquema, el grounding y la pantalla de revisión a cambio de nada.

Una tabla vacía no es un error

Si el documento no tiene esas filas, el resultado es una lista vacía y no se marca a revisión: “esta factura no tiene notas de crédito” es un estado real y frecuente, y marcarlo mandaría a una persona cada documento del lote.

La descripción no es documentación: es el prompt

El modelo lee la descripción de cada campo para decidir qué poner en él. Por eso es obligatoria. Escríbela como se la explicarías a alguien que ve el documento por primera vez: “número de la factura, tal y como aparece impreso” funciona mucho mejor que “número”.

Los umbrales van por campo

minConfidence es la confianza mínima para aceptar el campo sin que lo mire una persona. Cuanto más alto, más estricto.

Va por campo a propósito. Un número de factura o de serie es alfanumérico y sin redundancia lingüística: es justo donde el OCR falla, y donde equivocarse sale caro — así que se le exige casi certeza (0.95). Una razón social se lee siempre bien y el contexto la corrige sola, así que exigirle lo mismo solo mandaría a revisión trabajo que no la necesita (0.6).

Un umbral único para todo el documento manda todo a revisión y mata el ROI.

Ejemplo

El pipeline a mano, con un AI — Extract por lote:

IDP — Load Document   path = rutaDoc   → output: doc
IDP — Build Schema    taxonomy = asset("taxonomias/factura-proveedor.json")   → output: esquemas
Create List           → output: respuestas
Foreach   items = esquemas   itemVariable = esquema
  AI — Extract   prompt = doc["text"]
                 schema = esquema
                 → output: parcial
  Add to List    list = respuestas   item = parcial
IDP — Ground          document   = doc
                      extraction = respuestas
                      taxonomy   = asset("taxonomias/factura-proveedor.json")
                      → output: res

Errores comunes

Mensaje	Causa y solución
'maxFields' debe ser un número entero positivo. Se recibió: …	Valor de maxFields no válido.
'taxonomy' es obligatorio. / 'taxonomy' no es un JSON válido: … / 'taxonomy' debe ser un objeto JSON, pero es …	Falta la taxonomía o no es un objeto JSON. Si pasas una ruta, comprueba que el archivo exista.
La taxonomía debe declarar un 'documentType'. / La taxonomía debe declarar un arreglo 'fields'. / El arreglo 'fields' de la taxonomía está vacío; no hay nada que extraer.	Falta una clave obligatoria de la taxonomía.
La taxonomía declara el campo '…' más de una vez.	Nombres de campo repetidos (sin distinguir mayúsculas).
Cada campo de la taxonomía debe tener un 'name'. / El campo '…' no tiene 'description'. El modelo la lee para decidir qué va en este campo, así que no es opcional.	Un campo sin nombre o sin descripción.
El campo '…' tiene un tipo desconocido '…'. Tipos válidos: string, number, integer, boolean, date, table. / La columna '…' tiene el tipo '…'. Las columnas de una tabla deben ser de uno de estos tipos: string, number, integer, boolean, date.	Tipo no válido (o una tabla dentro de una tabla).
Campo '…': 'minConfidence' debe estar entre 0 y 1. Se recibió: …	Umbral fuera de rango o no numérico.
El campo '…' es una tabla, así que debe declarar un arreglo 'fields' con sus columnas. / La tabla '…' no declara columnas. / El campo '…' declara 'fields' pero su tipo es '…'. Solo un campo de tipo 'table' tiene columnas.	Estructura de tabla incorrecta.

Actividades relacionadas

• IDP — Ground — el paso siguiente: localizar y validar lo extraído.
• AI — Extract — la llamada al modelo que usa cada esquema.
• IDP — Extract — todo el pipeline en una actividad.