Mapping guides

Bidirectional mapping to and from incumbent schemas is OpenBody’s primary success measure and its adoption wedge: the standard is a universal adapter. These guides are built from the real mappers in openbody-ts/src/mappers — pure input → records[] functions, round-trip tested (npm run mappers).

The lossless guarantee is directional (§10)

• incumbent → OpenBody is lossless — OpenBody is the superset; anything lacking a core home is preserved via extensions or the opaque fallback.
• source → OpenBody → source (a source-anchored round-trip) is lossless.
• Emitting OpenBody’s full expressiveness into a less-expressive target (a %1RM target or a superset into a schema with no field for it) is necessarily best-effort and bounded by that target — a limit of the target, not a defect of OpenBody.

Mapping principles (§10.1)

• Canonical-plus-residue. Map each source construct to its canonical OpenBody equivalent; carry anything with no canonical home in namespaced extensions or, for identity, the opaque fallback. Nothing is dropped.
• Lazy terminology. Source type tokens are preserved source-namespaced on ingest and resolved to external codes (LOINC / SNOMED / UCUM / MET) only on output.
• Provenance preserved. Source platform, app, and device become registry-backed provenance tokens; the source’s own key becomes clientRecordId.
• Round-trip. Source → canonical → source MUST preserve meaning under the §8.3 equivalence rule.

The guides

Hevy Strength CSV → Session / Block(superset) / Exercise / WorkUnit, with reps/load/RPE and set roles.

Strong Strong CSV → the same shape, with an app-specific extension namespace.

Strava Activity + streams → sampleArray Measurements + a Session linked by measuredBy. Both pillars.

Apple Health / Health Connect export.xml → quantity / category Measurements + HKWorkout → Session. Health Connect maps identically.

What fit cleanly, and what to watch

Real-data dogfooding found no model gaps for strength (Hevy/Strong), telemetry (Strava), or Pillar A (Apple Health). Three things to keep in mind, surfaced by the mappers: every app has a workout title (now the v0.3 name); derivedFrom ⇒ provenance.algorithm is recommended and incumbents rarely publish it; and a Session carries at most one container kind (§5.3), so a mix of supersets + standalone exercises maps to all-blocks.