Guía de JSON Schema

Cómo definir estructuras de datos clínicos usando JSON Schema Draft-07 para la API Codify de SofIA

​

¿Qué es JSON Schema?

JSON Schema es un estándar para definir la estructura de datos JSON. Piénsalo como un “molde” o “plantilla” que le dices a la API que quieres que rellene con los datos extraídos del texto clínico.

Analogía: Si el texto clínico es arcilla sin forma, el JSON Schema es el molde que defines para que la API le dé la forma exacta que necesitas.

---

​

Requisitos

• Versión: Debe usar JSON Schema Draft-07
• Indicador obligatorio: Incluye "$schema": "http://json-schema.org/draft-07/schema#"
• Tipos soportados: object, array, string, number, boolean, null

---

​

Esquema básico

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["campo_obligatorio"],
  "properties": {
    "campo_obligatorio": {
      "type": "string",
      "description": "Descripción clara de qué debe contener este campo"
    },
    "campo_opcional": {
      "type": "string"
    }
  }
}

---

​

Anotación especial: source

​

Nomenclaturas estándar y custom

Puede anotar los campos con "source" para indicar el conjunto de datos o versión específica que quiere usar:

{
  "items": {
    "type": "string",
    "source": "CIE-10-MC-ES-2026"
  }
}

​

Fuentes estándar soportadas

Source	Descripción	Uso típico
CIE-10-MC-ES-2026	CIE-10 Modificación Clínica España 2026	Diagnósticos (CMBD, facturación)
CIE-10-PCS-ES-2026	CIE-10 Procedimientos España 2026	Procedimientos quirúrgicos y diagnósticos
CIE-9-MC-ES	CIE-9 Modificación Clínica España	Sistemas legacy, transición
SNOMED-CT-ES	SNOMED Clinical Terms España	Interoperabilidad, registros clínicos
LOINC	Logical Observation Identifiers	Pruebas de laboratorio

---

​

Fuentes custom por centro hospitalario

​

¿Su HIS/EHR usa códigos propios?

Podemos entrenar modelos especializados con sus nomenclaturas internas.

​

Casos de uso reales

​

1. Códigos de medicamentos

Sistema de farmacia con códigos Botplus, catálogo CIMA, o nomenclatura interna:

{
  "medicamentos": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "codigo_farmacia": {
          "type": "string",
          "source": "BOTPLUS-2024",
          "description": "Código del medicamento en Botplus"
        },
        "nombre": {
          "type": "string",
          "description": "Nombre del medicamento"
        },
        "dosis": {
          "type": "string",
          "description": "Dosis prescrita"
        },
        "via": {
          "type": "string",
          "description": "Vía de administración"
        }
      }
    }
  }
}

​

2. Códigos de pruebas diagnósticas

Códigos de tu sistema de radiología (RIS) o laboratorio interno:

{
  "pruebas_solicitadas": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "codigo_prueba": {
          "type": "string",
          "source": "RIS-HOSPITAL-XYZ",
          "description": "Código interno de la prueba"
        },
        "descripcion": {
          "type": "string"
        },
        "prioridad": {
          "type": "string",
          "enum": ["urgente", "normal", "programada"]
        }
      }
    }
  }
}

​

3. Plantillas custom del centro

Campos específicos de tu historia clínica o registros internos:

{
  "registro_oncologia": {
    "type": "object",
    "properties": {
      "tipo_tumor": {
        "type": "string",
        "source": "CLASIFICACION-ONCOLOGIA-CENTRO"
      },
      "estadio_tnm": {
        "type": "string"
      },
      "protocolo_tratamiento": {
        "type": "string",
        "source": "PROTOCOLOS-ONCOLOGIA-CENTRO"
      }
    }
  }
}

​

¿Cómo activar fuentes custom?

1. Comparta su catálogo/nomenclatura:

   • Archivo Excel, CSV, o volcado de base de datos
   • Incluye: código, descripción, sinónimos si aplica

2. Nuestro equipo entrena el modelo:

   • Tiempo estimado: 2-4 semanas
   • Validación con casos de prueba de tu centro

3. Especifice su source custom:

   • Use el identificador que le proporcionemos

4. La API devuelve códigos en su nomenclatura:

   • Sin post-procesamiento
   • Listos para su sistema

Beneficio: Cero fricción. Los datos salen en el formato exacto que su HIS/EHR espera.

---

​

Consejos para esquemas efectivos

​

Mejores prácticas

1. Sea específico en las descripciones

{
  "motivo_consulta": {
    "type": "string",
    "description": "Razón principal por la que el paciente acude a consulta, en sus propias palabras"
  }
}

2. Use required para campos obligatorios

{
  "type": "object",
  "required": ["diags", "plan_tratamiento"],
  "properties": {
    "diags": {...},
    "plan_tratamiento": {...}
  }
}

3. Añada ejemplos para guiar el modelo

{
  "temperatura": {
    "type": "number",
    "description": "Temperatura corporal en grados Celsius",
    "examples": [36.5, 37.2, 38.9]
  }
}

4. Use enum para valores predefinidos

{
  "prioridad": {
    "type": "string",
    "enum": ["baja", "media", "alta", "urgente"]
  }
}

5. Valide formatos cuando sea posible

{
  "fecha_consulta": {
    "type": "string",
    "format": "date-time"
  },
  "email": {
    "type": "string",
    "format": "email"
  }
}

​

Errores comunes

1. Esquemas vagos

// Malo
{
  "datos": {
    "type": "object"
  }
}

// Bueno
{
  "datos_clinicos": {
    "type": "object",
    "properties": {
      "tension_arterial": {"type": "string"},
      "frecuencia_cardiaca": {"type": "number"},
      "temperatura": {"type": "number"}
    }
  }
}

2. Omitir descripciones

// Malo
{
  "campo1": {"type": "string"}
}

// Bueno
{
  "diagnostico_principal": {
    "type": "string",
    "description": "Diagnóstico principal de la consulta"
  }
}

3. No usar source para códigos

// Malo (el modelo puede usar cualquier fuente)
{
  "codigo_diagnostico": {"type": "string"}
}

// Bueno
{
  "codigo_diagnostico": {
    "type": "string",
    "source": "CIE-10-MC-ES-2026"
  }
}

---

​

Ejemplos completos

​

Ejemplo 1: CMBD (Conjunto Mínimo Básico de Datos)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "CMBD Hospitalización",
  "type": "object",
  "required": ["diagnostico_principal", "diagnosticos_secundarios", "procedimientos"],
  "properties": {
    "diagnostico_principal": {
      "type": "string",
      "source": "CIE-10-MC-ES-2026",
      "description": "Diagnóstico principal que motivó el ingreso"
    },
    "diagnosticos_secundarios": {
      "type": "array",
      "description": "Diagnósticos secundarios presentes durante la estancia",
      "items": {
        "type": "string",
        "source": "CIE-10-MC-ES-2026"
      }
    },
    "procedimientos": {
      "type": "array",
      "description": "Procedimientos realizados durante la estancia",
      "items": {
        "type": "string",
        "source": "CIE-10-PCS-ES-2026"
      }
    },
    "circunstancia_ingreso": {
      "type": "string",
      "enum": ["urgente", "programado"],
      "description": "Tipo de ingreso"
    },
    "circunstancia_alta": {
      "type": "string",
      "enum": ["domicilio", "traslado", "exitus", "alta_voluntaria"],
      "description": "Circunstancia al alta"
    }
  }
}

​

Ejemplo 2: Nota de consulta estructurada

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Nota de Consulta",
  "type": "object",
  "required": ["motivo_consulta", "enfermedad_actual", "plan"],
  "properties": {
    "fecha_consulta": {
      "type": "string",
      "format": "date-time"
    },
    "motivo_consulta": {
      "type": "string",
      "description": "Motivo por el que acude el paciente"
    },
    "enfermedad_actual": {
      "type": "string",
      "description": "Descripción detallada de la enfermedad actual"
    },
    "antecedentes": {
      "type": "string",
      "description": "Antecedentes médicos relevantes"
    },
    "exploracion_fisica": {
      "type": "string",
      "description": "Hallazgos de la exploración"
    },
    "constantes_vitales": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "nombre": {"type": "string"},
          "valor": {"type": "string"},
          "unidad": {"type": "string"}
        }
      }
    },
    "diagnosticos": {
      "type": "array",
      "items": {
        "type": "string",
        "source": "CIE-10-MC-ES-2026"
      }
    },
    "plan": {
      "type": "string",
      "description": "Plan de tratamiento y seguimiento"
    },
    "medicacion_prescrita": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "medicamento": {"type": "string"},
          "dosis": {"type": "string"},
          "frecuencia": {"type": "string"},
          "duracion": {"type": "string"}
        }
      }
    },
    "pruebas_solicitadas": {
      "type": "array",
      "items": {"type": "string"}
    },
    "proxima_cita": {
      "type": "string"
    }
  }
}

​

Ejemplo 3: Registro de UCI

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Registro UCI",
  "type": "object",
  "required": ["diagnostico_ingreso", "apache_ii"],
  "properties": {
    "diagnostico_ingreso": {
      "type": "string",
      "source": "CIE-10-MC-ES-2026"
    },
    "apache_ii": {
      "type": "number",
      "description": "Puntuación APACHE II"
    },
    "sofa": {
      "type": "number",
      "description": "Puntuación SOFA"
    },
    "soporte_ventilatorio": {
      "type": "string",
      "enum": ["ninguno", "vmni", "vmi", "traqueostomia"]
    },
    "soporte_hemodinamico": {
      "type": "boolean",
      "description": "¿Requiere vasopresores?"
    },
    "tecnicas_depuracion": {
      "type": "boolean",
      "description": "¿Técnicas de depuración renal?"
    },
    "complicaciones": {
      "type": "array",
      "items": {
        "type": "string",
        "source": "CIE-10-MC-ES-2026"
      }
    }
  }
}

---

​

Validación de esquemas

​

Herramientas online

Valide su esquema antes de usarlo:

• jsonschemavalidator.net
• json-schema.org/implementations

​

Validación en código

Python:

import jsonschema

schema = {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "diags": {"type": "array"}
    }
}

# Validar
try:
    jsonschema.Draft7Validator.check_schema(schema)
    print("✅ Esquema válido")
except jsonschema.SchemaError as e:
    print(f"❌ Esquema inválido: {e}")

JavaScript:

const Ajv = require('ajv');
const ajv = new Ajv({schemaId: 'auto'});

const schema = {
  $schema: 'http://json-schema.org/draft-07/schema#',
  type: 'object',
  properties: {
    diags: {type: 'array'}
  }
};

try {
  ajv.compile(schema);
  console.log('✅ Esquema válido');
} catch (e) {
  console.log('❌ Esquema inválido:', e.message);
}

---

​

Próximos pasos

Ver ejemplos prácticos

Esquemas completos con peticiones y respuestas

Estructura de petición

Cómo enviar el esquema

Manejo de errores

Errores 422 por esquemas inválidos