soap-schema-python

Canonical JSON Schema and Python validation library for structured SOAP (Subjective, Objective, Assessment, Plan) clinical notes.

The JSON Schema files in schema/ are the source of truth. This package validates candidate notes and renders already validated notes as Markdown; it does not generate clinical notes, resolve patient references, validate real medical codes, or generate FHIR resources.

Installation

Install the latest version directly from GitHub:

python -m pip install "git+https://github.com/PeerbitsSolution/soap-schema-python.git"

To install a particular branch, tag, or commit, append it after @:

python -m pip install "git+https://github.com/PeerbitsSolution/soap-schema-python.git@main"

For local development, clone the repository and install it in editable mode:

git clone https://github.com/PeerbitsSolution/soap-schema-python.git
cd soap-schema-python
python -m pip install -e .

The package requires Python 3.9+; required validation dependencies install automatically. A GitHub account is not required to install the public repository.

Demo and Quick start

Peerbits HealthTech - SOAP Schema Demo

This example is complete: copy it into example.py, then run python example.py.

from soap_schema import assert_valid, render_note, validate

note = {
    "metadata": {
        "encounterType": "primary-care-followup",
        "authorRole": "physician",
        "timestamp": "2026-02-10T14:30:00Z",
        "patientRef": "synthetic-patient-0001",
    },
    "subjective": {
        "chiefComplaint": "Follow-up for hypertension management",
        "historyOfPresentIllness": "Taking medication as prescribed; no chest pain or shortness of breath.",
    },
    "objective": {
        "vitals": {
            "bloodPressure": {
                "systolic": {"value": 130, "unit": "mmHg"},
                "diastolic": {"value": 82, "unit": "mmHg"},
            },
            "heartRate": {"value": 72, "unit": "bpm"},
        }
    },
    "assessment": [{"description": "Essential hypertension", "status": "chronic"}],
    "plan": [{"category": "followUp", "detail": "Return in three months."}],
}

# Use validate() for data from a form, file, API, or LLM. It never raises.
result = validate(note)
if not result.valid:
    for error in result.errors:
        print(f"{error.path}: {error.message} ({error.keyword})")
    raise SystemExit("SOAP note is invalid")

# Optional fail-fast form. It raises SoapNoteValidationError when invalid.
assert_valid(note)
print(render_note(note))

Rendered preview

The function returns Markdown. GitHub renders that output as follows:

SOAP Note

Encounter: primary-care-followup · Author: physician · 2026-02-10T14:30:00Z

Subjective

Chief Complaint: Follow-up for hypertension management

History of Present Illness: Taking medication as prescribed; no chest pain or shortness of breath.

Objective

Vitals:

• Blood Pressure: 130/82 mmHg
• Heart Rate: 72 bpm

Assessment

• Essential hypertension (chronic)

Plan

• Follow-up: Return in three months.

Handling invalid input

from soap_schema import validate

bad_note = {"metadata": {}, "subjective": {}, "objective": {}, "assessment": [], "plan": []}
for error in validate(bad_note).errors:
    print(error.path, error.keyword, error.message)

See runnable examples: validate_and_render.py and build_and_assert.py. The JSON field names intentionally retain their cross-language camelCase form, such as chiefComplaint, historyOfPresentIllness, and patientRef. The native Python API uses assert_valid() and render_note(); assertValid and renderNote aliases are exported for migration from the TypeScript package.

Development

python -m pip install -e .
PYTHONPATH=src python -m unittest discover -s tests -v
python -m build

All fixtures are synthetic. See docs/USER_GUIDE.md and docs/FHIR_MAPPING_GUIDE.md for integration and mapping guidance.

Contributing and security

Contributions are welcome. Please read CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md before opening an issue or pull request. Do not include protected health information in the repository, issues, pull requests, or logs.