> ## 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.

# 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

```json theme={null}
{
  "$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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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**

```json theme={null}
{
  "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**

```json theme={null}
{
  "type": "object",
  "required": ["diags", "plan_tratamiento"],
  "properties": {
    "diags": {...},
    "plan_tratamiento": {...}
  }
}
```

**3. Añada ejemplos para guiar el modelo**

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

**4. Use `enum` para valores predefinidos**

```json theme={null}
{
  "prioridad": {
    "type": "string",
    "enum": ["baja", "media", "alta", "urgente"]
  }
}
```

**5. Valide formatos cuando sea posible**

```json theme={null}
{
  "fecha_consulta": {
    "type": "string",
    "format": "date-time"
  },
  "email": {
    "type": "string",
    "format": "email"
  }
}
```

### Errores comunes

**1. Esquemas vagos**

```json theme={null}
// Malo
{
  "datos": {
    "type": "object"
  }
}

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

**2. Omitir descripciones**

```json theme={null}
// Malo
{
  "campo1": {"type": "string"}
}

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

**3. No usar `source` para códigos**

```json theme={null}
// 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)

```json theme={null}
{
  "$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

```json theme={null}
{
  "$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

```json theme={null}
{
  "$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](https://www.jsonschemavalidator.net/)
* [json-schema.org/implementations](https://json-schema.org/implementations.html)

### Validación en código

**Python:**

```python theme={null}
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:**

```javascript theme={null}
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

<Columns cols={3}>
  <Card title="Ver ejemplos prácticos" href="/sofia/es/api/examples" icon="lightbulb">
    Esquemas completos con peticiones y respuestas
  </Card>

  <Card title="Estructura de petición" href="/sofia/es/api/request-response" icon="clipboard">
    Cómo enviar el esquema
  </Card>

  <Card title="Manejo de errores" href="/sofia/es/api/operations" icon="gear">
    Errores 422 por esquemas inválidos
  </Card>
</Columns>