docs: add PATHOLOGIES-FORMAT spec for the findings JSON catalog

Documents the canonical pathologies.json shape next to the existing
ANATOMY-SVG-CONVENTION and PDF-FORMAT guides. Mirrors the Zod
contract in src/domain/schema/findings.ts:

- Top-level frame (schema_version, scope_disclaimer, species, zones).
- ZoneFindings shape and how name_fr/name_en bridge to SVG labels.
- Recursive FindingNode (leaf vs intermediate, optional description,
  vet-referral flag, sources).
- SourceRef enum + URL validation.
- A minimal worked example.
- How leaf selections become persisted Findings, with the labelFr/En
  snapshot contract that protects already-exported reports from
  retroactive catalog edits.
- Authoring workflow that defers to `pnpm scaffold:species` and Vite
  HMR-driven validation.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Bastien ChanotandClaude committed 2026-05-20 06:15:26 +02:00
1 parent 70b7f20f6f
commit 70f21ccf37
1 file changed
+235
+235
View File
@@ -0,0 +1,235 @@
# Pathologies / Findings JSON Format
Each species ships a `pathologies.json` next to its `index.ts` manifest.
The JSON encodes the **hierarchical findings catalog** the practitioner
sees in the editor's per-zone picker and in the exported PDF.
The single source of truth is the Zod schema at
[`src/domain/schema/findings.ts`](../src/domain/schema/findings.ts) —
this document mirrors it.
The catalog is loaded once at module import via
`SpeciesFindingsSchema.parse(data)`. A malformed JSON crashes loudly at
boot (Zod stack trace pointing at the offending node) — there is no
silent fallback.
---
## Top-level shape
```json
{
"schema_version": "1.1",
"scope_disclaimer": "string non vide — affiché 1× par session dans l'éditeur",
"species": {
"id": "equine",
"name_fr": "Cheval",
"name_en": "Horse"
},
"zones": {
"<zoneKey>": { ... ZoneFindings ... }
}
}
```
| Field | Type | Required | Notes |
| ------------------ | ------ | -------- | ----------------------------------------------------------- |
| `schema_version` | string | yes | non-empty, bump on breaking changes |
| `scope_disclaimer` | string | yes | non-empty, shown once per session |
| `species.id` | string | yes | should match the `SpeciesManifest.id` in the manifest |
| `species.name_fr` | string | yes | |
| `species.name_en` | string | yes | |
| `zones` | object | yes | dictionary keyed by free-form `zoneKey` → `ZoneFindings` |
`zoneKey` is opaque — kebab-case is the convention. It does NOT have
to match SVG `data-anno-id` values (those are usually generator
strings). The runtime matches SVG zones to JSON zones via
`bone.fr` / `bone.en` ⇄ `zone.name_fr` / `zone.name_en` using the
fuzzy matcher in `src/lib/zoneMatch.ts`.
---
## ZoneFindings
```json
{
"id": "sphenoid",
"name_fr": "Sphénoïde",
"name_en": "Sphenoid",
"categories": [ { ... FindingNode ... } ]
}
```
| Field | Type | Required | Notes |
| ------------ | --------------- | -------- | --------------------------------------------------------- |
| `id` | string | yes | by convention the same string as the parent `zoneKey` |
| `name_fr` | string | yes | matched against SVG `data-anno-name-fr` |
| `name_en` | string | yes | matched against SVG `data-anno-name-en` |
| `categories` | `FindingNode[]` | yes | may be empty |
---
## FindingNode (recursive)
```json
{
"id": "tensions",
"name_fr": "Tensions des muscles masticateurs",
"name_en": "Masticatory muscle tensions",
"description_fr": "optionnel",
"description_en": "optionnel",
"requires_vet_referral": false,
"sources": [ { ... SourceRef ... } ],
"children": [ { ... FindingNode ... } ]
}
```
| Field | Type | Required | Notes |
| ----------------------- | --------------- | -------- | -------------------------------------------------- |
| `id` | string | yes | unique within its parent's `children` / `categories` |
| `name_fr` | string | yes | |
| `name_en` | string | yes | |
| `description_fr` | string | no | surfaced above the children list in the picker |
| `description_en` | string | no | reserved for future locale switch |
| `requires_vet_referral` | boolean | no | adds a ⚠ badge in picker and a ⚠ prefix in PDF |
| `sources` | `SourceRef[]` | no | citations, see below |
| `children` | `FindingNode[]` | no | absent or `[]` → leaf (selectable checkbox) |
**Leaf vs intermediate:**
- `children` missing or empty → **leaf**. Rendered as a checkbox.
Selecting it emits a `Finding` with the full path snapshot.
- `children` non-empty → **intermediate**. Rendered as a drill-down
button. The badge next to it counts selected descendants.
---
## SourceRef (optional citation)
```json
{
"type": "journal",
"citation": "Auteur, 'Titre', Journal, 2024",
"url": "https://example.com/paper"
}
```
| Field | Type | Required | Notes |
| ---------- | --------------------------------------------- | -------- | -------------------------------------- |
| `type` | `"manual" \| "journal" \| "database" \| "web"` | yes | enum, validated by Zod |
| `citation` | string | yes | non-empty, human-readable |
| `url` | string | no | must pass `z.string().url()` if present |
---
## Minimal complete example
```json
{
"schema_version": "1.1",
"scope_disclaimer": "Les éléments listés correspondent au périmètre légal de l'ostéopathie animale : dysfonctions ostéopathiques palpées, observations cliniques et motifs de consultation. Aucun diagnostic médical n'est posé. Toute pathologie organique relève du vétérinaire.",
"species": {
"id": "canine",
"name_fr": "Chien",
"name_en": "Dog"
},
"zones": {
"hanche": {
"id": "hanche",
"name_fr": "Hanche (coxo-fémorale)",
"name_en": "Hip joint",
"categories": [
{
"id": "dysf",
"name_fr": "Dysfonctions ostéopathiques",
"name_en": "Osteopathic dysfunctions",
"children": [
{
"id": "compression",
"name_fr": "Compression articulaire",
"name_en": "Joint compression",
"description_fr": "Restriction de mobilité dans plusieurs plans"
},
{
"id": "instabilite",
"name_fr": "Instabilité",
"name_en": "Instability",
"requires_vet_referral": true,
"sources": [
{
"type": "journal",
"citation": "Smith et al., 2024",
"url": "https://example.com/paper"
}
]
}
]
}
]
}
}
}
```
---
## Validation rules
- Every required `string` field must be non-empty (`z.string().min(1)`).
- `url` fields must parse via `z.string().url()`.
- Recursion through `children` is `z.lazy` — depth is unbounded.
- A bad JSON throws a Zod error at `pathologies.ts` import time, with a
path pointing at the offending node — the editor never starts with a
half-valid catalog.
---
## How selections become reports
When the practitioner toggles a leaf checkbox, the picker emits a
`Finding`:
```ts
{
zoneId: "<the zone key>",
path: ["<category id>", "<sub id>", ..., "<leaf id>"],
labelFrSnapshot: "<leaf.name_fr at click time>",
labelEnSnapshot: "<leaf.name_en at click time>",
requiresVetReferral?: true
}
```
The snapshot fields freeze the label so already-exported reports stay
legible even if the catalog is later edited or renamed. The `path` is
kept for future re-link / migration tooling but is never required to
re-render an existing report.
In the PDF, findings are grouped by `zoneId` (one
`CONSTATS — <ZONE>` section per zone) followed by a single
`CONSTATS LIBRES` section listing the free-text additions.
---
## Authoring workflow
1. Copy `src/domain/species/equine/pathologies.json` as a reference,
or scaffold a new species via `pnpm scaffold:species` (writes a
minimal valid skeleton).
2. Edit the JSON, respecting the schema above.
3. Run `pnpm dev` — Vite HMR reloads the module, Zod parses the new
tree, errors surface immediately on save.
4. The picker and PDF pick up changes without any code edit.
For production deploys, ship the new JSON via the normal build pipeline
(`pnpm build`) — there is no runtime hot-reload outside the dev server.
---
## Related schemas
| File | Purpose |
| ------------------------------------------ | -------------------------------------------------------------------------- |
| `src/domain/schema/findings.ts` | Zod definitions: `FindingNode`, `ZoneFindings`, `SpeciesFindings`, `SourceRef` |
| `src/domain/schema/observation.ts` | `Finding` snapshot stored on an observation |
| `src/domain/species/equine/pathologies.json` | Authoritative reference catalog |
| `src/lib/zoneMatch.ts` | SVG zone label ↔ JSON zone name matcher |