Standards compliance by default
Every default in the package follows RFC 5545, RFC 6868 and RFC 7986. Readers reject data that breaks a MUST or MUST NOT rule, and writers refuse to write a model that breaks one. Real-world calendars often break the rules, so each kind of accommodation is a separate option that you turn on by name.
All public types here are in the DataStandardizer.File.iCal namespace.
What the defaults mean
With a default IcalOptions:
- Readers reject non-compliant input.
IcalReader,XcalReaderandJcalReadercheck each calendar against RFC 5545 when they have read it. The first problem throwsIcalFileException, and reading can then continue with the next calendar. - Writers refuse non-compliant models.
IcalWriter,XcalWriterandJcalWritercheck each calendar before they write it. A calendar that breaks a rule throwsIcalFileException, and nothing of that calendar is written. - Line breaks are CRLF, as RFC 5545 §3.1 requires, on every operating system.
For example, a calendar whose DTSTART;TZID=America/New_York:... has no VTIMEZONE for America/New_York is rejected by the reader:
The TZID parameter of the DTSTART property names the time zone 'America/New_York',
which has no VTIMEZONE in the calendar.
and an IcalWriter refuses to write the same calendar with the same message.
The exception’s Data holds where the problem is, under the keys in IcalFileException.DataItemName: ComponentPath, such as VCALENDAR/VEVENT[1], DiagnosticKind, and, where they apply, LineNumber and PropertyName.
One option for each accommodation
Each accommodation for common non-compliant data is a separate property of IcalOptions. All of them default to false. There is no single “lenient mode” switch, so you accept only the problems you expect and still catch the rest.
| Option | What it accepts | Rule it relaxes |
|---|---|---|
AcceptBareLineFeed | A bare line feed as a line break, both to end a line and in a fold. A bare carriage return is never a line break. | RFC 5545 §3.1: lines end with CRLF. |
AllowMissingRequiredProperties | A missing required property or component, such as the UID or DTSTAMP of a VEVENT, or the STANDARD or DAYLIGHT parts of a VTIMEZONE. | The “MUST include” rules of each component. |
AllowCardinalityViolations | A property that may appear once appearing more than once, or two properties that exclude each other both appearing, such as DTEND and DURATION in a VEVENT. A typed accessor reads the first. | The “MUST NOT occur more than once” rules. |
AllowUndefinedTimeZones | A TZID parameter that names a time zone with no VTIMEZONE in the calendar. | RFC 5545 §3.2.19: a VTIMEZONE MUST be specified for each TZID. |
AllowInvalidValues | A value that doesn’t follow the syntax of its value type, or breaks a rule that ties it to its property, a FMTTYPE parameter that isn’t one type and subtype, or a defined parameter that is repeated or has too many values. The value is kept as written, and a typed accessor such as IcalEvent.DtStart throws IcalFileException when it reads it. For a parameter other than FMTTYPE that is repeated or has too many values, a typed accessor uses the first value. | RFC 5545 §3.3, the value rules of each property, the parameter rules of RFC 5545 §3.2 and RFC 7986 §6. |
AllowQuotedParameterValues | A value in double quotes for a parameter whose grammar has no quoted form, such as FMTTYPE="audio/basic". The value is read without its quotes, and IcalWriter writes it back with them. | RFC 5545 §3.2.8 and the other parameter rules of RFC 5545 §3.2 and RFC 7986 §6 that have no quoted-string. |
The same options apply to reading and writing:
var options = new IcalOptions
{
AcceptBareLineFeed = true,
AllowUndefinedTimeZones = true
};
using var reader = new IcalReader("feed.ics", options);
AllowUndefinedTimeZones lets you read such a calendar, but its times still need a time zone. The default resolver reads only the calendar’s own VTIMEZONE components, so add a resolver that fills in the rest. See Time-zone resolution and Read non-compliant feeds.
What is never accepted
Two kinds of problem have no option:
- Component nesting: a component inside one where RFC 5545 doesn’t allow it, such as a VEVENT inside a VTODO.
-
vCalendar 1.0: only iCalendar 2.0 is read. RFC 5545 §3.7.4 allows a
VERSIONmade of registered version identifiers, and the only one is2.0, so the readers acceptVERSION:2.0andVERSION:2.0;2.0and nothing else. Any other value, such asVERSION:1.0,VERSION:2orVERSION:1.0;2.0, throws as soon as it is read:The calendar has VERSION:1.0, but RFC 5545 allows only VERSION:2.0 (or the range 2.0;2.0), since 2.0 is the only iCalendar version it defines. vCalendar 1.0 (VERSION:1.0) is not supported.vCalendar 1.0 differs in more than its version: it has quoted-printable encoding, a different RRULE grammar, and
DALARM,AALARM,TZandDAYLIGHTproperties. To get at the lines of such data, useIcalContentLineReader, which doesn’t checkVERSION.
IcalWriter always writes VERSION:2.0, in place of the calendar’s own VERSION, so it never refuses a calendar for lacking one.
Line breaks and folding
Line breaks never come from Environment.NewLine. A file written on Windows, Linux or macOS is the same. The options that control them are:
| Option | Default | Meaning |
|---|---|---|
LineBreak | "\r\n" | The line break a writer ends each physical line with, including the lines of a fold. RFC 5545 §3.1 requires CRLF. "\n" may be chosen for consumers that expect it. No other value is accepted. |
FoldLength | 75 | The length at which a writer folds lines, in octets of UTF-8, not counting the line break. RFC 5545 §3.1 says lines SHOULD NOT be longer than 75 octets. A fold never splits a character. The minimum is 4. |
FoldWhitespace | ' ' | The character at the start of each continuation line: a space or a horizontal tab, the two that RFC 5545 §3.1 allows. A reader accepts both. |
AcceptBareLineFeed | false | Whether a reader accepts a bare line feed. See above. |
LineBreak, FoldLength and FoldWhitespace are ignored by readers.
The other options aren’t accommodations. Encoding defaults to UTF-8, the default charset of RFC 5545 §3.1.4. MaxLineLength defaults to no limit, because RFC 5545 sets none; set one when you read untrusted data. MaxRecurrenceIterations stops a recurrence rule that can never match.
Checking a model with Validate
IcalComponent.Validate() runs the same checks the readers and writers make, and returns every problem found as a list of IcalDiagnostic, without throwing. Use it on a model built in code, or one read with accommodations on:
foreach (var diagnostic in calendar.Validate())
{
Console.WriteLine($"{diagnostic.Kind}: {diagnostic}");
}
UndefinedTimeZone: VCALENDAR/VEVENT[1] (line 7): The TZID parameter of the DTSTART
property names the time zone 'America/New_York', which has no VTIMEZONE in the calendar.
Each diagnostic has a Kind, a Message, a ComponentPath, the PropertyName at fault if there is one, and the LineNumber it was found on, or 0 for a model not read from a source. Its Kind says which option, if any, accepts it:
IcalDiagnosticKind | Accepted with |
|---|---|
MissingRequiredProperty | AllowMissingRequiredProperties |
CardinalityViolation | AllowCardinalityViolations |
UndefinedTimeZone | AllowUndefinedTimeZones |
InvalidValue | AllowInvalidValues |
QuotedParameterValue | AllowQuotedParameterValues |
InvalidComponentNesting | Never accepted |
UnsupportedVersion | Never accepted |
Whether a TZID names a VTIMEZONE, and whether a VEVENT needs a DTSTART, depend on the calendar, so they are checked only when you validate an IcalCalendar.
What the checks cover
The checks cover the rules of RFC 5545 and RFC 7986 for each component. In summary:
- Required properties and components, such as
UIDandDTSTAMP, at least one component in a VCALENDAR, andDTSTARTin a VEVENT when the calendar has noMETHOD. Pairs that must appear together are checked too, such asDURATIONandREPEATin a VALARM. - Cardinality: properties that may appear at most once, or exactly once, and pairs that exclude each other.
- Value syntax: each value against its value type (RFC 5545 §3.3), including a
VALUEparameter the property doesn’t allow or one it requires, andENCODING=BASE64on inline BINARY values. - Values tied to their property: date-times that must be in UTC, including the
DTSTARTandDTENDof a VFREEBUSY; aDTENDorDUEwith the same value type asDTSTART, in local time if and only ifDTSTARTis, and later in time than it; aRECURRENCE-IDwith the same value type as theDTSTARTof the recurring component with itsUID, and in local time if and only if thatDTSTARTis, when the calendar holds that component;STATUS,TRANSPandCALSCALEvalues from their closed sets, in the components that define them; a duration from a DATE given in days or weeks; recurrence rules checked againstDTSTART, with aUNTILin UTC inside a VTIMEZONE; an observanceDTSTARTgiven as local time; and a VTIMEZONETZIDthat isn’t empty. - Time zones: each
TZIDparameter names a VTIMEZONE in the calendar. - Nesting and version, as above.
Layer 1 doesn’t make these checks. IcalContentLineReader checks only that each line follows the content-line syntax of RFC 5545 §3.1, and its line breaks. See The layered model.