Guía de JSON Schema

¿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?

Comparta su catálogo/nomenclatura:
- Archivo Excel, CSV, o volcado de base de datos
- Incluye: código, descripción, sinónimos si aplica
Nuestro equipo entrena el modelo:
- Tiempo estimado: 2-4 semanas
- Validación con casos de prueba de tu centro
Especifice su source custom:
- Use el identificador que le proporcionemos
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:

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

Visión General

Configuración

Uso y Ejemplos

Referencia de API

¿Qué es JSON Schema?

Requisitos

Esquema básico

Anotación especial: `source`

Nomenclaturas estándar y custom

Fuentes estándar soportadas

Fuentes custom por centro hospitalario

¿Su HIS/EHR usa códigos propios?

Casos de uso reales

1. Códigos de medicamentos

2. Códigos de pruebas diagnósticas

3. Plantillas custom del centro

¿Cómo activar fuentes custom?

Consejos para esquemas efectivos

Mejores prácticas

Errores comunes

Ejemplos completos

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

Ejemplo 2: Nota de consulta estructurada

Ejemplo 3: Registro de UCI

Validación de esquemas

Herramientas online

Validación en código

Próximos pasos

Ver ejemplos prácticos

Estructura de petición

Manejo de errores

Visión General

Configuración

Uso y Ejemplos

Referencia de API

​¿Qué es JSON Schema?

​Requisitos

​Esquema básico

​Anotación especial: source

​Nomenclaturas estándar y custom

​Fuentes estándar soportadas

​Fuentes custom por centro hospitalario

​¿Su HIS/EHR usa códigos propios?

​Casos de uso reales

​1. Códigos de medicamentos

​2. Códigos de pruebas diagnósticas

​3. Plantillas custom del centro

​¿Cómo activar fuentes custom?

​Consejos para esquemas efectivos

​Mejores prácticas

​Errores comunes

​Ejemplos completos

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

​Ejemplo 2: Nota de consulta estructurada

​Ejemplo 3: Registro de UCI

​Validación de esquemas

​Herramientas online

​Validación en código

​Próximos pasos

Ver ejemplos prácticos

Estructura de petición

Manejo de errores

¿Qué es JSON Schema?

Requisitos

Esquema básico

Anotación especial: `source`

Nomenclaturas estándar y custom

Fuentes estándar soportadas

Fuentes custom por centro hospitalario

¿Su HIS/EHR usa códigos propios?

Casos de uso reales

1. Códigos de medicamentos

2. Códigos de pruebas diagnósticas

3. Plantillas custom del centro

¿Cómo activar fuentes custom?

Consejos para esquemas efectivos

Mejores prácticas

Errores comunes

Ejemplos completos

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

Ejemplo 2: Nota de consulta estructurada

Ejemplo 3: Registro de UCI

Validación de esquemas

Herramientas online

Validación en código

Próximos pasos