Dates, Date-Times & Date-Time-Offsets
A date-time represents a point in the time scale outside of any timezone. A date without time represents a day of the calendar outside of any timezone. A date-time-offset represents a point in the time scale based on Universal Coordinated Time (UTC).Please note that the Lucca API enforces strong validation of each type. You may receive an error when trying to send a date in place of a date-time, or if you forget to send the offset of a date-time-offset. Default values are disabled in order to avoid unexpected side-effects.
The
Z
character in the time-offset
part of the string is equivalent to a +00:00
timezone offset. In other words, in indicates the date-time is UTC.Time is always 24-hour, i.e. there is no “AM” or “PM” part.
Type | Description | ABNF | Example |
---|---|---|---|
Date | Date of a day. | full-date | 2023-01-01 |
Date-Time (Local) | Timezoned date and time. | full-time | 2023-01-01T09:45:23.0001Z :br 2023-01-01T07:45:23.0001+02:00 |
Date-Time (Floating) | Date-time value that isn’t tied to a specific time zone. It’s occurs at the same displayed local time, wherever you are. | ||
Time (Local) | Timezoned time value. | full-time | 07:30Z |
Time (Floating) | Time value that isn’t tied to a specific time zone (e.g: the time of your alarm clock). | partial-time | 07:30 |
Most date typed properties are suffixed with “On”, and most date-time typed properties with “At”. For example:
(date-time) createdAt
, (date) occursOn
, etc…Date Ranges
Date ranges are most often used in query parameters in order to filter out results based on a
date attribute value being comprised in a given range.
- a date-range
2023-01-01--2023-01-31
represents the interval between two dates, outside of any timezone. Here, both the start and end date are included. - a date-time-range
2023-01-01T00:00:00--2023-01-02T00:00:00
represents the interval between two points in the time scale, oustide of any timezone. Here, the end date is NOT included. - a date-time-offset-range
2023-01-01T00:00:00+02:00--2023-01-02T00:00:00+02:00
represents the interval between two points in the time scale, defined in reference to UTC. Here, the end date is NOT included.
In the spec, dates can be separated with the ”/” (slash) character, but this could break URLs when serializing ranges as query parameters values
?date=2023-01-01/2023-01-31
, so the Lucca API does not officially support it. Besides, the Lucca API does not support ranges defined as a date and a duration either.".."
characters:
..--2023-01-01
: until Jan. 1st 2023 ;2023-01-01--..
: since Jan. 1st 2023.
Durations (time intervals)
A duration represents the length of the interval between two points in the time scale. Duration ISO value Same as with dates and date-times, durations (or time intervals) also conform to the ISO 8601 standard, whose ABNF grammar is:P2DT12H30M23S
indicates “2 days, 12 hours, 30 minutes and 23 seconds”.
Durations can be negative, in which case it is prefixed with a ”-” (hyphen) character.
- as a number of hours,
- or as a fraction of days.
If you only need to display a work-duration, then you can simply use the
value
property, followed by the unit
. But if calculations are needed, it is recommended to parse the iso
property, as the value
can be subject to rounding (e.g. “1h20” gives a decimal value of “1.3333…”).