ISO 8601 timestamp support

[mfulton26]

Requirements

I want to enable flags based on the current time in a more human readable format.

"$flagd.timestamp" is a number. A way to do the same using an ISO 8601 string would be more human friendly.

Ideally strings could be supplied with an offset or time zone indicator as well so that I can developers can define times in whatever format works best for them (UTC, US Central Time, etc.).

[toddbaert]

Interesting idea, and I've heard others ask for something similar (cc @jonathannorris )... To support ISO8601 timestamps while maintaining JsonLogic compatibility, I see two main paths:

Conversion operator:

Introduce a single operator (e.g., to_unix or to_timestamp ) to convert ISO8601 strings to Unix timestamps.

Example:

{
  "if": [
    // here, we convert an ISO8601 to a timestamp
    // we could also support dates only, ie: 2026-04-08 
    { ">": [{ "to_timestamp": "2026-04-08T18:50:00Z" }, 1712345678] },
    "on",
    "off"
  ]
}

• Pros: Low implementation overhead; leverages existing numeric operators.
• Cons: Requires explicit conversion in rules.

ISO8601 "sub-type"

Treat ISO8601 strings as a implicit "sub-type" (similar to semver args) with specialized operators like is_before and is_after.

Example:

{
  "if": [
    // here, `is_after` is a special operator that only works with ISO8601 (and probably also unix timestamps).
    { "is_after": [{ "var": "event_timestamp" }, "2026-04-08T18:50:00Z"] },
    "on",
    "off"
  ]
}

• Pros: High semantic clarity
• Cons: High implementation complexity; requires new operators and schema updates, makes old timestamp based approaches somewhat obsolete, has an almost limitless amount of possible operators (why not add is_wednesday? or is_leap_year, etc)

I have a pretty strong preference for the first option. What do you think?

[mfulton26]

The first option is straight forward and seems much simpler to build and maintain. I don't mind a little extra syntax to opt into a date string. Implementing it also doesn't prevent something like the second option from being done in the future if desired as well.

[jonathannorris]

I'm all for making flagd configurations more human readable / understandable.

Ideally all the functions / flagd could just internally try and covert to a timestamp if they get a string... but I understand if that requires too many changes. Then option 1 is probably best.

[alxckn]

Option 1 does seem to be the most logical way to implement this, with less impact on existing implementations. API wise the examples from the rust library could be copied/reused (https://goplasmatic.github.io/datalogic-rs/operators/datetime.html#datetime)?

[toddbaert]

Option 1 does seem to be the most logical way to implement this, with less impact on existing implementations. API wise the examples from the rust library could be copied/reused (https://goplasmatic.github.io/datalogic-rs/operators/datetime.html#datetime)?

I'm not 100% sure what you mean, because I don't see anything in that link that converts a ISO8601 to a timestamp. Do you just mean the form of the operator and validity of inputs? I think I'd like to go a bit beyond that and support ISO8601 dates, and datetimes (this seems to only support datetimes).

I will add that I think for this to work best, we need to make flagd aware of it's timezone. This can be retrieved from the OS, but we might also want to provide an override for it.

[alxckn]

Fair point, I should have been more specific. What caught my eye in that library was mostly the shape of the API which feels aligned with the to_timestamp approach in option 1
Also, the duration concept which could be a useful addition here (e.g. expressing "enable this flag 2 hours after a given timestamp" without having to manually compute the unix value)

I did assume it used unix timestamps under the hood, which looking more closely isn't the case. My bad on the imprecise reference.

Agreed on supporting both dates and datetimes and on timezone awareness, OS default with an override sounds right.

[toddbaert]

Sounds like there's general consensus on the conversion operator approach. This might be a good candidate for an ADR to capture the decision and rationale; we have a number of them already for similar design choices. Anyone here is welcome to open one.

Some things we've identified so far that should be addressed or investigated:

• support both ISO 8601 dates and datetimes
  • specify exactly what time something applies if it's date only... presumably at exactly T00:00:00UTC?
• get TZ offset from the OS by default, but provide an override option
• correctly handle the TZ offset if specified in the input string
• consider edge cases (leap seconds, ambiguous local times during DST transitions, etc)
• investigate consistency of datetime parsing across our key runtimes (.NET, Java, JS, Go, Python)