XML Holidays

Description

What the project is for

The xml-holidays project suggests an XML document type for expressing international holidays. The project also supports both current and historic holiday definitions for many countries actually.

What is out of the scope of this project?

This project concentrates on a holiday xml standard and the actual data definitions for holidays on this planet. This suggested standard should be independent of any programming language. Therefore an actual software implementation that parses xml data is out of the scope of this project.

Are there actual implementations that can process xml holidays data?

The free project called NumericalChameleon (a FOSS unit converter written in Java, released under the terms of the GPL) is able to read and understand xml holidays data. See also http://numericalchameleon.net

Examples

Celebrated on a fixed day

Example: on January 1

In many countries the New Year's day is always celebrated on January 1, each year.

<holiday>
<descriptionlanguage="en"name="New Year's Day"/>
<descriptionlanguage="de"name="Neujahrstag"/>
<definition>
<fixedday="1"month="January"/>
</definition>
</holiday>

Celebrated on a date that is dependent on Easter

Example: two days before Easter Sunday

Easter is celebrated always on a Sunday. Good Friday is celebrated two days before Easter. Simply use the easter tag at first and subtract two days from it (add -2).

<holiday>
<descriptionlanguage="en"name="Good Friday"/>
<descriptionlanguage="de"name="Karfreitag"/>
<definition>
<easter/>
<adddays="-2"/>
</definition>
</holiday>

Celebrated on the nth weekday in a particular month

Example: on the second Sunday in May

In the USA, Mother's Day is celebrated on the second Sunday in May. The holiday was declared officially by some states beginning in 1912.

<!-- http://en.wikipedia.org/wiki/Mother%27s_Day -->
<holiday>
<descriptionlanguage="en"name="Mother's Day"/>
<definitionfirstyear="1912">
<rulenth="2nd"weekday="Sunday"month="May"/>
</definition>
</holiday>

Celebrated on a date that is dependent on a weekday

Example: on October 12 with dependencies on a weekday

In Argentina Columbus Day (Día de la Raza) is celebrated on October 12, but if the date falls on a Tuesday or Wednesday, the holiday is the preceding Monday. If it falls on a Thursday or on a Friday then the holiday is the following Monday.

<holiday>
<descriptionlanguage="es"name="Día de la Raza"type="public holiday"/>
<descriptionlanguage="en"name="Columbus Day"type="public holiday"/>
<definitionfirstyear="1917">
<fixedday="12"month="October"/>
<!-- If the date falls on a Tuesday or Wednesday, the holiday is the preceding Monday.-->
<conditionifweekday="Tuesday">
<adddays="-1"/> <!-- can become the preceding Monday -->
</condition>
<conditionifweekday="Wednesday">
<adddays="-2"/> <!-- can become the preceding Monday -->
</condition>
<!-- If it falls on a Thursday or a Friday then the holiday is the following Monday.-->
<conditionifweekday="Thursday">
<adddays="+4"/> <!-- can become the following Monday -->
</condition>
<conditionifweekday="Friday">
<adddays="+3"/> <!-- can become the following Monday -->
</condition>
</definition>
</holiday>

Celebrated on the nth weekday in a particular month and on a fixed day in the past

Example: on the third Monday in February and on February 22 until 1970

As the first federal holiday to honor an American citizen, Washington's Birthday was celebrated on Washington's actual birthday, February 22. In 1971 it was shifted to the third Monday in February. So actually you need two definition blocks in order to define the Washington's birthday holiday correctly.

<!-- http://en.wikipedia.org/wiki/Washington%27s_Birthday George Washington (February 22, 1732 – December 14, 1799)-->
<holiday>
<descriptionlanguage="en"name="Washington's Birthday (President's Day)"type="federal holiday"/>
<!-- Titled Washington's Birthday, the federal holiday was originally implemented by the United States federal government in 1880 for government offices in the District of Columbia (20 Stat. 277) and expanded in 1885 to include all federal offices (23 Stat. 516). -->
<definitionfirstyear="1885"lastyear="1970">
<fixedday="22"month="February"/>
</definition>
<!-- On January 1, 1971 the federal holiday was shifted to the third Monday in February by the Uniform Monday Holiday Act. -->
<definitionfirstyear="1971">
<rulenth="3rd"weekday="Monday"month="February"/>
</definition>
</holiday>

Celebrated on a particular weekday of the nth full week of a particular month

Example: on the Tuesday of the first full week of May

Since 1986 the National Teacher Day is celebrated on Tuesday of the first full week of May. In the US, the week begins with Sunday, therefore the first full week begins with the first Sunday in May. If you add two days, you get Tuesday.

<holiday>
<descriptionlanguage="en"name="National Teacher Day"/>
<!-- ... -->
<definitionfirstyear="1986">
<rulenth="1st"weekday="Sunday"month="May"/>
<adddays="+2"/> <!-- will become Tuesday -->
</definition>
</holiday>

Example: on the Wednesday of the last full week of April

The National Secretaries Day is observed on the Wednesday of the last full week of April. In the US, the week begins with Sunday and it ends with Saturday. The last full week is therefore the week which ends with Saturday (the last Saturday in April). In order to get the Wednesday of the last full week of April, simply subtract three days.

<holiday>
<descriptionlanguage="en"name="National Secretaries Day"/>
<!-- ... -->
<definitionfirstyear="1955"lastyear="1980">
<rulenth="Last"weekday="Saturday"month="April"/>
<adddays="-3"/> <!-- this is Wednesday -->
</definition>
</holiday>

Celebrated on a particular weekday nearest a particular date

Example: on Monday nearest July 1st

In the Canadian provinces Newfoundland and Labrador, the Memorial Day is observed on the Monday nearest July 1st. Set the fixed date (July 1) and use the goto-direction called "nearest". The definition:

<holiday>
<descriptionlanguage="en"name="Memorial Day"region="Newfoundland and Labrador"/>
<definition>
<!-- it is celebrated on the Monday nearest July 1st -->
<fixedday="1"month="July"/>
<gotoweekday="Monday"direction="nearest"/>
</definition>
</holiday>

Celebrated in a different calendar system

Example: Hebrew Calendar: Fast of Esther in Israel

In Israel the Fast of Esther is observed on the 13th day of the Hebrew month of Adar. So we need to specify the hebrew calendar for the definition.

 <holiday>
<descriptionlanguage="he"name="תַּעֲנִית אֶסְתֵּר"type="Jewish holiday"/>
<descriptionlanguage="en"name="Fast of Esther"type="Jewish holiday"/>
<descriptionlanguage="de"name="Ta’anit Esther"type="Jewish holiday"/>
<definition>
<!-- The fast is observed on the 13th day of the Hebrew month of Adar --><!-- When the year has two Adar months, it is observed only in the second Adar -->
<fixedcalendar="hebrew"day="13"month="Adar"/>
<conditioncalendar="hebrew"ifweekday="Shabbat">
<!--If the date of the Fast of Esther falls on Shabbat (Saturday), the fast is instead observed on the preceding Thursday -->
<addcalendar="hebrew"days="-2"/>
</condition>
</definition>
</holiday>

Seasons: a day dependent on Solstice or Equinox

Example: the Solstice in June in Germany

In June 2008 the Solstice was on June 20 at 23:59 UTC (24 h system). This was the begin of summer for people living in the northern hemisphere and it was the start of winter for people living in the southern hemisphere. In Germany's caldendars, you find June 21, 2008 for the Solstice. This is because of the timezone difference of 2 hours from UTC. For the Europe/Berlin timezone the actual Solstice was on June 21, 2008 at 1:59 (24 h system). As the actual day of the Solstice (or Equinox) is dependent on the timezone in a country, you can specify it with the parameter called timezone.

<holiday>
<descriptionlanguage="de"name="Sommeranfang (Sommersonnenwende)"/>
<descriptionlanguage="en"name="Solstice June"/>
<definition>
<solsticetype="June"timezone="Europe/Berlin"/>
</definition>
</holiday>