Esquemas de datos clínicos

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.

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.

{
  "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

Entrada

La plantilla JSON Schema y el contexto de conversación se proporcionan al SofIA SDK.

Procesamiento IA

El SDK envía los datos mediante LangGraph Streaming para el procesamiento de IA.

Salida estructurada

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

{
  "$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:

<sofia-sdk
  template='{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"diagnosis":{"type":"string"}}}'
></sofia-sdk>

Programáticamente (recomendado para esquemas complejos) — configura vía JavaScript:

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:

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: 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.
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). 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:

{
  "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

{
  "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

{
  "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:

{
  "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:

{
  "peso": {
    "type": "number",
    "minimum": 0.5,
    "maximum": 500,
    "description": "Peso del paciente en kilogramos"
  }
}

Estructuras flexibles

Diseñe esquemas que permitan variabilidad clínica:

{
  "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):

{
  "treatment_plan": {
    "isConfigurable": true,
    "type": "string",
    "description": "Plan de tratamiento recomendado"
  }
}

Campo no configurable:

{
  "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.

<sofia-sdk
  debug="true"
  apikey="your-api-key"
  userid="user_12345"
  patientid="patient_67890"
  templateid="your-template-id"
  template='{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Clinical Notes",
    "type": "object",
    "properties": {
      "diagnosis": {"type": "string", "description": "Primary diagnosis"}
    },
    "required": ["diagnosis"]
  }'
></sofia-sdk>

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:

JSON Schema válido — incluye el header "$schema": "http://json-schema.org/draft-07/schema#"
Tanto template como templateid están presentes — el botón generar solo aparece cuando ambos están configurados
properties definidas con al menos 1 campo — un objeto properties vacío resulta en modo solo-chat
Tamaño del esquema menor a 100KB — esquemas más grandes son rechazados
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

El botón Generar no aparece

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:

Verificar que ambos atributos template y templateid estén configurados en el componente
Habilitar debug="true" y buscar Template loaded: {n} fields — si n es 0 o el mensaje no aparece, el template es inválido
Validar que template contenga al menos una propiedad dentro de properties

handleReport retorna un objeto vacío

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:

Asegurar que la conversación cubra temas relacionados con los campos de tu template antes de hacer clic en Generar
Verificar que los valores de description de los campos sean claros y específicos — descripciones vagas llevan a una extracción deficiente
Habilitar debug="true" y verificar que aparezca Report generation completed (no failed)

handleReport retorna datos parciales

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:

Revisar qué campos faltan — ¿corresponden a temas discutidos en la conversación?
Añadir valores de description más específicos para ayudar a la IA a identificar información relevante
Considerar marcar los campos críticos como required en tu esquema

El template usa los valores por defecto del servidor

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:

Validar tu JSON del template en jsonlint.com
Asegurar que el template se pasa como un string JSON válido, no como un objeto JavaScript
Verificar caracteres especiales o problemas de encoding en el string del template
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:

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.

Instalación y Configuración

Integración por Framework

Funcionalidades

Soporte

Cómo Funcionan las Plantillas

Estructura requerida

Ejemplo básico

Pasar templates al componente

Fuentes de codificación clínica

Campos especializados

Fuente a terminologías médicas

Constantes vitales estructuradas

Tipos de datos soportados

Tipos básicos

Validaciones avanzadas

Limitaciones técnicas

Mejores prácticas

Descripciones detalladas

Validaciones apropiadas

Estructuras flexibles

Personalización de propiedades

La propiedad `isConfigurable`

Depuración de tu template

Habilitar modo debug

Checklist de validación del template

Referencia de logs de consola

Problemas comunes

Verificar la salida de handleReport

​Accesibilidad (a11y)

​Cómo Funcionan las Plantillas

​Estructura requerida

​Ejemplo básico

​Pasar templates al componente

​Fuentes de codificación clínica

​Campos especializados

​Fuente a terminologías médicas

​Constantes vitales estructuradas

​Tipos de datos soportados

​Tipos básicos

​Validaciones avanzadas

​Limitaciones técnicas

​Mejores prácticas

​Descripciones detalladas

​Validaciones apropiadas

​Estructuras flexibles

​Personalización de propiedades

​La propiedad isConfigurable

​Depuración de tu template

​Habilitar modo debug

​Checklist de validación del template

​Referencia de logs de consola

​Problemas comunes

​Verificar la salida de handleReport

Accesibilidad (a11y)

Cómo Funcionan las Plantillas

Estructura requerida

Ejemplo básico

Pasar templates al componente

Fuentes de codificación clínica

Campos especializados

Fuente a terminologías médicas

Constantes vitales estructuradas

Tipos de datos soportados

Tipos básicos

Validaciones avanzadas

Limitaciones técnicas

Mejores prácticas

Descripciones detalladas

Validaciones apropiadas

Estructuras flexibles

Personalización de propiedades

La propiedad `isConfigurable`

Depuración de tu template

Habilitar modo debug

Checklist de validación del template

Referencia de logs de consola

Problemas comunes

Verificar la salida de handleReport