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