Data Types & Formating
The Lucca API normalizes the formating of some data types.
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.
Dates and date-times are formatted according to the ISO 8601 and RFC 3339 standards, whose ABNF grammar is the following:
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.
Depending on the type of date, there can be:
- a date-range
2023-01-01--2023-01-31represents 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:00represents 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:00represents the interval between two points in the time scale, defined in reference to UTC. Here, the end date is NOT included.
In conformance with ISO 8601, a date range can be serialized as a single string that contains both dates, separated by the ”—” characters.
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.
Open-handed ranges can be defined with the ".." characters:
..--2023-01-01: until Jan. 1st 2023 ;2023-01-01--..: since Jan. 1st 2023.
The ABNF grammar for such ranges is:
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:
For example, 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.
Unit & Value
In time management, work durations are often handled either:
- as a number of hours,
- or as a fraction of days.
For instance, in France, some managers don’t have their work duration expressed in hours, but rather in a number of days. Another example would be consultants working on projects for their clients: often, the company tracks their times as a fraction of days rather than as a number of hours, in order to make billing easier (they bill by the day rather than by the hour).
This is why work-durations are more complex objects than a simple ISO string:
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…”).
Enumerations
In the Lucca API, enumerations are string typed, non-nullable, and must be considered extensible.
You should be aware of the extensible nature of all enumerations. It means that adding a new value to an existing enumeration is not considered a breaking change in the Lucca API. Therefore, your code should prepare for it.