> ## Documentation Index > Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Esquemas de datos clínicos > Configuración de esquemas JSON para la generación de documentación médica La propiedad `template` define la estructura de los datos clínicos que SofIA debe generar. Debe ser un esquema JSON Schema Draft-07 completo que especifique los campos, tipos y validaciones requeridas para la documentación médica. La prop `template` acepta un **JSON Schema** que define la estructura del reporte. A lo largo de esta página, "template" se refiere a la prop y "schema" se refiere al contenido del JSON Schema. **Nota:** Esta propiedad se llamaba anteriormente `toolsArgs`/`toolsargs`. El nombre legacy sigue siendo soportado pero está deprecado y será eliminado en v2.0. Use `template` en su lugar. ## Accesibilidad (a11y) Si tu integración envía un payload de configuración (con `template` o con `toolsargs` legacy), puedes incluir una variable adicional `accessibility` al mismo nivel para declarar preferencias visuales. Usa los nombres de propiedad exactamente como aparecen a continuación (claves de payload agnósticas al idioma). Para mantener consistencia, cada valor se define como un array de etiquetas/alias aceptados. ```json theme={null} { "template": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "consulta_general_v1", "type": "object", "properties": { "diagnostico": { "type": "string" } } }, "templateid": "consulta-general-v1", "accessibility": { "text_size": ["Text size", "Font size", "Large text"], "color_contrast": ["Color adjustment", "Color contrast", "High contrast mode"], "color_inversion": ["Color inversion"], "color_filters": ["Color filters", "Color blindness"], "bold_text": ["Bold text"], "reduce_transparency": ["Reduce transparency"], "grayscale": ["Grayscale"] } } ``` **Término técnico recomendado:** `Accessibility` (a11y). El número `11` representa las letras entre la `a` y la `y`. Las opciones de color y contraste suelen agruparse como `Visual accommodations` o `Display preferences`. ## Cómo Funcionan las Plantillas La **plantilla JSON Schema** y el **contexto de conversación** se proporcionan al SofIA SDK. El SDK envía los datos mediante **LangGraph Streaming** para el procesamiento de IA. La IA genera un **reporte estructurado** conforme al esquema, entregado al EHR/HIS mediante el callback `handle-report`. El `template` define **qué** datos extraer. La IA de SofIA lee el contexto de la conversación y rellena los campos del esquema automáticamente, entregando un reporte JSON estructurado que coincide con su esquema. ## Estructura requerida El esquema debe incluir: * **\$schema**: Referencia al estándar JSON Schema Draft-07 * **title**: Identificador del tipo de documento clínico * **type**: Debe ser "object" para documentos estructurados * **required**: Array con los campos obligatorios * **properties**: Definición detallada de cada campo La prop `template` por sí sola no habilita la generación de reportes — también debes configurar `templateid`. Sin ambas props, SofIA opera en modo solo chat: la transcripción de audio y el chat clínico funcionan completamente, pero el botón de generar se oculta porque no hay esquema que enviar a los agentes de IA para la extracción de datos estructurados. ## Ejemplo básico ```json theme={null} { "$schema": "http://json-schema.org/draft-07/schema#", "title": "create_clinical_notes/v1", "type": "object", "required": ["diagnostico_principal"], "properties": { "diagnostico_principal": { "type": "string", "description": "Diagnóstico principal del paciente", "source": "tu-master-personalizado" }, "sintomas": { "type": "array", "description": "Lista de síntomas observados", "items": { "type": "string" } }, "exploracion_fisica": { "type": "object", "properties": { "tension_arterial": { "type": "object", "properties": { "sistolica": {"type": "number", "minimum": 50, "maximum": 250}, "diastolica": {"type": "number", "minimum": 30, "maximum": 150} } }, "frecuencia_cardiaca": { "type": "number", "description": "Frecuencia cardíaca en latidos por minuto" } } } } } ``` ### Pasar templates al componente **Como atributo HTML** — envuelve el JSON en comillas simples, usa comillas dobles dentro: ```html theme={null} ``` **Programáticamente (recomendado para esquemas complejos)** — configura vía JavaScript: ```javascript theme={null} const sofia = document.querySelector('sofia-sdk'); sofia.template = mySchemaObject; // O como string: sofia.setAttribute('template', JSON.stringify(mySchemaObject)); ``` ## Fuentes de codificación clínica Hay dos formas de obtener códigos clínicos estandarizados en un campo: 1. **Establece el `source` del campo apuntando a un master.** Un *master* es una terminología o catálogo de códigos controlado que Omniloy mantiene para tu cuenta. El valor de `source` vincula el campo con ese master, de modo que SofIA normaliza el valor extraído contra él. ¿Necesitas codificar contra **tus propios datos** — un catálogo personalizado, un conjunto de códigos interno o una terminología de especialidad? [Contacta a support@omniloy.com](mailto:support@omniloy.com): el equipo de Omniloy provisiona el **master personalizado** para tu cuenta y te proporciona el valor de `source` a usar. Un `source` personalizado solo funciona una vez que su master ha sido creado para tu cuenta. 2. **Solicita la terminología en la `description` del campo** — p. ej. `"Diagnóstico principal con su código CIE-10"`. Los agentes de SofIA aplican la codificación solicitada durante la extracción, incluso sin un valor `source`. Es útil para solicitudes puntuales donde no hace falta un master dedicado. ## Campos especializados ### Fuente a terminologías médicas Apunta un campo a un master personalizado con `source` (provisionado por Omniloy — consulta [Fuentes de codificación clínica](#fuentes-de-codificación-clínica)). También puedes dirigir la codificación desde la `description` de cada campo, como se muestra abajo. Reemplaza `"tu-master-personalizado"` por el valor de `source` que Omniloy te proporcione: ```json theme={null} { "diagnostico": { "name": "diagnostico", "type": "array", "items": { "type": "object", "required": [ "code", "nombre" ], "properties": { "code": { "type": "string", "description": "Código de diagnóstico usando el CIE10 y siendo lo más específico posible con la información proporcionada." }, "nombre": { "type": "string", "description": "Nombre del diagnóstico usando el CIE10." }, "descripcion": { "type": "string", "description": "Justificación o descripción del diagnóstico usando el CIE10." } } }, "source": "tu-master-personalizado", "description": "Lista el/los diagnóstico(s) determinado(s) durante esta consulta médica, incluyendo nombre, descripción (justificación) y código CIE10 si aplica. Si no se establece ningún diagnóstico explícitamente, sugiere las posibilidades más probables basándote en la conversación." } } ``` ### Constantes vitales estructuradas ```json theme={null} { "constantes_vitales": { "type": "array", "description": "Constantes vitales del paciente", "items": { "type": "object", "required": ["parametro", "valor"], "properties": { "parametro": { "type": "string", "enum": ["Tensión Sistólica", "Tensión Diastólica", "Frecuencia Cardíaca", "Temperatura", "Saturación O2"] }, "valor": {"type": "number"}, "unidad": {"type": "string"}, "fecha_medicion": {"type": "string", "format": "date-time"} } } } } ``` ## Tipos de datos soportados ### Tipos básicos * **string**: Texto libre o controlado * **number**: Valores numéricos (enteros o decimales) * **boolean**: Valores verdadero/falso * **array**: Listas de elementos * **object**: Estructuras complejas anidadas ### Validaciones avanzadas ```json theme={null} { "edad": { "type": "number", "minimum": 0, "maximum": 150, "description": "Edad del paciente en años" }, "email": { "type": "string", "format": "email", "description": "Correo electrónico de contacto" }, "fecha_nacimiento": { "type": "string", "format": "date", "description": "Fecha de nacimiento (YYYY-MM-DD)" }, "genero": { "type": "string", "enum": ["Masculino", "Femenino", "Otro", "No especificado"], "description": "Género del paciente" } } ``` ## Limitaciones técnicas * **Tamaño máximo**: 100 KB por esquema * **Profundidad**: Máximo 10 niveles de anidación * **Complejidad**: Evite esquemas excesivamente complejos que puedan afectar el rendimiento ## Mejores prácticas ### Descripciones detalladas Proporcione descripciones claras y específicas para cada campo: ```json theme={null} { "description": "Diagnóstico principal según criterios clínicos establecidos, utilizando terminología CIE-10 cuando sea posible" } ``` ### Validaciones apropiadas Implemente validaciones que reflejen la realidad clínica: ```json theme={null} { "peso": { "type": "number", "minimum": 0.5, "maximum": 500, "description": "Peso del paciente en kilogramos" } } ``` ### Estructuras flexibles Diseñe esquemas que permitan variabilidad clínica: ```json theme={null} { "medicamentos": { "type": "array", "items": { "type": "object", "required": ["nombre"], "properties": { "nombre": {"type": "string"}, "dosis": {"type": "string"}, "frecuencia": {"type": "string"}, "via_administracion": {"type": "string"} } } } } ``` ## Personalización de propiedades ### La propiedad `isConfigurable` **Valor por defecto:** `true` (todos los campos son configurables por defecto) Cuando `isConfigurable` es `true` (valor por defecto), el profesional sanitario puede editar el valor del campo generado en la interfaz de SofIA antes de finalizar el reporte. Establezca a `false` para campos que deben generarse pero no ser editables. **Campo configurable (comportamiento por defecto):** ```json theme={null} { "treatment_plan": { "isConfigurable": true, "type": "string", "description": "Plan de tratamiento recomendado" } } ``` **Campo no configurable:** ```json theme={null} { "diagnostico": { "isConfigurable": false, "name": "diagnostico", "type": "array", "items": { "type": "object", "required": [ "code", "nombre" ], "properties": { "code": { "type": "string", "description": "Código de diagnóstico usando el CIE10 y siendo lo más específico posible con la información proporcionada." }, "nombre": { "type": "string", "description": "Nombre del diagnóstico usando el CIE10." }, "descripcion": { "type": "string", "description": "Justificación o descripción del diagnóstico usando el CIE10." } } }, "description": "Lista el/los diagnóstico(s) determinado(s) durante esta consulta médica, incluyendo nombre, descripción (justificación) y código CIE10 si aplica. Si no se establece ningún diagnóstico explícitamente, sugiere las posibilidades más probables basándote en la conversación." } } ``` ## Depuración de tu template ### Habilitar modo debug Añade `debug="true"` al componente SofIA para habilitar logs detallados en consola. Todos los logs del SDK tienen el prefijo `[Sofia SDK]`, lo que facilita filtrarlos en las DevTools del navegador. ```html theme={null} ``` En la Consola de DevTools de tu navegador, usa el filtro `[Sofia SDK]` para aislar los logs del SDK del resto de la salida de tu aplicación. ### Checklist de validación del template Antes de depurar en el navegador, verifica estos cinco puntos: 1. **JSON Schema válido** — incluye el header `"$schema": "http://json-schema.org/draft-07/schema#"` 2. **Tanto `template` como `templateid` están presentes** — el botón generar solo aparece cuando ambos están configurados 3. **`properties` definidas con al menos 1 campo** — un objeto `properties` vacío resulta en modo solo-chat 4. **Tamaño del esquema menor a 100KB** — esquemas más grandes son rechazados 5. **Los campos `required` coinciden con properties existentes** — cualquier discrepancia causa errores de validación ### Referencia de logs de consola Cuando `debug="true"` está habilitado, estos son los mensajes clave relacionados con templates y generación de reportes: | Mensaje en consola | Significado | Acción | | ----------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `[Sofia SDK] Settings - Template loaded: {n} fields` | El template fue parseado exitosamente con `n` campos | Ninguna — este es el mensaje esperado de éxito | | `[Sofia SDK] Settings - Template validation failed` | El JSON del template está malformado o le faltan claves requeridas del esquema | Verificar sintaxis JSON y asegurar que `$schema`, `type` y `properties` estén presentes | | `[Sofia SDK] Settings - Using fallback template` | El template local era inválido; el SDK usó el template del servidor como respaldo | Corregir la prop `template` local — verificar errores de sintaxis o tipos de campo inválidos | | `[Sofia SDK] API - Report generation started` | El usuario hizo clic en Generar; el procesamiento ha comenzado | Ninguna — esperar a que complete o falle | | `[Sofia SDK] API - Report generation completed` | El reporte fue generado y entregado a `handleReport` | Verificar los datos en tu callback `handleReport` | | `[Sofia SDK] API - Report generation failed: {error}` | La generación del reporte encontró un error | Revisar el mensaje de error para detalles (`configError`, `authError`, `apiError` o `settingsError`) | ### Problemas comunes **Síntoma**: El componente SofIA carga en modo solo-chat — no se ve el botón de generar. **Causa**: El botón de generar requiere que tanto `template` como `templateid` estén presentes y sean válidos. Si alguno falta o si el template tiene cero campos parseables, `hasTemplateConfig` se evalúa como `false` y el botón se oculta. **Solución**: 1. Verificar que ambos atributos `template` y `templateid` estén configurados en el componente 2. Habilitar `debug="true"` y buscar `Template loaded: {n} fields` — si `n` es 0 o el mensaje no aparece, el template es inválido 3. Validar que `template` contenga al menos una propiedad dentro de `properties` **Síntoma**: El callback `handleReport` se ejecuta pero el objeto del reporte es `{}` o contiene solo valores vacíos. **Causa**: Los campos del template no coinciden con el contexto de la conversación. SofIA extrae datos basándose en lo que se discutió — si la conversación no contiene información relevante para los campos de tu template, esos campos estarán vacíos. **Solución**: 1. Asegurar que la conversación cubra temas relacionados con los campos de tu template antes de hacer clic en Generar 2. Verificar que los valores de `description` de los campos sean claros y específicos — descripciones vagas llevan a una extracción deficiente 3. Habilitar `debug="true"` y verificar que aparezca `Report generation completed` (no `failed`) **Síntoma**: Algunos campos del reporte están poblados pero otros faltan o son null. **Causa**: La IA solo pudo extraer datos para campos que fueron discutidos en la conversación. Los campos marcados como `required` en tu esquema son priorizados, pero los campos opcionales pueden omitirse si la conversación no contiene información relevante. **Solución**: 1. Revisar qué campos faltan — ¿corresponden a temas discutidos en la conversación? 2. Añadir valores de `description` más específicos para ayudar a la IA a identificar información relevante 3. Considerar marcar los campos críticos como `required` en tu esquema **Síntoma**: El reporte generado usa una estructura diferente a tu template local. En modo debug, ves `Using fallback template`. **Causa**: El SDK no pudo parsear tu prop `template` local. Intenta tres estrategias de parsing (JSON.parse, eliminación de prefijo, eval con Function) — si todas fallan, usa como respaldo el template configurado en el servidor para tu `templateid`. **Solución**: 1. Validar tu JSON del template en [jsonlint.com](https://jsonlint.com) 2. Asegurar que el template se pasa como un string JSON válido, no como un objeto JavaScript 3. Verificar caracteres especiales o problemas de encoding en el string del template 4. En modo debug, buscar `Template validation failed` para detalles específicos del error ## Verificar la salida de handleReport Usa el siguiente patrón para inspeccionar los datos del reporte en la consola de tu navegador: ```javascript theme={null} function handleReport(report) { // Loguear el reporte completo para depuración console.log('[Mi App] Reporte recibido:', JSON.stringify(report, null, 2)); // Comparar las keys del reporte con los campos esperados del template const camposEsperados = ['diagnostico_principal', 'sintomas', 'exploracion_fisica']; const camposRecibidos = Object.keys(report); const camposFaltantes = camposEsperados.filter(f => !camposRecibidos.includes(f)); if (camposFaltantes.length > 0) { console.warn('[Mi App] Campos faltantes:', camposFaltantes); } // Procesar el reporte en tu aplicación // ... } ``` Usa `JSON.stringify(report, null, 2)` para una vista formateada del objeto del reporte. Esto facilita detectar valores faltantes o inesperados en comparación con la salida por defecto de `console.log`. Para más herramientas de depuración y cómo leer los logs del SDK, consulta [Solución de Problemas — Depuración y Logging](/sofia/es/sdk/troubleshooting#depuracion-y-logging).