Version 6

[minichma]

Now that we're about to release v5, its time to start discussions about v6, starting with those things that didn't make it into v5.

• Separation of Model and Operations (mostly as discussed in Version 5 #606 (comment)
• Use the Ical.Net types for representing the model but use NodaTime types for evaluation.
  I.e. the Ical.Net types have been designed for and are great in representing the ICAL model while NodaTime has been designed for and is great in doing time- and time-zone based calculations, dealing with related ambiguities, etc. The approach would be to have a clean translation layer between the Ical.Net types and NodaTime and then doing the actual calculations in NodaTime.

[axunonb]

Created a new project for iCal v6

[axunonb]

Taking #734 as an example: When parsing we currently have 2 alternatives in case of ambiguities or standard violations: Use a "best guess" or throw. For the "best guess" submitting a warning to a logger (Microsoft.Extensions.Logging.Abstractions) could enhance transparency. What do you think?

[minichma]

When parsing user input, IMHO we should be lenient. If it can be represented by our models, we should accept it (which is why we should probably discard #735). In the evaluation phase we should be more restrictive or maybe make the behavior configurable. But every configuration increases complexity significantly, because all combinations would require testing, which probably is not what we want. So if we want to make the behavior configurable, we should probably only introduce a single config in this respect, something like EvaluationOptions.EvaluationMode = Lenient/Strict.

[axunonb]

Agree with EvaluationOptions.EvaluationMode = Lenient/Strict, where Lenient should be the default. What about introducing a logger that could help for more transparency in Lenient mode?

[minichma]

Yes, a logger could be helpful for debugging. Would it be configured via a global static configuration? We should make sure that it doesn't consume too much if not configured.

[axunonb]

The most unobtrusive implementation is a global static logger factory, that uses a NullLogger (which is a no-op) if not configured. I'll come up with a proposal.

[axunonb]

Further discussion re logging on #838

[maknapp]

Does "use NodaTime types for evaluation" include producing occurrences with NodaTime values?

Occurrence uses CalDateTime (via Period) to define start and end. It is impossible to specify some values with CalDateTime because it does not store the time zone offset. If an occurrence's Start is supposed to be an exact point-in-time, it makes more sense to use ZonedDateTime to represent that. Adding offset to CalDateTime does NOT make sense because it is not in the iCal spec for DTSTART.

Why is Period used in Occurrence? In the iCal spec, it seems that the PERIOD type is supposed to have exact point-in-time values, and the PERIOD type is only used in the FREEBUSY property. Period should use Instant instead of CalDateTime, and Period should not be used by Occurrence at all.

Calendar.GetOccurrences() should be GetOccurrences(Instant start, DateTimeZone tz).TakeWhileBefore(Instant end) instead of using CalDateTime. It would remove any start/end ambiguity and explicitly produce occurrences in a specific time zone.

[minichma]

Does "use NodaTime types for evaluation" include producing occurrences with NodaTime values?

This has indeed been the idea.

Occurrence uses CalDateTime (via Period) to define start and end. It is impossible to specify some values with CalDateTime because it does not store the time zone offset. If an occurrence's Start is supposed to be an exact point-in-time, it makes more sense to use ZonedDateTime to represent that.

Actually the RFC clarifies how to deal with ambiguous and non-existent date/times, so basically it should be possible to represent any recurrence that could be produced by any RRULE (and obviously any other occurrence that is explicitly specified) by CalDateTime without losing any information. This is in contrast to an occurrences end date/time, which could easily be specified as an ambiguous date/time if specified by using the DURATION property (e.g. 20250126T024500 CET + PT30M clearly specifies the 'first' 2:45 on DST change day as start and the 'second' 2:15 as the end). By specifying an occurrence via its start and duration, there shouldn't be any ambiguity. However, using Noda types or our own unambiuous types would certainly be helpful but not perfectly straight forward, as Noda doesen't offer any types that can represent date/time with TZ, date/time without TZ (i.e. floating) as well as date-only. Some additional thoughts are required there. Anyhow, not something for the current v5 as it would probably imply a breaking change.

Why is Period used in Occurrence?

That's probably legacy. I assume it was considered a good fit when introduced because it can represent a start, duration and end, but I agree that is not ideal. Several discussions have emerged around the topic. I agree that it would be good to have a dedicated type for this purpose.

Calendar.GetOccurrences() should be GetOccurrences(Instant start, DateTimeZone tz).TakeWhileBefore(Instant end) instead of using CalDateTime.

Still need to consider the cases date/time without tz, date-only. But for now you have some viable workarounds:

• Instead of filtering for start/end (which is not required anymore in v5), just return all occurrences and filter using your own logic.
• Subtract some grace value from start, like 1 day, that ensures you won't miss any occurrences in case of DST. Afterwards implement your own filtering logic. Note that GetOccurrences() returns a generator, so you don't necessarily need to apply an upper limit, just avoid iterating to the end in case of indefinite sequences.

[maknapp]

Anyhow, not something for the current v5 as it would probably imply a breaking change.

Yes, I was only thinking about v6 changes here. In my opinion, it would be helpful to narrow down CalDateTime usage to plain NodaTime types as much as possible.

Actually the RFC clarifies how to deal with ambiguous and non-existent date/times, so basically it should be possible to represent any recurrence that could be produced by any RRULE (and obviously any other occurrence that is explicitly specified) by CalDateTime without losing any information. This is in contrast to an occurrences end date/time, which could easily be specified as an ambiguous date/time if specified by using the DURATION property (e.g. 20251125T024500 CET + PT30M clearly specifies the 'first' 2:45 on DST change day as start and the 'second' 2:15 as the end).

Creating a CalDateTime using a time zone ID that does not have a constant offset (e.g. America/New_York) will always create on the first hour (due to always using InZoneLeniently for every operation). Using your example, you cannot create an occurrence that starts on the "second" 2:15 that represents the correct time.

// CET is an alias for Europe/Brussels
var a = new CalDateTime(2025, 10, 26, 2, 45, 0, "Europe/Brussels");
var b = a.AddMinutes(30);

Console.WriteLine(a.AsUtc.ToString("yyyy-MM-ddTHH:mm:ssZ", CultureInfo.InvariantCulture));
Console.WriteLine(b.AsUtc.ToString("yyyy-MM-ddTHH:mm:ssZ", CultureInfo.InvariantCulture));

var db = NodaTime.DateTimeZoneProviders.Tzdb;
var aa = new LocalDateTime(2025, 10, 26, 2, 45, 0).InZoneLeniently(db["Europe/Brussels"]);
var bb = aa.PlusMinutes(30);

Console.WriteLine(aa.ToInstant());
Console.WriteLine(bb.ToInstant());

// Result
// 2025-10-26T00:45:00Z
// 2025-10-26T00:15:00Z <-- Wrong, b < a
// 2025-10-26T00:45:00Z
// 2025-10-26T01:15:00Z <-- Correct

By specifying an occurrence via its start and duration, there shouldn't be any ambiguity. However, using Noda types or our own unambiuous types would certainly be helpful but not perfectly straight forward, as Noda doesen't offer any types that can represent date/time with TZ, date/time without TZ (i.e. floating) as well as date-only. Some additional thoughts are required there.

Is an occurrence defined in the spec? All I see are example occurrence times that always include a fixed offset time zone. There is nothing in the spec that I see talking about a floating occurrence or a date-only occurrence. An Occurrence has the Source event with it, and can still be defined via ZonedDateTime start/end while referencing the source event for determining if it is date-only.

Calendar.GetOccurrences() should be GetOccurrences(Instant start, DateTimeZone tz).TakeWhileBefore(Instant end) instead of using CalDateTime.

Still need to consider the cases date/time without tz, date-only.

What does it mean to get occurrences without a time zone? Am I missing some use case where no time zone makes sense? Having just DATE or DATE+TIME does not point to an actual point in time. When I use occurrences, I intend to know the exact point in time that an event will occur. Online calendars like Google and Microsoft all have display settings for time zone because it is needed to know how to calculate occurrences and when an event is starting for the user.

[maknapp]

Linking to #854 for reference.

[axunonb]

@NRG-Drink Are you still on board of ical.net?