JSON Schema Example (JSON) Example (JSON Lines)

Exfero Health export format

This document describes the files Exfero Health writes: mainly the JSON and JSON Lines formats, which are meant for other programs, and briefly CSV and Markdown. It's for anyone who reads the exports with a script or dashboard.

Tests in the app check that the schema, the example and the data type table below match what the app writes.

Compatibility

schemaVersion changes whenever the structure changes: a field is added, renamed or removed, or a field can hold new values. Readers should check it and refuse or warn about versions they don't know. Files without schemaVersion are version 1. The version history lists every change.

Within one version, every record has the same keys. Missing values are null, never left out.

File names

File names come from the template's pattern. New templates use {name}_{start}_{end}, such as Sleep & Breathing_2026-11-08_2026-11-14.json; templates made with earlier versions (when the app was called HealthPort) keep HealthPort_{start}_{end} until you change it on the Where page. The placeholders are {name} (the template name, with characters a file name can't hold replaced by -, or ExferoHealth when no letter or digit is left), {start} and {end} (the first and last day of the range, such as 2026-11-08), {from} and {to} (the exact start and end of the range, such as 2026-11-07_1200 and 2026-11-15_0000), {date} (the export day) and {time} (the export time, such as 0915), all in the iPhone's time zone. {to} is the exclusive end, so a range that ends at midnight ends at 0000 the next day. The extension follows the format: .json, .jsonl (JSON Lines), .csv or .md. If the folder already holds a file with that name, the template either replaces it or adds a two-digit number counting up from _01: Sleep & Breathing_2026-11-08_2026-11-14_01.json, then _02 and so on.

Top level

Field Type Description
schemaVersion integer The format version, currently 8.
generatedAt timestamp When the export was made.
timeZone string The exporting iPhone's time zone, as an IANA identifier such as Europe/Amsterdam.
range object The period the export covers: start and end (exclusive), both timestamps. See Date range.
recordCount integer The number of items in records.
records array The samples, sorted by startDate. See Records.
deleted array Samples deleted from Health since the previous export. See Since last export.
gaps array Possible gaps in the data. See Gaps.
gapCheck object or null What the gap check looked at. See Gaps.

Timestamps are ISO 8601 in UTC with milliseconds, such as 2026-11-13T22:41:00.000Z. Use timeZone (on a record when present, otherwise the top-level one) to show local times.

Date range

range follows the template's date rule. With Start data at noon the day before, it starts at 12:00 the day before the first day, so the first night is complete: a week then runs from, for example, 2026-11-07T11:00:00.000Z (noon in Amsterdam) to the end of the last day.

Records

Field Type Description
uuid string HealthKit's ID for the sample, in upper case. It's the same in every export, so use it to remove duplicates when exports overlap.
type string The data type, such as heartRate. See the data type table.
value number The value in unit. For category data and workouts: the duration in minutes.
unit string HealthKit's unit syntax, such as count/min. Each type always uses the same unit.
categoryValue string or null For category data, HealthKit's name for the value, such as asleepCore. For workouts, the activity type, such as running. null for quantities.
startDate timestamp When the sample starts.
endDate timestamp When it ends; the same as startDate for instant measurements.
timeZone string or null The time zone the sample was recorded in, when HealthKit knows it (sleep samples usually have one).
source string The name of the app or device that recorded it. The user can rename devices, so don't rely on it.
sourceBundleId string or null The source's bundle identifier, which stays the same when the device is renamed.
deviceModel string or null The hardware model, such as Watch7,3 or iPhone18,2.
attributes object Extra numbers for some types (below); {} otherwise.

Values

Category values

type categoryValue
sleepAnalysis inBed, asleepUnspecified, awake, asleepCore, asleepDeep, asleepREM
appleStandHour stood, idle
menstrualFlow unspecified, light, medium, heavy, none
ovulationTestResult negative, luteinizingHormoneSurge, indeterminate, estrogenSurge
cervicalMucusQuality dry, sticky, creamy, watery, eggWhite
sleepApneaEvent, intermenstrualBleeding always null
workout the activity type, named after HealthKit's HKWorkoutActivityType cases: running, walking, cycling, traditionalStrengthTraining, highIntensityIntervalTraining, yoga and so on; activity<number> for types Exfero Health doesn't name

A value Exfero Health doesn't recognise is written as unknown(<number>).

Attributes

type Key Meaning
workout activeEnergyKcal Active energy burned, in kcal.
workout distanceKm Distance, in km.
workout averageHeartRate Average heart rate, in beats per minute.
menstrualFlow cycleStart 1 if this sample starts a cycle, 0 if not.

Keys only appear when HealthKit has the value; a workout without distance has no distanceKm.

Since last export

With the Since last export rule, an export holds what Health received since the template's previous saved export, whatever the samples' own times. This means:

With other rules deleted is always empty.

Gaps

gaps lists what looks missing or unusual, so readers don't mistake "not measured" for "nothing happened". Every gap has type, kind, start, end and minutes.

kind Meaning start and end
noData A day or night without any data for a type that normally has data. The day (midnight to midnight) or night (noon to noon, with the noon option).
duringSleep Over minimumSleepGapMinutes without samples of a frequently measured type while asleep, on nights that overlap range. The last sample (or start of sleep) before the stretch and the first one after it.
unstagedSleep A night with sleep recorded only as asleepUnspecified, without core, deep or REM stages. The night.
shortSleep A night with less than shortSleepMinutes asleep; minutes holds the time asleep. The night.

minutes is null for every kind except shortSleep.

What gets checked

gapCheck says what was judged, so a type without gaps is known to be complete only if it's listed:

Field Description
periods days (midnight to midnight) or nights (noon to noon, when the range starts at noon the day before).
missingDataMetrics Types checked for noData. A type is checked when it has data on at least half of the complete periods from its first data on; earlier periods don't count, as the feature may have been off.
duringSleepMetrics Types checked for duringSleep: those measured on average at least every frequentSpacingMinutes while asleep. Rarely measured types such as blood oxygen usually aren't listed.
minimumSleepGapMinutes The shortest stretch during sleep that counts as a gap (60).
frequentSpacingMinutes The typical spacing during sleep up to which a type counts as frequently measured (15).
shortSleepMinutes Nights with less time asleep are shortSleep (300).

Only complete periods inside range and before the export time are checked: the current day is still being recorded. "Asleep" means sleep stages starting with asleep, taken from the export's own sleepAnalysis records; time in bed and awake don't count. Night-based checks (unstagedSleep, shortSleep) always use nights from noon to noon. gapCheck is null if the check didn't run.

Reading exports

JSON Lines

A JSON Lines export (.jsonl, see jsonlines.org) holds the same information as a JSON export, with one compact JSON object per line, so it can be read line by line without loading the whole file. Lines end with a line feed, including the last one.

Each line starts with entry, which says what it holds:

entry Fields Lines
export The top-level fields without records, deleted and gaps. Always the first line, exactly once.
record The record fields. One per record, sorted by startDate.
deleted uuid and type, as in deleted. One per deleted sample.
gap The gap fields. One per gap.

Apart from entry, keys are sorted, as in JSON. schemaVersion on the first line has the same meaning as in JSON; each line other than the first validates against the matching definition in export.schema.json once entry is removed.

{"entry":"export","gapCheck":{…},"generatedAt":"2026-11-14T09:15:00.000Z","range":{…},"recordCount":4,"schemaVersion":8,"timeZone":"Europe/Amsterdam"}
{"entry":"record","attributes":{},"categoryValue":null,…,"type":"heartRate","unit":"count/min","uuid":"0A9B8C7D-…","value":58}
{"entry":"deleted","type":"heartRate","uuid":"5B6C7D8E-…"}
{"entry":"gap","end":"2026-11-13T05:40:00.000Z","kind":"duringSleep","minutes":null,"start":"2026-11-13T02:10:00.000Z","type":"heartRate"}

CSV and Markdown

CSV follows RFC 4180, with CRLF line endings and one row per record. The columns are type, value, unit, category_value, start_date, end_date, time_zone, source, source_bundle_id, device_model, uuid and attributes, with the same meaning as the JSON fields. Empty cells stand for null. attributes holds key=value pairs separated by ;. Text that a spreadsheet would run as a formula (starting with =, +, -, @, a tab or carriage return) starts with an apostrophe. CSV has no deleted, gaps or gapCheck.

Markdown is a report for people: the export's details, possible gaps, a summary table per metric (count, minimum, maximum, average, total), then a table of every record per metric. Its layout isn't meant for parsing.

Version history

Version Change
1 No schemaVersion field; whole-second timestamps.
2 Added uuid, sourceBundleId, deviceModel, record timeZone, top-level timeZone and sleep data; percentages became 0–100.
3 Timestamps gained milliseconds; breathing disturbances changed from count to count/hr.
4 Added attributes (workouts, cycle start) and 38 more data types, including workouts and cycle tracking.
5 Added deleted; Since last export uses what Health received.
6 Added gaps with kinds noData and duringSleep.
7 Added gap kinds unstagedSleep and shortSleep, the gap field minutes, and gapCheck.
8 Added 15 workout detail types: cycling speed, power, cadence and FTP; rowing, paddle sports, skating and cross-country skiing distance and speed; workout effort; underwater depth and water temperature.

Data types

All 75 types Exfero Health exports, with their type and unit. Kind quantity means a measured value in unit; category and workout have the duration in minutes as value.

Category type Name unit Kind
Activity stepCount Steps count quantity
Activity distanceWalkingRunning Walking + Running Distance km quantity
Activity flightsClimbed Flights Climbed count quantity
Activity activeEnergyBurned Active Energy kcal quantity
Activity basalEnergyBurned Resting Energy kcal quantity
Activity appleExerciseTime Exercise Minutes min quantity
Activity appleStandTime Stand Minutes min quantity
Activity appleStandHour Stand Hours min category
Activity distanceCycling Cycling Distance km quantity
Activity distanceSwimming Swimming Distance m quantity
Activity swimmingStrokeCount Swimming Strokes count quantity
Activity physicalEffort Physical Effort kcal/hr*kg quantity
Running runningSpeed Running Speed km/hr quantity
Running runningPower Running Power W quantity
Running runningStrideLength Running Stride Length m quantity
Running runningGroundContactTime Ground Contact Time ms quantity
Running runningVerticalOscillation Vertical Oscillation cm quantity
Workouts workout Workouts min workout
Workouts workoutEffortScore Workout Effort appleEffortScore quantity
Workouts estimatedWorkoutEffortScore Estimated Workout Effort appleEffortScore quantity
Workouts cyclingSpeed Cycling Speed km/hr quantity
Workouts cyclingPower Cycling Power W quantity
Workouts cyclingCadence Cycling Cadence count/min quantity
Workouts cyclingFunctionalThresholdPower Cycling FTP W quantity
Workouts distanceRowing Rowing Distance km quantity
Workouts rowingSpeed Rowing Speed km/hr quantity
Workouts distancePaddleSports Paddle Sports Distance km quantity
Workouts paddleSportsSpeed Paddle Sports Speed km/hr quantity
Workouts distanceSkatingSports Skating Distance km quantity
Workouts distanceCrossCountrySkiing Cross-Country Skiing Distance km quantity
Workouts crossCountrySkiingSpeed Cross-Country Skiing Speed km/hr quantity
Workouts underwaterDepth Underwater Depth m quantity
Workouts waterTemperature Water Temperature degC quantity
Mobility walkingSpeed Walking Speed km/hr quantity
Mobility walkingStepLength Walking Step Length cm quantity
Mobility walkingAsymmetryPercentage Walking Asymmetry % quantity
Mobility walkingDoubleSupportPercentage Double Support Time % quantity
Mobility appleWalkingSteadiness Walking Steadiness % quantity
Mobility stairAscentSpeed Stair Speed: Up m/s quantity
Mobility stairDescentSpeed Stair Speed: Down m/s quantity
Mobility sixMinuteWalkTestDistance Six-Minute Walk m quantity
Heart heartRate Heart Rate count/min quantity
Heart restingHeartRate Resting Heart Rate count/min quantity
Heart walkingHeartRateAverage Walking Heart Rate Average count/min quantity
Heart heartRateVariabilitySDNN Heart Rate Variability ms quantity
Heart bloodPressureSystolic Blood Pressure (Systolic) mmHg quantity
Heart bloodPressureDiastolic Blood Pressure (Diastolic) mmHg quantity
Heart vo2Max Cardio Fitness (VO₂ max) ml/kg*min quantity
Heart heartRateRecoveryOneMinute Heart Rate Recovery count/min quantity
Body Measurements bodyMass Weight kg quantity
Body Measurements height Height cm quantity
Body Measurements bodyMassIndex Body Mass Index count quantity
Body Measurements bodyFatPercentage Body Fat Percentage % quantity
Respiratory respiratoryRate Respiratory Rate count/min quantity
Respiratory oxygenSaturation Blood Oxygen % quantity
Sleep sleepAnalysis Sleep Stages min category
Sleep appleSleepingWristTemperature Wrist Temperature degC quantity
Sleep appleSleepingBreathingDisturbances Breathing Disturbances count/hr quantity
Sleep sleepApneaEvent Sleep Apnea Events min category
Nutrition dietaryEnergyConsumed Dietary Energy kcal quantity
Nutrition dietaryProtein Protein g quantity
Nutrition dietaryCarbohydrates Carbohydrates g quantity
Nutrition dietaryFatTotal Total Fat g quantity
Nutrition dietarySugar Sugar g quantity
Nutrition dietaryFiber Fibre g quantity
Nutrition dietarySodium Sodium mg quantity
Nutrition dietaryCaffeine Caffeine mg quantity
Nutrition numberOfAlcoholicBeverages Alcoholic Drinks count quantity
Nutrition dietaryWater Water mL quantity
Hearing environmentalAudioExposure Environmental Sound Levels dBASPL quantity
Hearing headphoneAudioExposure Headphone Audio Levels dBASPL quantity
Cycle Tracking menstrualFlow Menstrual Flow min category
Cycle Tracking intermenstrualBleeding Spotting min category
Cycle Tracking ovulationTestResult Ovulation Test min category
Cycle Tracking cervicalMucusQuality Cervical Mucus Quality min category