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

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

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

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

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

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

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

2. Use required for mandatory fields

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

3. Add examples to guide the model

{
  "temperature": {
    "type": "number",
    "description": "Body temperature in degrees Celsius",
    "examples": [36.5, 37.2, 38.9]
  }
}

4. Use enum for predefined values

{
  "priority": {
    "type": "string",
    "enum": ["low", "medium", "high", "urgent"]
  }
}

5. Validate formats when possible

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

Common errors

1. Vague schemas

// Bad
{
  "data": {
    "type": "object"
  }
}

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

2. Omitting descriptions

// Bad
{
  "field1": {"type": "string"}
}

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

3. Not using source for codes

// 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)

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

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

{
  "$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
• json-schema.org/implementations

Code validation

Python:

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:

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

View practical examples

Complete schemas with requests and responses

Request structure

How to send the schema

Error handling

422 errors for invalid schemas