Health.md export reference
Deze inhoud is nog niet vertaald.
This reference documents the data Health.md can produce for users, scripts, databases, and connected applications. It covers readable daily summaries and the source-level Apple Health records behind them.
The reference is written for two audiences:
- Users deciding which formats and metrics to export.
- Developers building parsers, automations, data warehouses, Obsidian workflows, or connected clients.
All committed examples use deterministic synthetic data. They contain no real health information.
Contract authority
Section titled “Contract authority”When sources disagree, use this order:
- Production exporters, serializers, metric catalogs, and protocol models.
- The committed versioned export-schema signature.
- Generated examples and generated field inventories.
- Explanatory prose.
The generated artifacts are rebuilt by running the real production code against a fixed synthetic corpus. CI compares regenerated output byte-for-byte with the committed files. This keeps examples from drifting into hand-written approximations.
Current schemas
Section titled “Current schemas”| Surface | Identifier | Current version | Purpose |
|---|---|---|---|
| Daily record | healthmd.health_data |
8 | Apple daily summaries, optional typed provider sections, diagnostics, and optional canonical archive. |
| Typed WHOOP day | healthmd.provider.whoop_daily |
1 | Provider-namespaced WHOOP cycles, recovery, sleep, workouts, body snapshot, and safe resource status. |
| Canonical Apple Health archive | healthmd.healthkit_records |
1 | Source records, provenance, relationships, query results, and external records. |
| Roll-up summary | healthmd.rollup_summary |
9 | One immutable requested-range projection derived from successful daily summaries; historical weekly/monthly/yearly v8 files remain valid. |
| API Endpoint envelope | healthmd.api_export |
1 or 2 | One or more daily records sent to a configured endpoint; v2 adds provider sidecars. |
| Strict CLI raw result | healthmd.raw_result |
1 | Canonical daily records returned through the Mac CLI without writing files. |
| Compact context day | healthmd.query_context_day |
1 | Portable typed query input with coverage and evidence locators. |
| Query request/response/error | healthmd.query_request / healthmd.query_response / healthmd.query_error |
1 | Shared paged query semantics and structured failures. |
| Evidence packet | healthmd.evidence_packet |
1 | Deterministic factual results linked to source evidence. |
| Connected app protocol | Versioned capabilities/messages | Independent | Mac–iPhone requests, progress, transfer, acknowledgement, and results. |
Versions advance independently. A newer API or connected-protocol envelope does not automatically change the daily-record schema.
Choose an export surface
Section titled “Choose an export surface”| Need | Recommended surface | Exact source records? | Human-readable? |
|---|---|---|---|
| Complete machine archive | JSON | Yes | Partly |
| Spreadsheet or stream ingestion | CSV | Yes, as canonical JSON cells | Partly |
| Daily journal | Markdown | No; compact diagnostics only | Yes |
| Obsidian database properties | Obsidian Bases | No; compact diagnostics only | Frontmatter |
| One note per source event | Individual Entry Tracking | Selected UUID-backed records | Yes |
| Send to your own service | API Endpoint | Yes when lossless capture is enabled | No |
| Terminal automation | Mac CLI strict raw | Yes | No |
| Local queries and evidence | Loopback query API/CLI/MCP | Directly scoped | Typed JSON |
| Requested-range trends | Roll-ups | No; summary projections | Yes |
Reference map
Section titled “Reference map”- Daily records: top-level structure, summary layers, omission rules, units, and format mapping.
- Canonical Apple Health records: UUID-backed records, external identities, metadata tags, payloads, relationships, and specialized domains.
- Query manifests and diagnostics: completeness, status values, failures, warnings, and partial results.
- Compact queries and evidence packets: typed values, unlimited cursor-paged access, evidence locators, comparisons, and factual packet derivations.
- Export formats: JSON, CSV, Markdown, and Obsidian Bases contracts and complete examples.
- Individual Entry Tracking: source-backed note identity, filenames, frontmatter, and fallbacks.
- API and CLI: API Endpoint envelopes, local control/query routes, CLI, strict raw results, and exit behavior.
- Connected Mac–iPhone protocol: requests, capabilities, progress, bounded transfers, and results.
- Data dictionary and roll-ups: metric definitions, units, aggregation, and period summaries.
- Other export surfaces: Preview, Daily Note Injection, Shortcuts, scheduling, Manual IP, sidecars, and contract reuse.
- Integration recipes: copyable Python, TypeScript,
jq, DuckDB, API, CLI, and Individual Entry parsing patterns. - Generated documentation workflow: how examples are produced and checked.
Generated references
Section titled “Generated references”The generated directory contains complete, copyable fixtures rather than shortened snippets:
generated/core/: daily exports, canonical records, data dictionary, metric catalog, path/type inventories, and CSV contracts.generated/individual/: canonical and compatibility entry notes, filename/path behavior, and recursive frontmatter inventory.generated/rollups/: production range-v9 JSON/CSV/Markdown/Bases output, historical weekly-v8 examples, and the complete aggregation matrix.generated/automation/: API, localhost control, strict raw, sync-message, connected-transfer, and Mac job/result contracts.generated/cli/: executable CLI requests, responses, diagnostics, and exit-code behavior.
Generated files may be large because they intentionally exercise optional branches and specialized payloads. Start with the hand-written reference pages, then open the complete fixture relevant to your integration.
Compatibility rules for consumers
Section titled “Compatibility rules for consumers”- Branch on every declared schema identifier and version.
- Preserve unknown keys, enum values, metadata tags, and record kinds when possible.
- Treat absent optional fields as absent, never as zero or false.
- Inspect capture status and every query result before claiming completeness.
- Use source UUIDs or documented external identities for deduplication.
- Use canonical archive timestamps for source-event joins; summary clock fields are presentation values.
- Parse CSV with an RFC 4180 implementation. Do not split on commas or physical lines.
- Keep historical files under their original version. Never relabel older exports as v8.
Privacy
Section titled “Privacy”Lossless exports may include exact timestamps, route locations, medications, mental-wellbeing entries, clinical content, source/device details, ECG measurements, documents, and binary attachments. Health.md keeps local exports on the selected device or destination, but API and CLI users control where copied data goes. Apply encryption, access controls, retention limits, and logging policies appropriate for sensitive health information.