docs(species): refresh PATHOLOGIES-FORMAT for v2.0 contract
- schema_version "2.0" everywhere; new Changelog section with
v1.0 → v2.0 entries highlighting the breaking change.
- New Scope (legal périmètre) section listing inclusions / exclusions
and the two flag mechanisms (root scope_disclaimer + leaf boolean).
- Clarified SVG ↔ JSON link via strict label equality (not data-anno-id)
and cranio-caudal zone ordering rule.
- Documented the 3 standardized categories per zone
(*-dysfunctions / *-observations / anamnesis) and the 5 dysfunctions
taxonomy patterns (head SSB / head peripheral / articular /
vertebral hinge / vertebral region).
- Documented structural authoring rules (depth ≤ 4, ≥ 2 children per
intermediate, sibling-scoped ID uniqueness).
- Spelled out the v2.0 requires_vet_referral / description_fr policy
(boolean = source of truth; description_fr survives only on
differential leaves) and the breaking-change notice for any consumer
relying on description_fr.includes('vétérinaire').
- Rewrote the minimal example using v2.0 contract (boolean only,
description_fr only when it adds a differential).
- Noted Zod's silent strip of unknown fields (e.g. species.notes,
per-leaf metadata).
- Added current horse.json stats table (26 zones / 792 nodes /
612 leaves / 41 vet leaves).
This commit is contained in:
1 parent
6eda7ebc39
commit
57b58b3af1
1 file changed
+246
-48
+246
-48
@@ -13,18 +13,44 @@ The catalog is loaded once at module import via
|
||||
boot (Zod stack trace pointing at the offending node) — there is no
|
||||
silent fallback.
|
||||
|
||||
**Current schema version: `"2.0"`** — see [Changelog](#changelog) for the
|
||||
breaking changes from v1.x.
|
||||
|
||||
---
|
||||
|
||||
## Scope (legal périmètre — important)
|
||||
|
||||
Catalog entries describe **strictly what an animal osteopath may write
|
||||
in a bilan** under French law:
|
||||
|
||||
- ✅ Palpated osteopathic dysfunctions (SSB lesions, sutures, intra-osseous)
|
||||
- ✅ Mobility restrictions and muscular tensions observed
|
||||
- ✅ Visible mechanical asymmetries
|
||||
- ✅ Clinical observations and consultation motives reported by the owner
|
||||
- ✅ Anamnesis (reported factors)
|
||||
|
||||
- ❌ Medical diagnoses (Cushing, OCM, arthrosis, ankylosis…)
|
||||
- ❌ Organic pathologies requiring imaging / blood work / biopsy
|
||||
- ❌ Anything requiring medical, surgical or pharmaceutical intervention
|
||||
|
||||
The osteopath may **suspect** and **redirect to a veterinarian** but
|
||||
never poses a medical diagnosis. Two mechanisms enforce this in data:
|
||||
the root `scope_disclaimer` field (UI surface) and the boolean
|
||||
`requires_vet_referral` on sensitive leaves (logic surface — see below).
|
||||
|
||||
---
|
||||
|
||||
## Top-level shape
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "1.1",
|
||||
"schema_version": "2.0",
|
||||
"scope_disclaimer": "string non vide — affiché 1× par session dans l'éditeur",
|
||||
"species": {
|
||||
"id": "equine",
|
||||
"name_fr": "Cheval",
|
||||
"name_en": "Horse"
|
||||
"name_en": "Horse",
|
||||
"notes": "optional — clinical context specific to the species"
|
||||
},
|
||||
"zones": {
|
||||
"<zoneKey>": { ... ZoneFindings ... }
|
||||
@@ -34,18 +60,28 @@ silent fallback.
|
||||
|
||||
| Field | Type | Required | Notes |
|
||||
| ------------------ | ------ | -------- | ----------------------------------------------------------- |
|
||||
| `schema_version` | string | yes | non-empty, bump on breaking changes |
|
||||
| `scope_disclaimer` | string | yes | non-empty, shown once per session |
|
||||
| `schema_version` | string | yes | non-empty, bump on breaking changes; current `"2.0"` |
|
||||
| `scope_disclaimer` | string | yes | non-empty, shown once per session via `osteo:disclaimer-shown` flag |
|
||||
| `species.id` | string | yes | should match the `SpeciesManifest.id` in the manifest |
|
||||
| `species.name_fr` | string | yes | |
|
||||
| `species.name_en` | string | yes | |
|
||||
| `species.notes` | string | no | free-text species context; currently stripped by Zod (extend schema before relying on it) |
|
||||
| `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`.
|
||||
`zoneKey` is opaque — kebab-case is the convention. It does NOT have to
|
||||
match SVG `data-anno-id` values (those are usually generator strings).
|
||||
|
||||
**SVG ↔ JSON link is via labels, not IDs.** The runtime matches a
|
||||
clicked SVG element to a JSON zone by comparing `data-anno-name-fr` /
|
||||
`data-anno-name-en` against `zone.name_fr` / `zone.name_en`. The v2.0
|
||||
authoring rule prescribes **strict equality** (case + accents + spaces);
|
||||
`src/lib/zoneMatch.ts` keeps a normalize+Levenshtein fallback as a
|
||||
safety net but content should not depend on it.
|
||||
|
||||
**Zone ordering.** Zones appear in the `zones` dictionary in
|
||||
**cranio-caudal order** (head → tail). JS object insertion order is
|
||||
preserved by modern engines for non-numeric keys, and the picker relies
|
||||
on this — never sort `zones` alphabetically.
|
||||
|
||||
---
|
||||
|
||||
@@ -63,9 +99,39 @@ fuzzy matcher in `src/lib/zoneMatch.ts`.
|
||||
| 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 |
|
||||
| `name_fr` | string | yes | **must equal** SVG `data-anno-name-fr` exactly |
|
||||
| `name_en` | string | yes | **must equal** SVG `data-anno-name-en` exactly |
|
||||
| `categories` | `FindingNode[]` | yes | three standardized buckets (see below) |
|
||||
|
||||
### Three standardized categories per zone
|
||||
|
||||
Each zone exposes exactly three top-level categories in this order:
|
||||
|
||||
1. **Dysfonctions ostéopathiques** — palpation / manipulation, the core
|
||||
work. `id` is zone-prefixed (e.g. `atm-dysfunctions`).
|
||||
2. **Observations / motifs de consultation** — what the owner reports or
|
||||
what is observed (varies per species). `id` is zone-prefixed (e.g.
|
||||
`atm-observations`).
|
||||
3. **Anamnèse / facteurs rapportés** — context. `id` is always plain
|
||||
`anamnesis` (not zone-prefixed).
|
||||
|
||||
### Five taxonomy patterns for `*-dysfunctions`
|
||||
|
||||
The dysfunctions sub-tree follows one of five patterns derived from the
|
||||
zone type — degrees of freedom enumerated, muscles by insertion, sutures
|
||||
by adjacency:
|
||||
|
||||
| Pattern | Zones (horse) | Sub-categories |
|
||||
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
|
||||
| Cranial (SSB axis) | `sphenoid`, `ssb` | `physiological` · `traumatic` · `intraosseous` · `sutures` |
|
||||
| Cranial (peripheral) | `parietal`, `frontal`, `temporal`, `occipital` | `mobility` · `intraosseous` · `sutures` |
|
||||
| Articular | `atm`, `shoulder`, `elbow`, `fore-fetlock`, `hind-fetlock`, `hock`, `hip`, `stifle`, `sacroiliac`, `fore-sesamoids` | `articular` · `muscular` · `mechanical` |
|
||||
| Vertebral hinge | `c0-c1`, `c7-t1`, `t18-l1`, `l6-s1` | `segmental` · `muscular` · `mechanical` |
|
||||
| Vertebral region | `cervical`, `thoracic`, `lumbar`, `sacral`, `caudal` | `segmental` · [`costovertebral`] · `group` · `muscular` · `mechanical` |
|
||||
|
||||
Special cases: `hyoid` (mobility of the hyoid apparatus / associated
|
||||
muscles / intra-osseous), `thoracic` (extra `costovertebral`
|
||||
sub-category).
|
||||
|
||||
---
|
||||
|
||||
@@ -76,9 +142,9 @@ fuzzy matcher in `src/lib/zoneMatch.ts`.
|
||||
"id": "tensions",
|
||||
"name_fr": "Tensions des muscles masticateurs",
|
||||
"name_en": "Masticatory muscle tensions",
|
||||
"description_fr": "optionnel",
|
||||
"description_en": "optionnel",
|
||||
"requires_vet_referral": false,
|
||||
"description_fr": "optionnel — différentiel clinique spécifique uniquement",
|
||||
"description_en": "optional — currently authored FR-only",
|
||||
"requires_vet_referral": true,
|
||||
"sources": [ { ... SourceRef ... } ],
|
||||
"children": [ { ... FindingNode ... } ]
|
||||
}
|
||||
@@ -86,22 +152,75 @@ fuzzy matcher in `src/lib/zoneMatch.ts`.
|
||||
|
||||
| Field | Type | Required | Notes |
|
||||
| ----------------------- | --------------- | -------- | -------------------------------------------------- |
|
||||
| `id` | string | yes | unique within its parent's `children` / `categories` |
|
||||
| `id` | string | yes | unique within its **siblings only** (NOT globally) |
|
||||
| `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 |
|
||||
| `description_fr` | string | no | see policy below (v2.0) |
|
||||
| `description_en` | string | no | reserved — current catalog FR-only |
|
||||
| `requires_vet_referral` | boolean | no | **source of truth** for the vet flag (v2.0) |
|
||||
| `sources` | `SourceRef[]` | no | citations, see below |
|
||||
| `children` | `FindingNode[]` | no | absent or `[]` → leaf (selectable checkbox) |
|
||||
|
||||
**Leaf vs intermediate:**
|
||||
### Leaf vs intermediate
|
||||
|
||||
```ts
|
||||
const isLeaf = (n) => !n.children || n.children.length === 0
|
||||
```
|
||||
|
||||
- `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.
|
||||
|
||||
### Structural constraints (authoring rules)
|
||||
|
||||
- Maximum depth: **4 levels** (category → sub-category → [sub-sub-category] → leaf).
|
||||
- Every intermediate node has **at least 2 children**.
|
||||
- `requires_vet_referral` is **only** set on leaves, never on categories.
|
||||
- IDs are unique among **siblings only**, not globally — `articular`,
|
||||
`muscular`, `mechanical`, `anamnesis`, `trauma-direct` legitimately
|
||||
repeat across zones. Any `findNodeById` helper must therefore be
|
||||
scoped to a single zone root.
|
||||
|
||||
### `requires_vet_referral` and `description_fr` (v2.0)
|
||||
|
||||
Since v2.0 the boolean `requires_vet_referral: true` is the **only**
|
||||
source of truth for the vet-orientation flag. The generic
|
||||
"orienter vers vétérinaire" wording has been **purged** from
|
||||
`description_fr` on leaves where the boolean alone suffices.
|
||||
|
||||
`description_fr` survives on a vet-flagged leaf **only** when it adds a
|
||||
clinical differential the boolean cannot carry — a specific cause to
|
||||
rule out (neurological, sinus, ligament, rotular, cutaneous, osseous,
|
||||
traumatic…). Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "deglutition-difficulty",
|
||||
"name_fr": "Difficulté de déglutition",
|
||||
"name_en": "Swallowing difficulty",
|
||||
"description_fr": "Une difficulté de déglutition impose d'écarter une cause médicale/neurologique : orienter vers vétérinaire avant intervention ostéo.",
|
||||
"requires_vet_referral": true
|
||||
}
|
||||
```
|
||||
|
||||
**Consumer rule:**
|
||||
|
||||
```ts
|
||||
const requiresVetReferral = (n) => n.requires_vet_referral === true
|
||||
```
|
||||
|
||||
**Breaking change from v1.x.** Any consumer that detected the flag by
|
||||
scanning `description_fr.includes('vétérinaire')` will silently miss
|
||||
vet leaves on a v2.0 catalog (25 leaves had that text removed in the
|
||||
v2.0 purge). All in-tree consumers (`FindingsTreePicker`,
|
||||
PDF `observationPage`) already key off the boolean.
|
||||
|
||||
Picker surface: a ⚠ badge is shown next to vet-flagged leaves. PDF
|
||||
surface: the snapshot label is prefixed `⚠` in the
|
||||
`CONSTATS — <ZONE>` section. If a `description_fr` is also present,
|
||||
it is rendered as an additional context line below the children list.
|
||||
|
||||
---
|
||||
|
||||
## SourceRef (optional citation)
|
||||
@@ -120,13 +239,16 @@ fuzzy matcher in `src/lib/zoneMatch.ts`.
|
||||
| `citation` | string | yes | non-empty, human-readable |
|
||||
| `url` | string | no | must pass `z.string().url()` if present |
|
||||
|
||||
Sources are optional in v2.0; recommended on leaves carrying clinical
|
||||
weight (vet-referral leaves, differential descriptions).
|
||||
|
||||
---
|
||||
|
||||
## Minimal complete example
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "1.1",
|
||||
"schema_version": "2.0",
|
||||
"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",
|
||||
@@ -140,30 +262,42 @@ fuzzy matcher in `src/lib/zoneMatch.ts`.
|
||||
"name_en": "Hip joint",
|
||||
"categories": [
|
||||
{
|
||||
"id": "dysf",
|
||||
"name_fr": "Dysfonctions ostéopathiques",
|
||||
"name_en": "Osteopathic dysfunctions",
|
||||
"id": "hanche-dysfunctions",
|
||||
"name_fr": "Dysfonctions ostéopathiques de la hanche",
|
||||
"name_en": "Hip 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": [
|
||||
"id": "articular",
|
||||
"name_fr": "Restrictions de mobilité articulaire",
|
||||
"name_en": "Joint mobility restrictions",
|
||||
"children": [
|
||||
{
|
||||
"type": "journal",
|
||||
"citation": "Smith et al., 2024",
|
||||
"url": "https://example.com/paper"
|
||||
"id": "compression",
|
||||
"name_fr": "Compression articulaire",
|
||||
"name_en": "Joint compression"
|
||||
},
|
||||
{
|
||||
"id": "laxite",
|
||||
"name_fr": "Laxité perçue",
|
||||
"name_en": "Perceived laxity",
|
||||
"description_fr": "Une laxité perçue peut évoquer une atteinte ligamentaire : orienter vers vétérinaire avant intervention ostéo.",
|
||||
"requires_vet_referral": true
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "hanche-observations",
|
||||
"name_fr": "Observations / motifs de consultation",
|
||||
"name_en": "Observations / consultation motives",
|
||||
"children": [ /* ... */ ]
|
||||
},
|
||||
{
|
||||
"id": "anamnesis",
|
||||
"name_fr": "Anamnèse / facteurs rapportés",
|
||||
"name_en": "Anamnesis / reported factors",
|
||||
"children": [ /* ... */ ]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -177,7 +311,12 @@ fuzzy matcher in `src/lib/zoneMatch.ts`.
|
||||
|
||||
- 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.
|
||||
- Recursion through `children` is `z.lazy` — depth is unbounded at the
|
||||
schema level (authoring rule caps it at 4).
|
||||
- Unknown fields on objects are **silently stripped** by Zod's default
|
||||
`z.object` behaviour. Extra metadata (e.g. `species.notes`,
|
||||
custom per-leaf `metadata`) survives in the JSON file but is not
|
||||
surfaced at runtime until the schema declares it.
|
||||
- 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.
|
||||
@@ -200,13 +339,26 @@ When the practitioner toggles a leaf checkbox, the picker emits a
|
||||
```
|
||||
|
||||
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.
|
||||
legible even if the catalog is later edited or renamed (BDR-010). 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.
|
||||
`CONSTATS LIBRES` section listing the free-text additions. Vet-referral
|
||||
leaves are prefixed with ⚠ in the rendered list.
|
||||
|
||||
---
|
||||
|
||||
## Current `horse.json` stats
|
||||
|
||||
| Metric | Count |
|
||||
| --------------------------------------- | ----------- |
|
||||
| Zones (9 head + 17 body) | 26 |
|
||||
| Total nodes | 792 |
|
||||
| Leaves | 612 |
|
||||
| Leaves with `requires_vet_referral` | 41 |
|
||||
| File size (indented) | ~177 KB |
|
||||
|
||||
---
|
||||
|
||||
@@ -215,10 +367,12 @@ In the PDF, findings are grouped by `zoneId` (one
|
||||
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
|
||||
2. Edit the JSON, respecting the schema and structural rules above.
|
||||
3. Ensure every `zone.name_fr` / `zone.name_en` matches the SVG
|
||||
`data-anno-name-fr` / `data-anno-name-en` exactly (case included).
|
||||
4. 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.
|
||||
5. 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.
|
||||
@@ -231,5 +385,49 @@ For production deploys, ship the new JSON via the normal build pipeline
|
||||
| ------------------------------------------ | -------------------------------------------------------------------------- |
|
||||
| `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 |
|
||||
| `src/domain/species/equine/pathologies.json` | Authoritative reference catalog (v2.0, 26 zones) |
|
||||
| `src/lib/zoneMatch.ts` | SVG zone label ↔ JSON zone name fallback matcher |
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
### v2.0 (current) — breaking
|
||||
|
||||
- `requires_vet_referral` boolean becomes the **sole source of truth**
|
||||
for the vet-orientation flag.
|
||||
- Generic vet wording purged from `description_fr` on 25 leaves where
|
||||
the boolean already conveyed the same info. `description_fr` survives
|
||||
on the 16 leaves carrying a clinical differential (cause to rule out).
|
||||
- Consumer helper simplified to `node.requires_vet_referral === true`.
|
||||
Any prior `description_fr.includes('vétérinaire')` fallback **must
|
||||
migrate** to the boolean.
|
||||
- Horse coverage extended placeholder 3 zones → full 26 zones (9 head +
|
||||
17 body), 792 nodes, 612 leaves.
|
||||
|
||||
### v1.2
|
||||
|
||||
- Added the optional boolean `requires_vet_referral` on leaves
|
||||
(still co-existed with vet wording in `description_fr` for
|
||||
backward compatibility — removed in v2.0).
|
||||
- Documented SVG ↔ JSON link via `name_fr` / `name_en` strict match
|
||||
(not `zones.<id>` ↔ `data-anno-id`).
|
||||
- Documented the 5 dysfunctions taxonomy patterns.
|
||||
- Explicit cranio-caudal zone ordering.
|
||||
- Explicit structural constraints (depth ≤ 4, ≥ 2 children per
|
||||
intermediate, sibling-scoped ID uniqueness).
|
||||
|
||||
### v1.1
|
||||
|
||||
- Removed medical diagnoses (OCM, Cushing, hyperthyroidism, arthrosis,
|
||||
ankylosis…) — out of legal scope.
|
||||
- Reformulated diagnoses as observations ("Suite de X", "X rapporté(e)").
|
||||
- Added `scope_disclaimer` at the root + initial `description_fr`
|
||||
vet-orientation hints on sensitive motives.
|
||||
- Standardized 3 categories per zone (Dysfunctions / Observations /
|
||||
Anamnesis).
|
||||
|
||||
### v1.0
|
||||
|
||||
- Initial schema mixing osteopathic dysfunctions with medical
|
||||
diagnoses — non-compliant with French legal scope, corrected in v1.1.
|
||||
Reference in new issue
Block a user