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:
1 parent
70b7f20f6f
commit
70f21ccf37
1 file changed
+235
@@ -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 |
|
||||||
Reference in new issue
Block a user