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

# JSON Schema Guide

> How to define clinical data structures using JSON Schema Draft-07 for the SofIA Codify API

## What is JSON Schema?

JSON Schema is a standard for defining the structure of JSON data. Think of it as a **"mold"** or **"template"** that you tell the API to fill with data extracted from clinical text.

**Analogy:** If clinical text is shapeless clay, JSON Schema is the mold you define for the API to give it the exact shape you need.

***

## Requirements

* **Version:** Must use JSON Schema **Draft-07**
* **Mandatory indicator:** Include `"$schema": "http://json-schema.org/draft-07/schema#"`
* **Supported types:** `object`, `array`, `string`, `number`, `boolean`, `null`

***

## Basic schema

```json theme={null}
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["mandatory_field"],
  "properties": {
    "mandatory_field": {
      "type": "string",
      "description": "Clear description of what this field should contain"
    },
    "optional_field": {
      "type": "string"
    }
  }
}
```

***

## Special annotation: `source`

### Standard and custom nomenclatures

You can annotate fields with `"source"` to indicate the specific dataset or version you want to use:

```json theme={null}
{
  "items": {
    "type": "string",
    "source": "ICD-10-CM-US-2026"
  }
}
```

### Supported standard sources

| Source               | Description                          | Typical usage                      |
| -------------------- | ------------------------------------ | ---------------------------------- |
| `ICD-10-CM-US-2026`  | ICD-10 Clinical Modification US 2026 | Diagnoses (billing, reporting)     |
| `ICD-10-PCS-US-2026` | ICD-10 Procedures US 2026            | Surgical and diagnostic procedures |
| `ICD-9-CM-US`        | ICD-9 Clinical Modification US       | Legacy systems, transition         |
| `SNOMED-CT-US`       | SNOMED Clinical Terms US             | Interoperability, clinical records |
| `LOINC`              | Logical Observation Identifiers      | Laboratory tests                   |

***

## Custom sources by hospital center

### Does your HIS/EHR use proprietary codes?

We can train specialized models with your internal nomenclatures.

### Real use cases

#### 1. Medication codes

Pharmacy system with NDC codes, RxNorm, or internal nomenclature:

```json theme={null}
{
  "medications": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "pharmacy_code": {
          "type": "string",
          "source": "RXNORM-2024",
          "description": "Medication code in RxNorm"
        },
        "name": {
          "type": "string",
          "description": "Medication name"
        },
        "dose": {
          "type": "string",
          "description": "Prescribed dose"
        },
        "route": {
          "type": "string",
          "description": "Administration route"
        }
      }
    }
  }
}
```

#### 2. Diagnostic test codes

Codes from your radiology system (RIS) or internal laboratory:

```json theme={null}
{
  "requested_tests": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "test_code": {
          "type": "string",
          "source": "RIS-HOSPITAL-XYZ",
          "description": "Internal test code"
        },
        "description": {
          "type": "string"
        },
        "priority": {
          "type": "string",
          "enum": ["urgent", "normal", "scheduled"]
        }
      }
    }
  }
}
```

#### 3. Custom center templates

Specific fields from your medical record or internal registries:

```json theme={null}
{
  "oncology_record": {
    "type": "object",
    "properties": {
      "tumor_type": {
        "type": "string",
        "source": "ONCOLOGY-CLASSIFICATION-CENTER"
      },
      "tnm_stage": {
        "type": "string"
      },
      "treatment_protocol": {
        "type": "string",
        "source": "ONCOLOGY-PROTOCOLS-CENTER"
      }
    }
  }
}
```

### How to activate custom sources?

1. **Share your catalog/nomenclature:**
   * Excel file, CSV, or database dump
   * Include: code, description, synonyms if applicable

2. **Our team trains the model:**
   * Estimated time: 2-4 weeks
   * Validation with test cases from your center

3. **Specify your custom `source`:**
   * Use the identifier we provide

4. **The API returns codes in your nomenclature:**
   * No post-processing
   * Ready for your system

**Benefit:** Zero friction. Data comes out in the exact format your HIS/EHR expects.

***

## Tips for effective schemas

### Best practices

**1. Be specific in descriptions**

```json theme={null}
{
  "chief_complaint": {
    "type": "string",
    "description": "Main reason why the patient comes to consultation, in their own words"
  }
}
```

**2. Use `required` for mandatory fields**

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

**3. Add examples to guide the model**

```json theme={null}
{
  "temperature": {
    "type": "number",
    "description": "Body temperature in degrees Celsius",
    "examples": [36.5, 37.2, 38.9]
  }
}
```

**4. Use `enum` for predefined values**

```json theme={null}
{
  "priority": {
    "type": "string",
    "enum": ["low", "medium", "high", "urgent"]
  }
}
```

**5. Validate formats when possible**

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

### Common errors

**1. Vague schemas**

```json theme={null}
// Bad
{
  "data": {
    "type": "object"
  }
}

// Good
{
  "clinical_data": {
    "type": "object",
    "properties": {
      "blood_pressure": {"type": "string"},
      "heart_rate": {"type": "number"},
      "temperature": {"type": "number"}
    }
  }
}
```

**2. Omitting descriptions**

```json theme={null}
// Bad
{
  "field1": {"type": "string"}
}

// Good
{
  "primary_diagnosis": {
    "type": "string",
    "description": "Primary diagnosis of the consultation"
  }
}
```

**3. Not using `source` for codes**

```json theme={null}
// Bad (model can use any source)
{
  "diagnosis_code": {"type": "string"}
}

// Good
{
  "diagnosis_code": {
    "type": "string",
    "source": "ICD-10-CM-US-2026"
  }
}
```

***

## Complete examples

### Example 1: Minimum Basic Dataset (MDS)

```json theme={null}
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Hospitalization MDS",
  "type": "object",
  "required": ["primary_diagnosis", "secondary_diagnoses", "procedures"],
  "properties": {
    "primary_diagnosis": {
      "type": "string",
      "source": "ICD-10-CM-US-2026",
      "description": "Primary diagnosis that motivated admission"
    },
    "secondary_diagnoses": {
      "type": "array",
      "description": "Secondary diagnoses present during stay",
      "items": {
        "type": "string",
        "source": "ICD-10-CM-US-2026"
      }
    },
    "procedures": {
      "type": "array",
      "description": "Procedures performed during stay",
      "items": {
        "type": "string",
        "source": "ICD-10-PCS-US-2026"
      }
    },
    "admission_circumstance": {
      "type": "string",
      "enum": ["urgent", "scheduled"],
      "description": "Type of admission"
    },
    "discharge_circumstance": {
      "type": "string",
      "enum": ["home", "transfer", "death", "voluntary_discharge"],
      "description": "Circumstance at discharge"
    }
  }
}
```

### Example 2: Structured consultation note

```json theme={null}
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Consultation Note",
  "type": "object",
  "required": ["chief_complaint", "present_illness", "plan"],
  "properties": {
    "consultation_date": {
      "type": "string",
      "format": "date-time"
    },
    "chief_complaint": {
      "type": "string",
      "description": "Reason why the patient comes"
    },
    "present_illness": {
      "type": "string",
      "description": "Detailed description of current illness"
    },
    "past_history": {
      "type": "string",
      "description": "Relevant medical history"
    },
    "physical_examination": {
      "type": "string",
      "description": "Physical examination findings"
    },
    "vital_signs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "value": {"type": "string"},
          "unit": {"type": "string"}
        }
      }
    },
    "diagnoses": {
      "type": "array",
      "items": {
        "type": "string",
        "source": "ICD-10-CM-US-2026"
      }
    },
    "plan": {
      "type": "string",
      "description": "Treatment and follow-up plan"
    },
    "prescribed_medication": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "medication": {"type": "string"},
          "dose": {"type": "string"},
          "frequency": {"type": "string"},
          "duration": {"type": "string"}
        }
      }
    },
    "requested_tests": {
      "type": "array",
      "items": {"type": "string"}
    },
    "next_appointment": {
      "type": "string"
    }
  }
}
```

### Example 3: ICU record

```json theme={null}
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "ICU Record",
  "type": "object",
  "required": ["admission_diagnosis", "apache_ii"],
  "properties": {
    "admission_diagnosis": {
      "type": "string",
      "source": "ICD-10-CM-US-2026"
    },
    "apache_ii": {
      "type": "number",
      "description": "APACHE II score"
    },
    "sofa": {
      "type": "number",
      "description": "SOFA score"
    },
    "ventilatory_support": {
      "type": "string",
      "enum": ["none", "niv", "invasive", "tracheostomy"]
    },
    "hemodynamic_support": {
      "type": "boolean",
      "description": "Requires vasopressors?"
    },
    "renal_replacement": {
      "type": "boolean",
      "description": "Renal replacement therapy?"
    },
    "complications": {
      "type": "array",
      "items": {
        "type": "string",
        "source": "ICD-10-CM-US-2026"
      }
    }
  }
}
```

***

## Schema validation

### Online tools

Validate your schema before using it:

* [jsonschemavalidator.net](https://www.jsonschemavalidator.net/)
* [json-schema.org/implementations](https://json-schema.org/implementations.html)

### Code validation

**Python:**

```python theme={null}
import jsonschema

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

# Validate
try:
    jsonschema.Draft7Validator.check_schema(schema)
    print("✅ Valid schema")
except jsonschema.SchemaError as e:
    print(f"❌ Invalid schema: {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('✅ Valid schema');
} catch (e) {
  console.log('❌ Invalid schema:', e.message);
}
```

***

## Next steps

<Columns cols={3}>
  <Card title="View practical examples" href="/sofia/en/api/examples" icon="lightbulb">
    Complete schemas with requests and responses
  </Card>

  <Card title="Request structure" href="/sofia/en/api/request-response" icon="clipboard">
    How to send the schema
  </Card>

  <Card title="Error handling" href="/sofia/en/api/operations" icon="gear">
    422 errors for invalid schemas
  </Card>
</Columns>