Salidas de IA con JSON Schema: válido no significa verdadero
El modelo devuelve un objeto impecable. Tu programa lo lee sin errores y una marca verde aparece en pantalla. Sin embargo, la referencia apunta a la página dos de un documento que solo tiene una. El formato pasó la prueba; el dato todavía necesita una comprobación diferente.
Esta distinción ayuda a diseñar extracciones de documentos y otras funciones con IA. Un contrato de datos permite detectar ciertos errores antes de que lleguen al resto de la aplicación. Conviene escribir también qué queda fuera de ese contrato.
Define una salida pequeña
En este ejemplo ficticio pedimos una referencia y la página donde aparece. properties describe los campos; required exige su presencia y additionalProperties: false rechaza campos no declarados en este objeto sencillo. Definir propiedades no las vuelve obligatorias por sí solo: así lo documenta la referencia oficial de objetos de JSON Schema.
El siguiente código usa Python y el paquete jsonschema. Si hace falta instalarlo, utiliza un entorno virtual; el comando es python -m pip install jsonschema. La documentación del validador explica la validación de esquemas e instancias.
from jsonschema import Draft202012Validator
esquema = {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"referencia": {"type": "string", "minLength": 1},
"pagina": {"type": "integer", "minimum": 1}
},
"required": ["referencia", "pagina"],
"additionalProperties": False
}
Draft202012Validator.check_schema(esquema)
validar = Draft202012Validator(esquema)
validar.validate({"referencia": "A-104", "pagina": 2})
print("Estructura válida; falta contrastar el documento")
El esquema y los valores son de demostración. Comprobé este ejemplo: acepta el objeto mostrado y rechaza una página como texto, una página cero, un campo adicional y la ausencia de la referencia o la página. No necesita llamar a un modelo para ejecutar estas pruebas.
Pon a prueba la marca verde
La salida con pagina: 2 cumple el esquema. Esa comprobación no abre un PDF ni cuenta sus páginas. Si el documento del caso tiene una sola, hace falta contrastarlo y devolver una incidencia a la aplicación. El identificador A-104 también podría estar bien escrito y no aparecer en el original.
Propongo conservar por separado la salida recibida, el resultado de la validación estructural y la comprobación contra la fuente. Para esta última, el flujo puede guardar el identificador del archivo y el fragmento revisado, respetando la información que el equipo tenga permiso de conservar. Una cadena vacía, un dato ausente y una discrepancia con el documento deben tener rutas explícitas.
Revisa también las opciones del validador
Si después añades fechas o correos, comprueba cómo trata tu implementación format. En python-jsonschema, comprobar formatos requiere configurar esa capacidad; no basta con imaginar que cualquier etiqueta activa todas las verificaciones. La documentación de validación de formatos describe esa diferencia. Además, que una fecha tenga un formato aceptable no demuestra que corresponda al documento.
Cierra el recorrido con una decisión
Finalmente, define qué puede hacer el sistema cuando cada prueba pasa. Guardar una extracción para revisión, enviar una propuesta a una cola y ejecutar una acción son estados distintos. Mi criterio de diseño es que el resultado estructurado aporte datos al flujo; los permisos para actuar deben estar definidos por el producto.
Empieza con un caso que funciona, otro mal formado y otro que parece correcto pero contradice la fuente. Esa pequeña colección ofrece una explicación concreta de lo que protege tu contrato y de la comprobación que todavía debes construir.



