Skip to main content

​
Dates, Date-Times & Date-Time-Offsets

A date represents a day of the calendar outside of any timezone. A date-time-offset represents an exact point in the time scale, expressed with its offset from Universal Coordinated Time (UTC). A plain (or floating) date-time represents a wall-clock date and time outside of any timezone: it occurs at the same displayed local time, wherever you are.
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, if you forget to send the offset of a date-time-offset, or if you send an offset along with a plain date-time. 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, it indicates the date-time is UTC.
Parse date-time-offsets with an RFC 3339 parser, and don’t compare them as strings. The API may write the same UTC offset as Z or +00:00, and include up to 7 fractional digits of a second: 2023-01-23T12:45:23.1234567+00:00 and 2023-01-23T12:45:23.1234567Z are the same instant.
Time is always 24-hour, i.e. there is no “AM” or “PM” part.
In the OpenAPI specification, each of these types is a string schema identified by its format:
date-time-local is registered in the OpenAPI Format Registry, but it is not defined by the JSON Schema specification, so generic validators ignore it. The corresponding schemas therefore also declare a pattern that rejects any trailing offset.
Most date typed properties are suffixed with “On”, and most date-time typed properties (plain or with offset) 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-31 represents the interval between two dates, outside of any timezone. Here, both the start and end date are included.
  • a date-time-local-range 2023-01-01T00:00:00--2023-01-02T00:00:00 represents the interval between two plain date-times, outside 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:

​
Fractional Seconds

Bounds of date-time-local-ranges and date-time-offset-ranges accept fractional seconds, so a timestamp read from a response (e.g. 2025-01-14T23:08:54.9358662+00:00) can be reused as a bound as is.
The Lucca API handles date-times with a precision of 100 nanoseconds, i.e. 7 fractional digits. A bound with more digits is accepted, but rounded half to even to the nearest 100 ns:
  • …54.93586627 becomes …54.9358663;
  • …54.93586625 becomes …54.9358662, as 2 is even;
  • …54.99999999 carries into the next second and becomes …55.0000000.
The two bounds of a range must differ once rounded: 2023-01-01T00:00:30--2023-01-01T00:00:30.00000001 gets a 400 Bad Request.

​
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. The OpenAPI specification lists the values an enumeration has today. When you validate or deserialize responses against it:
  • Don’t reject an unknown value. Strict validators reject a value that is not in enum: treat it as a warning, or relax response enums before validating.
  • Give generated enums a fallback. Map unknown values to an “unknown” member, or keep the raw string, rather than failing deserialization.
  • Handle the unknown case in your logic. For example, ignore an unknown value in a list, or show it as is.
This applies to enumerations in responses and webhook payloads. Values you send in requests must still be one of the documented values.