ISO 8601 time specification

ISO 8601 - Data elements and interchange formats – Information interchange – Representation of dates and times - prescribes a simple text format for defining durations (periods) and time intervals (start/end or date + duration) including repeating intervals.

In the Global Backend API we use iso8601 formatted strings for periods and intervals for example in the Rights API, the Payment API, and the Service Catalog API.

This page provides a brief overview, parsing instructions, and a couple of examples so that you can get started with the APIs without studying the specification.

Format

Date and time - timestamps

The clients must support all of the following timestamp formats.

FormatExamplesNotes
[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss.sss]Z 2012-09-07T14:17:20.420Z
[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss,sss]Z 2012-09-07T14:17:20,420Z ("," instead of "." on seconds)
[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss.sss]+hh 2012-09-07T14:17:20.420+01
[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss,sss]+hh 2012-09-07T14:17:20,420+01 ("," instead of "." on seconds)
[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss.sss]+hh:mm 2012-09-07T14:17:20.420+01:00
[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss,sss]+hh:mm 2012-09-07T14:17:20,420+01:00 ("," instead of "." on seconds)

Time zones

  • Timestamps can be specified with the time zone UTC, or with an offset from UTC.
  • If timestamp is specified as UTC, add a Z at the end of the timestamp, as in the example below.
  • If you want to specify another timezone than UTC, add +hh:mm or +hh at the end of the timestamp, as in the example below.
  • If neither UTC is explicitly defined with a Z nor offset is defined, the timestamp will be understood as UTC.
Format Examples Notes
[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss.sss]Z 2013-01-01T13:25:10.125Z This is default Coordinated Universal Time (UTC).
[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss.sss]+hh 2013-01-01T13:25:10.125+01 This is a datetime with a 1 hour positive offset, like in Central European Time (CET).
[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss.sss]+hh:mm 2013-07-05T13:25:10.125+02:00 This is a datetime with a 2 hour positive offset, like in Central European Summer Time (CEST).
[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss.sss]-hh:mm 2013-01-01T13:25:10.125-04:30 This is a datetime with a 4 hour and 30 minutes negative offset, like in Venezuela.

Durations (periods)

Format Examples Notes
PnYnMnDTnHnMnS P1Y2M3DT1H2M3S
P1Y
P12M
PT24H
Any elements may be omitted to reduce precision or to mean 0 (Only the leading P and, if specifying time, then also the T separator are required.)
PnW P4W Number of weeks, here: period of four weeks
P<date>T<time> P00010600T120000 Format "PYYYYMMDDThhmmss" or "P[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]". Here: period of 1 year, 6 month, 12 hours.

Time intervals

There are four ways to express a time interval:

  1. <start>/<end>
  2. <start>/<duration>
  3. <duration>/<end>
  4. <duration>
Format Example Notes
start/end 2007-03-01T13:00:00Z/2008-05-11T15:30:00Z
2007-03-01T13:00:00Z/15:301 (*)
start/duration 2007-03-01T13:00:00Z/P1Y2M10DT2H30M Here: Interval of 1 year, 2 months, 10 days, 2 hours and 30 minutes starting at 1pm on 2007-03-01.
duration/end P1Y2M10DT2H30M/2008-05-11T15:30:00Z
duration (+ context info) P100Y Some of our APIs automatically anchor an unbounded period by setting the start date to the moment they were invoked (e.g. rightSpec in the create subscription REST call). Beware that JodaTime likely will fail to parse an unbounded time interval.

(*) If any elements are missing from the end value, they are assumed to be the same as for the start value, so this example could be e.g. a 2.5h meeting.

Repeating (recurring) intervals

(Used e.g. when creating a subscription.)

Format Example Notes
Rnn/interval R5/2008-03-01T13:00:00Z/P1Y2M10DT2H30M Repeat for the given number of times (nn)
R/interval R/2008-03-01T13:00:00Z/P1M Repeat forever (here: infinite monthly subscriptions)

Examples

Durations (periods)

Period example Notes
PT12H 12 hours
P1D 1 day
P7D 7 days
P1M 1 month, i.e. til the corresponding date in the next month (28th Feb + P1M = 28th March)
P31D 31 days - quite different from P1M, which varies between 28 and 31 days w.r.t. month and year
P1Y 1 year, i.e. til the corresponding date in the next year (2012-02-29/P1Y thus ends on 28.2. 2013)
P365D 365 days, which is the same or one day less (in a leap year) than 1Y

Time intervals

Interval example Notes
2011-09-25T00+01/9999-01-01T00+01 "forever" starting 25th Sept 2011
2011-12-09T00+01/2013-01-01T00+01 ~ 2 years

Recurring time intervals

Recurring interval example Notes
R/2011-12-01/P1M Monthly subscriptions renewed until explicitly terminated
R12/2011-12-01/P1M Monthly subscriptions renewed 12 times (one year)
R1/2011-12-01/P10Y Subscription lasting 10 years, without any repetition/renewal

Parsing with Joda-Time

The ISO-formatted intervals and periods may be parsed with Joda-Time using its Instant and/or PeriodFormatter obtained from the ISOPeriodFormat:

import org.joda.time.Interval;
import org.joda.time.chrono.ISOChronology;

public static Interval parse(String intervalString) {
    return new Interval(intervalString, ISOChronology.getInstanceUTC());
}