# 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": { "": { ... 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: "", path: ["", "", ..., ""], labelFrSnapshot: "", labelEnSnapshot: "", 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 — ` 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 |