The KHolidays library in kdepimlibs provides details on public holidays for a given country and date range. A separate library and file format is required as iCalendar is not capable of expressing recurrence rules for all possible holidays.
To request support for a new country, or to request fixes to existing files, please file a feature request or bug report.
If you wish to write a new file yourself, please follow the instructions for writing a new holiday file.
The following features are available in KHolidays that are not supported in iCalendar:
The file format originally used was the PLAN format, but this has been extended a number of times to support new features. The limits of the format have about been reached and it is too complex for easy maintenance. It is intended to add a few more features to the format then to design a new XML file format to replace it.
The following development plan is designed to become a Freedesktop.org project so that the maintenance burden can be shared with Gnome and any other interested parties.
1 <holiday predefined="christmas" region="GB" type="public,religious"> 2 <observance move-type="both-days" days-off="both-days" language="en_GB">Christmas Day Bank Holiday</observance> 3 </holiday> 4 5 <holiday region=NZ_WN type="public"> 6 <name language="en_NZ">Wellington Anniversary Day</name> 7 <observance calendar="gregorian" month="01" day="22" started="1853" /> 8 </holiday>
1 <?xml version="1.0" encoding="UTF-8"?> 2 <!DOCTYPE holidayCalendar > 3 4 <!-- US Federal Holidays --> 5 6 7 <!-- Federal Holidays in The United States --> 8 <holidayCalendar name="Federal" type="political"> 9 10 11 <-- New Year's Day --> 12 <holiday type="public" workDayOff="true" schoolDayOff="true"> 13 <name>New Year's Day</name> 14 <datespec> 15 <posdate position="fourth" dayOfWeek="thursday" month="11"> 16 <plus days="1"/> 17 </posdate> 18 </datespec> 19 <description>Start of year, marks traditional end of holiday season</description> 20 </holiday> 21 22 </holidayCalendar> 23 24 <?xml version="1.0" encoding="UTF-8"?> 25 <!DOCTYPE features > 26 27 <!-- Maryland State Holidays 28 29 Includes all the federal holidays plus 30 Election Day (even years only) 31 Day After Thanksgiving 32 --> 33 34 <!-- Holidays for the state of Maryland in The United States --> 35 <holidayCalendar name="Maryland" type="political"> 36 <include>UnitedStates/Federal.xml</include> 37 38 <holiday type="public" workDayOff="true" schoolDayOff="true"> 39 <name>Day After Thanksgiving</name> 40 <datespec> 41 <posdate position="fourth" dayOfWeek="thursday" month="11"> 42 <plus days="1"/> 43 </posdate> 44 </datespec> 45 <description>The day after Thanksgiving</description> 46 </holiday> 47 48 <holiday type="public" workDayOff="true" schoolDayOff="true"> 49 <name>Election Day</name> 50 <datespec> 51 <posdate position="first" dayOfWeek="tuesday" month="11"> 52 <yearMod>2</yearMod> <!-- every even year --> 53 </posdate> 54 </datespec> 55 <description>Election Day</description> 56 </holiday> 57 58 </holidayCalendar>
A project to implement a common file format, data repository, and reference libraries for national holiday data. A core goal is to develop a cross-platform community to maintain the Holidays data in a manner similar to the Time Zone database or iso-codes project, and for the data to be available to be used everywhere.
Implementation goals include:
Three forms of the file:
First design resolved format, i.e. what the Qt api will deliver
Key attributes like name, calendar, etc can be overridden in sub-clauses, or derived from first parent, i.e the core recurrence rule entity can fully specify all details required, but where these are common to multiple recurrence rules they can be omitted from the recurrence rule and defined at a holiday or resource level, or even imported
calendar - gregorian - julian - etc
HolidayOccurrence - official name - common name - observance name - occurrence start datetime - occurrence end datetime - observance start datetime - observance end datetime - observance type - isWholeDay - isMultiDay
The master files will be defined in en_US for convenience of maintenance. The format will support optional in-file translated strings for fully-resolved format, or custom non-resolved format, but the master files will only include translations for the the official names for regional files for the languages used in that region. This is to keep the file from bloating and being hard to maintain, and to keep the official local names properly controlled. The master files will use standard .po files and the KDE translation framework for allother languages. The standard English strings will be extracted and translated into all other languages using gettext, but scripting will be provided to generate Qt tr and json format translation files from these. The extraction script will also extract the official names and pre-populate the po files for those languages. The web service may offer the ability to inline all available languages on request, or to serve the required po or json tr file.
Definition of the default master database file hierarchy, designed to minimise duplication. A fully resolved file may contain elements form many of the master files.
Top level directory holds a set of generic holiday rule files named by their primary category. These are common defined date and name rules that are commonly used by many files. For example, Christmas Day, New Years Day, Valentines Day, Easter, etc. These files only hold the default English name. These files can be included into regional files and the rule extended by any local variations, e.g. define if Easter is a public holiday or not.
The regional files are organised by directories by ISO country code, with subdirs for ISO regional codes if there are sufficient regional variations to warrant a separate file. Each country directory may have one or more files for the different primary categories, or a single file if there are only a few holidays and separate files seem over-kill. These files can have official local name translations held in them. It is strongly
Categories: - Official - Civil - Cultural - NameDay - Religious - Catholic - Orthodox - Protestant - Islamic - Jewish Orthodox - Jewish Reform - etc
DaysOff: - PublicDayOff - Implies all other? - GovernmentDayOff - SchoolDayOff - FinancialDayOff
Base file hierarchy: /civil.json /cultural.json /financial.json /catholic.json /protestant.json /orthodox.json /islamic.json /GB/EAW/official.json /GB/EAW/catholic.json /GB/EAW/cultural.json /NZ/civil.json
Including another file makes the other files holidays rules available to be extended, but for the holidays to be included in the fully-realised file must be explicitly extended.
Importing another file causes all the other files rules to be included in the fully-realised file.
JSON cannot have inline comments, but we need to document the rules and sources for the rules in the master files. This will be done via a Source object containing any comments and links required. Shipping this info in the partly or fully resolved files would be wasteful, so the resolving process will strip the Source object out.
School Holidays - Best done with iCal? Are they predictable enough? Maybe only historic and current, no future?
HolidayResource - HolidayEvent - HolidayOccurrence
The HolidayResource is a set of holiday calculation rules The HolidayEvent is the holiday calculation rule The HolidayOccurrence is an actual occurrence of a holiday on an actual date
The HolidayResource can return the set of HolidayEvent active between two dates The HolidayResource can return the set of HolidayOccurrence between two dates for all HolidayEvent in the HolidayResource The HolidayEvent can return the set of HolidayOccurrence between two dates for itself The HolidayOccurrence only knows about itself
Event () QDate dateEnd () const virtual KDateTime dtEnd () const bool hasEndDate () const QLatin1String iconName (const KDateTime &recurrenceId=KDateTime()) const bool isMultiDay (const KDateTime::Spec &spec=KDateTime::Spec()) const QLatin1String mimeType () const virtual void shiftTimes (const KDateTime::Spec &oldSpec, const KDateTime::Spec &newSpec) Transparency transparency () const IncidenceType type () const QByteArray typeStr () const
Incidence () Alarm::List alarms () const QString altDescription () const Attachment::List attachments () const Attachment::List attachments (const QString &mime) const QStringList categories () const QString categoriesStr () const KDateTime created () const QString customStatus () const QString description () const bool descriptionIsRich () const virtual KDateTime endDateForStart (const KDateTime &startDt) const float geoLatitude () const float geoLongitude () const bool hasAltDescription () const bool hasEnabledAlarms () const bool hasGeo () const bool hasRecurrenceId () const QString instanceIdentifier () const bool localOnly () const QString location () const bool locationIsRich () const Alarm::Ptr newAlarm () int priority () const void recreate () Recurrence * recurrence () const KDateTime recurrenceId () const ushort recurrenceType () const virtual void recurrenceUpdated (Recurrence *recurrence) bool recurs () const bool recursAt (const KDateTime &dt) const virtual bool recursOn (const QDate &date, const KDateTime::Spec &timeSpec) const QString relatedTo (RelType relType=RelTypeParent) const void removeAlarm (const Alarm::Ptr &alarm) QStringList resources () const int revision () const QString richDescription () const QString richLocation () const QString richSummary () const QString schedulingID () const Secrecy secrecy () const virtual QList< KDateTime > startDateTimesForDate (const QDate &date, const KDateTime::Spec &timeSpec=KDateTime::LocalZone) const virtual QList< KDateTime > startDateTimesForDateTime (const KDateTime &datetime) const Status status () const QString summary () const bool summaryIsRich () const bool supportsGroupwareCommunication () const bool thisAndFuture () const QString writeAttachmentToTempFile (const Attachment::Ptr &attachment) const
IncidenceBase () bool allDay () const QStringList comments () const QStringList contacts () const virtual KDateTime dtStart () const Duration duration () const bool hasDuration () const
A GSOC 2014 project proposal has been submitted in implement a replacement for KHolidays. This new project will be known as OpenHolidays as a primary aim is to set up a cross-platform data resource. This section documents the background reading required for candidates for this project. If you wish to apply for the project, please subscribe to the firstname.lastname@example.org mailing list and send your initial contact email there with a cc to email@example.com.
A good introduction to the project is the presentation done at the Berlin Desktop Summit in August 2011. (Note the Calendar System implementations details are out of scope for this project).
Next, read through the contents of this wiki page and follow the various links, in particular look through:
One compulsory requirement is to integrate the new QOpenHolidays library into KDE using the Akonadi PIM server in a manner similar to iCalendar files where a base event has a start and end date with recurrence dates able to be queried (KHolidays does not offer such an api).
A major concern is the localization of the files, so you need some understanding of how the KDE localization system works.
It is recommended to get some familiarity with the KDE code development process by submitting some small bug fixes. In this case you could look in Bugzilla for KHolidays data file updates that need to be done.