- 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).
19 KiB
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 —
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.
Current schema version: "2.0" — see 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
{
"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",
"notes": "optional — clinical context specific to the species"
},
"zones": {
"<zoneKey>": { ... ZoneFindings ... }
}
}
| Field | Type | Required | Notes |
|---|---|---|---|
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).
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.
ZoneFindings
{
"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 | 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:
- Dysfonctions ostéopathiques — palpation / manipulation, the core
work.
idis zone-prefixed (e.g.atm-dysfunctions). - Observations / motifs de consultation — what the owner reports or
what is observed (varies per species).
idis zone-prefixed (e.g.atm-observations). - Anamnèse / facteurs rapportés — context.
idis always plainanamnesis(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).
FindingNode (recursive)
{
"id": "tensions",
"name_fr": "Tensions des muscles masticateurs",
"name_en": "Masticatory muscle tensions",
"description_fr": "optionnel — différentiel clinique spécifique uniquement",
"description_en": "optional — currently authored FR-only",
"requires_vet_referral": true,
"sources": [ { ... SourceRef ... } ],
"children": [ { ... FindingNode ... } ]
}
| Field | Type | Required | Notes |
|---|---|---|---|
id |
string | yes | unique within its siblings only (NOT globally) |
name_fr |
string | yes | |
name_en |
string | yes | |
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
const isLeaf = (n) => !n.children || n.children.length === 0
childrenmissing or empty → leaf. Rendered as a checkbox. Selecting it emits aFindingwith the full path snapshot.childrennon-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_referralis only set on leaves, never on categories.- IDs are unique among siblings only, not globally —
articular,muscular,mechanical,anamnesis,trauma-directlegitimately repeat across zones. AnyfindNodeByIdhelper 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:
{
"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:
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)
{
"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 |
Sources are optional in v2.0; recommended on leaves carrying clinical weight (vet-referral leaves, differential descriptions).
Minimal complete example
{
"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",
"name_fr": "Chien",
"name_en": "Dog"
},
"zones": {
"hanche": {
"id": "hanche",
"name_fr": "Hanche (coxo-fémorale)",
"name_en": "Hip joint",
"categories": [
{
"id": "hanche-dysfunctions",
"name_fr": "Dysfonctions ostéopathiques de la hanche",
"name_en": "Hip osteopathic dysfunctions",
"children": [
{
"id": "articular",
"name_fr": "Restrictions de mobilité articulaire",
"name_en": "Joint mobility restrictions",
"children": [
{
"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": [ /* ... */ ]
}
]
}
}
}
Validation rules
- Every required
stringfield must be non-empty (z.string().min(1)). urlfields must parse viaz.string().url().- Recursion through
childrenisz.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.objectbehaviour. Extra metadata (e.g.species.notes, custom per-leafmetadata) 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.tsimport 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:
{
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 (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. 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 |
Authoring workflow
- Copy
src/domain/species/equine/pathologies.jsonas a reference, or scaffold a new species viapnpm scaffold:species(writes a minimal valid skeleton). - Edit the JSON, respecting the schema and structural rules above.
- Ensure every
zone.name_fr/zone.name_enmatches the SVGdata-anno-name-fr/data-anno-name-enexactly (case included). - Run
pnpm dev— Vite HMR reloads the module, Zod parses the new tree, errors surface immediately on save. - 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 (v2.0, 26 zones) |
src/lib/zoneMatch.ts |
SVG zone label ↔ JSON zone name fallback matcher |
Changelog
v2.0 (current) — breaking
requires_vet_referralboolean becomes the sole source of truth for the vet-orientation flag.- Generic vet wording purged from
description_fron 25 leaves where the boolean already conveyed the same info.description_frsurvives on the 16 leaves carrying a clinical differential (cause to rule out). - Consumer helper simplified to
node.requires_vet_referral === true. Any priordescription_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_referralon leaves (still co-existed with vet wording indescription_frfor backward compatibility — removed in v2.0). - Documented SVG ↔ JSON link via
name_fr/name_enstrict match (notzones.<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_disclaimerat the root + initialdescription_frvet-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.