USER_GUIDE.md

soap-schema-python — User Guide

soap-schema-python provides three layers: portable Draft 2020-12 JSON Schema files, Python TypedDict definitions, and validation/rendering helpers. The schema is canonical; types and helpers are conveniences.

Validation

Use validate() for explicit control flow. It always returns every detected schema failure and never raises:

from soap_schema import validate

result = validate(candidate)
for error in result.errors:
    print(error.path, error.keyword, error.message)

Use assert_valid() when an invalid note should stop the current workflow:

from soap_schema import SoapNoteValidationError, assert_valid

try:
    assert_valid(candidate)
except SoapNoteValidationError as exc:
    print(exc.errors)

The JSON keys intentionally retain their cross-language camelCase names: chiefComplaint, historyOfPresentIllness, patientRef, and so on.

Rendering

render_note() does not validate its input. Validate external data first, then pass the valid dictionary to it. The result is deterministic Markdown with Subjective, Objective, Assessment, and Plan section headings.

Security and PHI

Fixtures are synthetic. Do not place real patient data in fixtures, logs, exception telemetry, public issues, or example documentation. patientRef is an opaque caller-owned reference, not a patient name, DOB, or MRN.

Raw schema use

Consumers that need another validator can read schema/soap-note.schema.json and its schema/definitions/ dependencies directly. They must use a JSON Schema Draft 2020-12 validator with format checking enabled to apply the timestamp and URI format constraints.