Files
faunosteo/docs/PATHOLOGIES-FORMAT.md
T
Bastien Chanot 8385b49bbe docs: sync drift after catalog v2.0 + i18n + WinAnsi hotfix
doc-syncer audit applied 10 AUTO patches and 1 HUMAN reword (#5)
across the doc set.

README.md:
- Test count "7 tests pass on skeleton" / "88 tests across 23 files"
  → "155 tests" / "155 tests across 29 files".
- Reword "Observation builder" bullet + add hierarchical findings
  tree + browser-detected locale bullets (HUMAN #5).
- Status paragraph: pathology DB "intentionally empty" → full
  26-zone v2.0 catalog (792 nodes, 612 leaves, 41 vet leaves).
- Documentation section: add PATHOLOGIES-FORMAT.md link; tidy the
  DEPLOY.md mention (DEPLOY.md itself comes in the next commit).

CLAUDE.md:
- Architecture block: "embedFonts (Inter body + Fraunces heading)"
  → reality (Helvetica + TimesRoman / WinAnsi StandardFonts; TTF
  Inter/Fraunces planned).
- PDF convention: "Fonts are TTF" → "Fonts are StandardFonts
  (Helvetica/TimesRoman, WinAnsi)" with the ASCII-surrogate caveat.
- Folder map: add src/anatomy/labels.ts, include zoneMatch.ts in
  src/lib/{...}.ts.
- i18n: locale default "fr" → "navigator-detected fr/en, or 'fr'
  if no match" to match commit 9cf8a66.

docs/PATHOLOGIES-FORMAT.md:
- "PDF surface: snapshot label is prefixed ⚠" → "(!)" in two
  places (after WinAnsi hotfix 143fdc3). Picker ⚠ statement
  kept — browser renders U+26A0 natively.

docs/ADDING-A-SPECIES.md:
- data-anno-category: "Free-form" → enum of 7 valid values per
  ANATOMY-SVG-CONVENTION.md; parser throws SvgConventionError on
  unknown values.
- Section 4 (findings catalog): cross-link to
  docs/PATHOLOGIES-FORMAT.md so authors find the v2.0 contract.
2026-05-21 04:13:13 +02:00

19 KiB
Raw Blame History

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.


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:

  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).


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
  • 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:

{
  "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 (the picker ⚠ cannot be rendered until the PDF font path migrates from WinAnsi StandardFonts to TTF). 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 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 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.

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

  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 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.
  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.


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_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.