JSON Schema Guide

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?

Share your catalog/nomenclature:
- Excel file, CSV, or database dump
- Include: code, description, synonyms if applicable
Our team trains the model:
- Estimated time: 2-4 weeks
- Validation with test cases from your center
Specify your custom source:
- Use the identifier we provide
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:

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

Overview

Configuration

Usage and Examples

API Reference

What is JSON Schema?

Requirements

Basic schema

Special annotation: `source`

Standard and custom nomenclatures

Supported standard sources

Custom sources by hospital center

Does your HIS/EHR use proprietary codes?

Real use cases

1. Medication codes

2. Diagnostic test codes

3. Custom center templates

How to activate custom sources?

Tips for effective schemas

Best practices

Common errors

Complete examples

Example 1: Minimum Basic Dataset (MDS)

Example 2: Structured consultation note

Example 3: ICU record

Schema validation

Online tools

Code validation

Next steps

View practical examples

Request structure

Error handling

Overview

Configuration

Usage and Examples

API Reference

​What is JSON Schema?

​Requirements

​Basic schema

​Special annotation: source

​Standard and custom nomenclatures

​Supported standard sources

​Custom sources by hospital center

​Does your HIS/EHR use proprietary codes?

​Real use cases

​1. Medication codes

​2. Diagnostic test codes

​3. Custom center templates

​How to activate custom sources?

​Tips for effective schemas

​Best practices

​Common errors

​Complete examples

​Example 1: Minimum Basic Dataset (MDS)

​Example 2: Structured consultation note

​Example 3: ICU record

​Schema validation

​Online tools

​Code validation

​Next steps

View practical examples

Request structure

Error handling

What is JSON Schema?

Requirements

Basic schema

Special annotation: `source`

Standard and custom nomenclatures

Supported standard sources

Custom sources by hospital center

Does your HIS/EHR use proprietary codes?

Real use cases

1. Medication codes

2. Diagnostic test codes

3. Custom center templates

How to activate custom sources?

Tips for effective schemas

Best practices

Common errors

Complete examples

Example 1: Minimum Basic Dataset (MDS)

Example 2: Structured consultation note

Example 3: ICU record

Schema validation

Online tools

Code validation

Next steps