ISO 8601 Duration Parser
Parse ISO 8601 duration strings into component parts.
Overview
The ISO 8601 Duration Parser takes a duration string in the PnYnMnDTnHnMnS format used by ISO 8601 — P3Y6M4DT12H30M5S for "3 years 6 months 4 days 12 hours 30 minutes 5 seconds" — and breaks it into its individual numeric components. Each field is shown separately with its unit, plus a total seconds figure where the calendar components are unambiguous.
Useful for developers debugging XML schema or JSON Schema duration fields, integrators wiring up REST APIs that use ISO 8601 (Stripe, AWS, GitHub Actions all do), and anyone who has stared at a string like PT15M wondering whether it means 15 minutes or 15 months.
How it works
The parser implements the ISO 8601-1:2019 duration grammar. A duration always starts with P (period), optionally followed by year (Y), month (M), week (W), and day (D) components, then a T separator, and finally hour (H), minute (M), and second (S) time components. Fractional values are permitted on the last present component using either . or , as the decimal separator.
Note the dual meaning of M: before T it is months, after T it is minutes. Week format (P3W) is mutually exclusive with the other components — the spec does not allow mixing W with Y/M/D. The tool flags any string that violates these rules with a precise error position.
Examples
P3Y2M10DT2H30M15S
→ Years: 3, Months: 2, Days: 10, Hours: 2, Minutes: 30, Seconds: 15
PT1H30M
→ Hours: 1, Minutes: 30
P1W
→ Weeks: 1 (equivalent to 7 days)
PT0.5S
→ Seconds: 0.5 (500 milliseconds)
FAQ
Why does the same letter M mean two different things?
Before the T separator, M is months (calendar). After it, M is minutes (time). The T separator is mandatory whenever any time component is present, exactly to disambiguate.
Is P1.5Y valid?
Yes — the ISO 8601 amendment permits a fractional value on the last present component. P1.5Y parses as 1.5 years, but cannot be exactly converted to days without a reference date because year length varies.
What does the W form mean?
PnW expresses a duration in weeks only. It cannot be combined with Y, M, D, H, M, or S in the same string per the spec.
Can durations be negative?
Yes — the 2019 revision allows a leading minus sign (-PT1H = "minus one hour"), useful for time-zone offsets and accounting deltas. Some older parsers reject this form.
How do I express "zero duration"?
The canonical form is PT0S. Some tools accept P0D or even bare P, but PT0S is the most widely supported.