Data Rules

gpx-export converts typed input into a consistent GPX 1.1 document. This page describes how values are merged and serialized.

Serialization rules

Required fields are explicit in TypeScript types.
Dates are emitted as ISO-8601 with toISOString().
String element values and selected attributes are XML-escaped.
Optional fields appear only when provided.
Elevation is formatted to 2 decimal places.
Garmin speed is formatted to 4 decimal places.

Document handling

generateGpx(track, metadata?) accepts tracks-only input.
generateGpx(document, metadata?) accepts full GpxDocument input.
Track input is normalized to a one-track document internally.
Provided metadata shallow-merges into document.metadata.

Track and segment behavior

If track.segments is provided and non-empty, those segments are emitted.
Otherwise, a single segment is created from track.points (or empty points).
Track points require time; route points and waypoints use optional time.

Extensions behavior

Garmin namespace/schema declarations are added when Garmin metrics are present on track points.
Garmin point values map to gpxtpx:speed, gpxtpx:hr, and gpxtpx:cad on track points.
GpxPoint.speed exists as a legacy compatibility alias; extensions.speed is the canonical field for new code.
When both are provided on a track point, extensions.speed takes precedence.
Extension rawXml values are trusted XML and are not escaped.

Recommended workflow

Validate your source data before generation, then call generateGpx() and persist or upload the resulting GPX XML.