# Foot Passport Specification

**Version 1.0**

Status: Draft · Open specification · Free to implement

---

## 1. Purpose

The Foot Passport is a **portable, open format for longitudinal foot-health records**.

Like PDF or JPEG, it is a specification — not an application. Any software may read from
or write to a Foot Passport by following this document. The passport belongs to its
owner, not to any vendor. It is designed to be stored locally, backed up, copied, or
moved between devices without loss of meaning.

A Foot Passport is a **directory on a filesystem**. That is the whole storage model: no
database, no proprietary container, no network dependency. A person can open it in
Finder, Windows Explorer, or a NAS file browser and understand it without any special
tool.

## 2. Design principles

1. **The owner owns the data.** Software serves the passport; the passport does not
   belong to the software.
2. **Local-first.** A passport is fully functional with no network. Nothing is required
   to leave the device.
3. **Human-readable first.** Every folder is self-explanatory; a `README.md` at the root
   is the owner's manual. Machine files sit alongside human files, never replacing them.
4. **Append-only history.** Records are added and timestamped, never silently
   overwritten. History is the point.
5. **Not a medical device.** A passport documents and organizes; it does not diagnose.
   Any automated observation carries a clear non-diagnostic disclaimer.

## 3. Directory layout

A conforming Foot Passport is a directory containing:

```
Foot Passport/
├── README.md            (REQUIRED) owner's manual, human-readable
├── Profile/             (REQUIRED) who the owner is, and why they use FootLab
├── Baseline/            (REQUIRED) initial assessment + permanent anatomical baseline
├── Daily Checks/        daily monitoring sessions and observations
├── Photos/              original foot photographs (source images)
├── AI Reports/          observations generated by AI models + daily summaries
├── Timeline/            longitudinal history of foot-health events
├── Medical Records/     surgical reports, visit notes, imaging
├── Footwear/            shoes, orthotics, braces, prosthetics
├── Thermal/             thermal images and temperature monitoring
├── 3D Scans/            three-dimensional foot scans and models
├── Documents/           educational resources and supporting documents
├── Exports/             reports prepared for sharing with clinicians
└── .footlab/            (REQUIRED) machine state: format version, audit trail, prompt hashes
```

`README.md`, `Profile/`, `Baseline/`, and `.footlab/` are REQUIRED. All other folders are
RECOMMENDED and MAY be empty or absent; a reader MUST tolerate their absence. A writer
MUST NOT delete folders or files it does not own.

Folder names are **case-sensitive** and use spaces exactly as written above.

### 3.1 `Daily Checks/` — the timeline (the heart of the passport)

`Daily Checks/` is organized as **one folder per calendar date**, named `YYYY-MM-DD`.
Each date is a self-contained **chapter** of the owner's foot story:

```
Daily Checks/
├── 2026-05-24/
│   ├── summary.md      the day's chapter cover: what stood out + the model reads
│   ├── notes.md        the owner's notes for the day
│   ├── Photos/         the original photos taken that day
│   ├── AI Reports/     that day's JSON receipts + Markdown reports
│   ├── Temperature/    thermal / skin-temperature readings (if any)
│   └── 3D Scans/       3D foot scans captured that day (if any)
├── 2026-05-25/
└── ...
```

The date is the photo's **true capture date** (e.g. EXIF `DateTimeOriginal`), not the
processing date, so the timeline reflects when the foot actually looked that way. A day
chapter with no photos MAY still exist (a notes-only or temperature-only day). Opening
`Daily Checks/` in a file browser, sorted by name, IS the longitudinal record — five
years of chapters, each readable on its own.

`Photos/` at the passport root remains the flat archive of all originals; day chapters
hold that day's copy so a single day can be handed to a clinician in isolation.

### 3.2 Information model

The passport organizes a lifelong record. The folders above carry this content:

| Section | Lives in | Holds |
|---|---|---|
| **Identity** — why the owner uses FootLab | `Profile/` | `identity.md`, profile |
| **Baseline** — permanent anatomical baseline | `Baseline/` | `left-foot.md`, `right-foot.md` |
| **History** — surgeries, amputations, fractures, hardware, scars | `Baseline/history.md` | permanent surgical/anatomical history |
| **Daily Timeline** — photos, AI reports, notes, temperature, 3D scans | `Daily Checks/<date>/` | per-day chapters (§3.1) |
| **Footwear** — shoes, orthotics, braces, prosthetics | `Footwear/` | footwear records |
| **Visits** — podiatry, surgery, wound care | `Medical Records/` | visit notes |
| **Documents** — operative reports, imaging, PDFs | `Medical Records/`, `Documents/` | source documents |
| **Thermal / 3D** — standalone captures | `Thermal/`, `3D Scans/` | reference captures |
| **Exports** — reports prepared for sharing | `Exports/` | clinician-facing bundles |

## 4. `.footlab/` — machine state

`.footlab/` holds the machine-facing metadata a human doesn't need to see:

- `passport.json` — format descriptor (see §5).
- `audit/` — append-only JSONL audit trail: one line per write, recording filename,
  timestamp, software + version, model, prompt version + SHA-256, and output paths.

A reader MAY ignore `.footlab/` entirely and still understand the passport.

## 5. `passport.json` (format descriptor)

`/.footlab/passport.json` identifies the passport and its format version:

```json
{
  "format": "foot-passport",
  "format_version": "1.0",
  "created": "2026-07-06",
  "owner": "self",
  "generators": [
    { "name": "OpenFootLab", "version": "1.0.0" }
  ]
}
```

`format` MUST be `"foot-passport"`. `format_version` MUST follow semantic versioning; a
reader MUST accept any `1.x` passport and MAY warn on unknown minor versions but MUST NOT
fail. Multiple pieces of software MAY append themselves to `generators`.

## 6. AI Reports — the observation record

Software that writes automated observations SHOULD write, per reviewed image:

- a **JSON receipt** under `AI Reports/json/` — the structured record, and
- a **Markdown report** under `AI Reports/markdown/` — the human-readable version,

plus a **daily rollup** under `AI Reports/` summarizing the day.

### 6.1 Receipt schema (v1)

Each receipt is a JSON object with at least these fields (closed vocabularies shown with
`|`):

```json
{
  "receipt_id": "", "timestamp": "", "source_image": "", "sidecar_notes": "",
  "model": "", "prompt_version": "",
  "patient_context": { "condition": "", "recent_surgery": true, "surgery_context": "", "purpose": "" },
  "image_quality": { "usable": true, "issues": [], "confidence": "low|medium|high" },
  "observations": {
    "foot": "right|left|unknown", "surgery_site_visible": true,
    "redness": "none|mild|moderate|severe|unclear",
    "swelling": "none|mild|moderate|severe|unclear",
    "drainage_or_fluid": "none|present|unclear",
    "discoloration": "none|present|unclear",
    "open_wound_or_skin_break": "none|present|unclear",
    "scab_or_crust": "none|present|unclear",
    "bruising": "none|present|unclear",
    "maceration": "none|present|unclear",
    "pressure_or_friction_signs": "none|present|unclear"
  },
  "comparison": { "prior_image_used": "", "change_summary": "",
                  "possible_worsening": false, "comparison_confidence": "none|low|medium|high" },
  "risk_flag": { "category": "routine_log|watch_closely|contact_clinician|urgent_care", "reasons": [] },
  "plain_english_summary": "", "suggested_next_action": "",
  "medical_disclaimer": "This is not a diagnosis and does not replace review by a qualified clinician."
}
```

### 6.2 Safety rule (normative)

`risk_flag.category` is an **attention level**, ordered:

```
routine_log  <  watch_closely  <  contact_clinician  <  urgent_care
```

A conforming writer MUST derive this level with deterministic rules that a human can
audit, and MUST allow those rules only to **raise** the level, never lower it, relative to
the model's own suggestion. Emergency indicators — spreading redness, pus, foul odor,
fever, black tissue, red streaking, a wound opening after surgery, or rapidly worsening
swelling — MUST escalate to at least `contact_clinician`. Every receipt MUST carry the
non-diagnostic `medical_disclaimer`.

## 7. Naming and time

- Timestamps use ISO-8601 (`2026-07-06T14:30:05`).
- Filenames carrying a timestamp SHOULD be sortable and MUST NOT overwrite an existing
  file; append a counter if a collision occurs.
- Original photographs in `Photos/` MUST NOT be modified by any writer.

## 8. Conformance

**A conforming reader** opens the directory, honors `.footlab/passport.json`, tolerates
missing RECOMMENDED folders, and never modifies files it does not own.

**A conforming writer** preserves the REQUIRED layout, writes append-only, records an
audit line in `.footlab/audit/`, adds itself to `passport.json.generators`, and follows
the §6.2 safety rule when writing automated observations.

## 9. Licensing

This specification is published openly so that anyone may implement it. Implementations
may be commercial or non-commercial. The format imposes no vendor lock-in: a Foot
Passport written by one conforming implementation can be read by any other.

---

_OpenFootLab is the reference implementation of this specification. The Foot Passport
belongs to its owner._