Files
faunosteo/docs/PATHOLOGIES-FORMAT.md
T
Bastien ChanotandClaude 70f21ccf37 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>
2026-05-20 06:15:26 +02:00

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


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:

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

{
  "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 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:

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


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