# OpenScar Minimum Data Schema

This schema is the stable interface for the first OpenScar data asset. It is intentionally small: the goal is to capture enough structure for longitudinal scar research without pretending that every clinic will have the same instruments, scales, or follow-up schedule.

All field names use `snake_case`. Values should be de-identified before research export.

## 1. patient

One row per patient.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| patient_id | string | yes | De-identified stable ID. |
| sex_at_birth | enum | no | `female`, `male`, `intersex`, `unknown`, `not_recorded`. |
| age_at_first_visit | integer | no | Years; avoid full birth date in research export. |
| fitzpatrick_skin_type | enum | no | `i`, `ii`, `iii`, `iv`, `v`, `vi`, `unknown`. |
| relevant_history | text | no | Prior keloids, hypertrophic scars, acne, surgery, trauma, burns, pregnancy, family history. |
| comorbidities | text | no | Diabetes, immune disease, infection risk, wound-healing risk factors. |
| consent_status | enum | yes | `clinical_only`, `research_deidentified`, `teaching`, `public_media`, `not_recorded`. |

## 2. lesion

One row per scar or keloid lesion. A patient can have multiple lesions.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| lesion_id | string | yes | Stable lesion ID. |
| patient_id | string | yes | Links to `patient.patient_id`. |
| scar_category | enum | yes | `keloid`, `hypertrophic_scar`, `atrophic_scar`, `contracture`, `postoperative_scar`, `burn_scar`, `other`, `uncertain`. |
| anatomic_site | string | yes | Use controlled terms when possible. |
| laterality | enum | no | `left`, `right`, `midline`, `bilateral`, `not_applicable`, `unknown`. |
| presumed_trigger | enum | no | `surgery`, `trauma`, `acne`, `piercing`, `burn`, `injection`, `spontaneous`, `unknown`, `other`. |
| onset_date_precision | enum | no | `exact_date`, `month`, `year`, `estimated`, `unknown`. |
| duration_months_at_baseline | number | no | Approximate duration at first documented visit. |
| baseline_symptoms | text | no | Pain, itch, tenderness, tightness, ulceration, functional limitation. |

## 3. visit

One row per clinical encounter or follow-up timepoint.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| visit_id | string | yes | Stable visit ID. |
| patient_id | string | yes | Links to `patient.patient_id`. |
| lesion_id | string | yes | Links to `lesion.lesion_id`. |
| visit_date_offset_days | integer | yes | Days from baseline visit, not calendar date. |
| visit_type | enum | yes | `baseline`, `treatment`, `follow_up`, `complication`, `recurrence_check`, `other`. |
| clinician_assessment | text | no | Structured or free-text clinician observation. |
| patient_reported_pain | integer | no | 0-10 scale if available. |
| patient_reported_itch | integer | no | 0-10 scale if available. |
| patient_satisfaction | integer | no | 0-10 scale if collected. |
| validated_scale_name | string | no | Example: POSAS, VSS, or local scale. |
| validated_scale_score | number | no | Store raw score and define scale externally. |

## 4. image

One row per image. A visit may include multiple views.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| image_id | string | yes | Stable image ID. |
| visit_id | string | yes | Links to `visit.visit_id`. |
| lesion_id | string | yes | Links to `lesion.lesion_id`. |
| image_uri | string | yes | Local path, archive ID, or secure storage pointer. |
| view_label | enum | yes | `overview`, `close_up`, `oblique`, `profile`, `with_scale`, `other`. |
| capture_device | string | no | Camera or phone model if available. |
| distance_cm | number | no | Estimated or measured distance. |
| scale_marker_present | boolean | yes | Whether ruler or scale marker is visible. |
| color_reference_present | boolean | yes | Whether color card or reference is visible. |
| lighting_quality | enum | yes | `good`, `acceptable`, `poor`, `unknown`. |
| angle_quality | enum | yes | `standardized`, `acceptable`, `nonstandard`, `unknown`. |
| focus_quality | enum | yes | `good`, `acceptable`, `poor`, `unknown`. |
| privacy_redaction_status | enum | yes | `not_needed`, `redacted`, `needs_review`. |

## 5. treatment

One row per intervention exposure.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| treatment_id | string | yes | Stable treatment ID. |
| visit_id | string | yes | Links to treatment visit. |
| lesion_id | string | yes | Links to `lesion.lesion_id`. |
| treatment_modality | enum | yes | `steroid_injection`, `5fu_injection`, `botulinum_toxin`, `laser`, `rf_microneedling`, `surgery`, `radiotherapy`, `silicone`, `pressure`, `cryotherapy`, `other`. |
| treatment_detail | text | no | Drug, dose, device, wavelength, passes, surgical technique, or other protocol notes. |
| combination_flag | boolean | yes | Whether treatment was part of a combination session. |
| adverse_event_reported | boolean | yes | Any reported adverse event after treatment. |
| adverse_event_detail | text | no | Conservative description, if present. |

## 6. outcome

One row per outcome assessment window.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| outcome_id | string | yes | Stable outcome ID. |
| lesion_id | string | yes | Links to `lesion.lesion_id`. |
| assessment_visit_id | string | yes | Visit where outcome was assessed. |
| follow_up_days_from_baseline | integer | yes | Days from baseline. |
| response_category | enum | yes | `improved`, `stable`, `worse`, `recurrence`, `partial_recurrence`, `uncertain`, `not_assessable`. |
| recurrence_status | enum | yes | `yes`, `no`, `suspected`, `not_assessed`. |
| recurrence_definition | text | no | Local operational definition used. |
| functional_impact | text | no | Range of motion, contracture, pain, work, clothing, or other impact. |
| cosmetic_impact | text | no | Patient or clinician cosmetic concern. |
| outcome_confidence | enum | yes | `high`, `moderate`, `low`. |

## Export Rules

- Do not export names, phone numbers, full dates, full-face identifiable images, or direct identifiers unless the use case has explicit consent and governance approval.
- Use date offsets rather than calendar dates for research tables.
- Keep image files in controlled storage; the schema should reference images rather than embed them.
- Record missing values explicitly as `unknown`, `not_recorded`, or `not_assessable` when possible.