KDE PIM/KHolidays/File Format

The KHolidays file format is based on the Plan file format, but has been heavily modified to cater for alternative calendar systems and proper category support. This page documents the basics of this format and the other conventions used in standardising the content of the files. You can use this page to create a new file or to maintain an existing page.

Conventions

Always use the standard template given below
Always complete the file metadata
Always put Public Holidays in the separate section at the top regardless of their other categories (i.e. even if Religious)
Always sort categories into date order
Always include the English name of the holiday in a comment so the maintainers can understand it
Always write dates using month name to remove any ambiguity
Never remove old holidays or change the rule of an existing holiday to only have a new future calculation, as you still need the old holiday rule when calculating holidays for earlier years. Instead modify the year range the old and new calculations apply to. See Advanced Calculations below.

Holiday Region Files

A single holiday file defines all the holidays for an administrative region translated into a language and optionally separated into categories. This is known in KHolidays as a Holiday Region and each file/region is listed separately in the user interface where they can be enabled and disabled separately. This provides a convenient and easy way for organising large groups of holidays.

File Naming

The file name is of the format holiday_$region_$language[_$variant], for example "holiday_es_es" for general holidays in Spain in Spanish or "holiday_es_es_catholic" for Catholic holidays in Spain in Spanish.

The filename is always lowercase
The filename, being unique, is used as the ID for the Holiday Region in KHolidays
The metadata tags in the filename are separated by an underscore "_"
Where the metadata tags require subtags these are separated by a dash "-"
The metadata tags in the filename are used as a fallback if the internal file metadata tags are not populated, otherwise the naming standard is purely for organisational convenience.
The region code is the ISO 3166 Alpha2 code for the administrative region that the holidays in the file apply to and is compulsory. This is usually the country level code such as "es" (Spain) or "us" (USA), but can be a level 2 region code for a state or province such as "es-ca" (Catalonia). Where the file applies at a global level, such as "Catholic Saint's Days", then the region code is "xx"
The language code is the KDE translation code for the language that the file is in, usually the ISO 639 Language code such as "es" (Spanish) or the locale variant of the language such as "en-gb" (British English), or even with the script variant included "sr@latin" (Serbian in Latin script).
The variant code is optional and usually omitted for the default file for an administrative region. Where a particular category has an excessive number of holidays that may not be suitable for the default file, e.g. Name Days) then these can be split into a separate file and named with the category, e.g. "holiday_gr_el_nameday" for Greek Name Days. If the file's internal Name metadata tag is not populated, then the variant code will be used by KHoliday in generating the Name. To ensure this is properly translated you must use one of the pre-defined variant tags, or add the tag and translation to the KHolidayRegion class. Currently supported variant codes are: public, civil, religious, government, financial, cultural, commemorative, historical, school, seasonal, nameday, personal, catholic, protestant, orthodox, jewish, islamic.

File Template

When creating a new holiday file please copy this template and complete all the fields within the square brackets [ ] before adding the holidays under each category heading. See below for an explanation of the categories.

All lines starting with a ":" are comments and are ignored by the parser.

::
:: Country:  [Name]
::
:: Language: [Name]
::
:: Author:   [Name <[email protected]>]
::
:: Updated:  [YYYY-MM-DD]
::
:: Source:   [Source URL 1]
::           [Source URL 2]

:: Metadata
country     "XX"
language    "xx"
:name        "[optional - defaults to country name]"
description "[please add description in source language, e.g. National holiday file for $country]"

:: Public Holidays 

:: Civil

:: Religious

:: Government

:: Financial

:: Commemorative

:: Cultural

:: Historical

:: School

:: Daylight Saving (Winter/Summer Time)

:: Seasons

:: Name Days

File Header

The file header section contains documentation about the file contents:

Country: The name of the country or administrative region the file applies to.
Language: The name of the language the file is translated into.
Author: The name and e-mail address of the author(s) of the file, primarily used for maintenance purposes as the contents of the file may not qualify for copyright.
Updated: Date of last significant update, i.e. when the accuracy of the Public holidays was last verified.
Source: The URL of the source of the data, two sources are preferred of which at least one is preferred to be an official government website, and one is allowed to be Wikipedia, with preferably at least one source in English. Do not use websites that claim to hold copyright over the data.

File Metadata

The File Metadata section contains metadata about the file contents that will be used by the KHolidays library, so must always be completed:

country: Compulsory. The uppercase ISO 4166 alpha 2 code for the administrative region the file contents apply to, usually the country code (e.g. "US") or a level 2 state or provincial code (e.g. "es_CA"). Level 1 country codes are automatically translated by KDE, but new level 2 state codes must have a translation added to KHolidayRegion.
language: Compulsory. The KDE translation code for the language this file is translated into, usually the lowercase ISO 639 alpha 2 code (e.g. "es"), but also the mixed-case locale variant code as well (e.g. "en_GB" or "sr@latin")
name: Optional. If left commented out, then KHolidayRegion::description() will default to the translation for the "country" code and optionally and category variant included in the file name. It is recommended to leave this to the default except for specialised category or global files where the generated default name is incorrect or insufficient.
description: Optional but recommended. Provide a longer description of the file in the language of the file to be returned by KHolidayRegion::description(), for example "National holiday file for Spain" or "Catholic Saint's Days".

Holiday List Section

After the File Metadata comes the holiday rules themselves. A typical rule is of the format:

"[Holiday Name]" [categories] on [calendar] [calculation]

For example:

"New Years Day" public cultural on january 1
"Valentines Day" cultural on february 14
"Easter" religious on easter
"Christmas Day" public religious on december 25
"Eid ul-Fitr" religious on hijri shawwal 1

You must assign at least one category to a holiday, and can assign multiple categories if needed.

The calendar is the calendar system to use in the date calculation, such as Gregorian or Hijri. If omitted then Gregorian is assumed.

Calculations can be a simple day and month, or very complex logical and mathematical expressions, or be relative to other events, or even be shifted to other dates.

For convenience, we organise the list into categories, with each category sorted in date order. All Public Holidays should go in the first section regardless of any other category they may belong to.