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>
9.1 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.
Top-level shape
{
"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
{
"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)
{
"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:
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.
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 |
Minimal complete example
{
"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
stringfield must be non-empty (z.string().min(1)). urlfields must parse viaz.string().url().- Recursion through
childrenisz.lazy— depth is unbounded. - 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. 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
- 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 above.
- 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 |
src/lib/zoneMatch.ts |
SVG zone label ↔ JSON zone name matcher |