Table of Contents

Authoring notable date rules

A notable date is defined by a rule document on the notable-date schema (urn:bodu:globalization:calendar): author it as XML or JSON, then load it into an immutable NotableDateResource with NotableDateResourceLoader. There is no mutable rule-object graph and no rule-provider interface - a rule is a <Rule> element, and a service is built over the loaded resource. This guide covers the document model directly; to assemble the same document fluently in C# instead, see Authoring with the notable-date builder.

This guide walks the document model top to bottom: the <NotableDateResource> root and its child order, how a <NotableDate> concept carries one or more <Rule> recipes, the <Strategy> and <Recurrence> occurrence sources, importing the bundled common catalogues with <Imports>, and ID-targeted edits with <Overrides>. For the full strategy catalogue see Notable-date rule strategies. For the vocabulary it assumes (document vs. resource, concept vs. rule, nominal vs. observed, territory containment) read Core concepts first. For the per-element field reference, see NotableDateRule and adjustment-policy reference.

Rule authoring - authored document loaded into an immutable resource


Document structure

A document is a single <NotableDateResource> element. It declares the schema namespace, a schemaVersion, and a resourceId, and contains its child sections in this order:

Child element Required Purpose
<Metadata> No Name, Description, and zero or more Source provenance entries.
<ResolutionPolicy> No Resource-level duplicate / collision / observed-date policy and the working week.
<AdjustmentPolicies> No Reusable, named adjustment policies referenced by rules via policyRef.
<Imports> No Pulls concepts in from the bundled common catalogues.
<NotableDates> No The locally declared concepts (each with one or more rules).
<Overrides> No ID-targeted AddRule / PatchRule / RemoveRule edits applied at load time.

A minimal document declares a single fixed-date concept:

<?xml version="1.0" encoding="utf-8"?>
<NotableDateResource xmlns="urn:bodu:globalization:calendar" schemaVersion="1.0" resourceId="demo">
  <NotableDates>
    <NotableDate id="new-years-day" displayName="New Year's Day" category="PublicHoliday" defaultNonWorkingDay="true">
      <Rules>
        <Rule id="default">
          <Strategy><Fixed month="January" day="1" /></Strategy>
        </Rule>
      </Rules>
    </NotableDate>
  </NotableDates>
</NotableDateResource>

id values follow the schema's identifier pattern - lowercase, digits, and hyphens (new-years-day, good-friday). resourceId additionally allows dots (data.au, common.global-buddhist).


Concepts and rules

A <NotableDate> is one notable-date concept - an id, a displayName, a default category, and a <Rules> block of one or more <Rule> recipes. Optional concept-level attributes set defaults the rules inherit: defaultNonWorkingDay marks the concept as a closure, and defaultDurationDays gives multi-day events their span.

<NotableDate id="anzac-day" displayName="Anzac Day" category="Remembrance" defaultNonWorkingDay="true">
  <Tags>
    <Tag value="national" />
  </Tags>
  <Rules>
    <Rule id="default">
      <Strategy><Fixed month="April" day="25" /></Strategy>
    </Rule>
  </Rules>
</NotableDate>

A <Rule> is one calculation recipe. Its required id distinguishes it from its siblings under the same concept; the optional attributes (priority, category, nonWorking, durationDays, comment) override the concept defaults for that recipe. A rule contains, in order:

  1. an optional <Applicability> (calendar, year bounds, territory scope);
  2. exactly one <Strategy> (the calculation) or <Recurrence> (a repeating series);
  3. an optional <Duration> (a calculated end date for a multi-day span);
  4. an optional <Tags> block;
  5. an optional <Adjustments> block of policyRef references.
<Rule id="au" priority="100" comment="National; substitute Monday when 26 January falls on a weekend.">
  <Applicability calendar="Gregorian"><Territory code="AU" /></Applicability>
  <Strategy><Fixed month="January" day="26" /></Strategy>
  <Tags><Tag value="national" /></Tags>
  <Adjustments><Adjustment policyRef="weekend-roll" /></Adjustments>
</Rule>

A concept holds several rules when the same date is observed differently across subdivisions or years - for example one Labour-Day rule per Australian state, each scoped to its subdivision and carrying its own <Strategy>. The engine resolves the most-specific rule that applies to the requested territory and year. See NotableDateRule and adjustment-policy reference for every attribute.


The strategy elements

A rule's occurrence source is a <Strategy> child holding exactly one strategy element, each mapping to a public IDateCalculationStrategy. The six most common describe a single date by calendar arithmetic or by reference to another rule:

<Strategy> element What it computes
<Fixed> A specific month + day every year (e.g. 1 January), optionally in a non-Gregorian calendar.
<DayOfWeekInMonth> The nth or last weekday in a month (e.g. fourth Thursday in November).
<WeekdayNearDate> A weekday on / before / after / nearest a fixed reference date (e.g. the Monday on or before 24 May).
<RelativeWeekdayInMonth> A weekday positioned relative to a weekday-in-month anchor (e.g. the Tuesday after the first Monday in November).
<OffsetFromRule> A signed day-offset from another rule's occurrence (e.g. Easter Sunday − 2 = Good Friday).
<Algorithm> Delegated to a named algorithm key for astronomical / ecclesiastical dates (Easter, Vesak, Diwali, …).

A one-line example of each:

<Strategy><Fixed month="January" day="1" /></Strategy>
<Strategy><DayOfWeekInMonth month="11" dayOfWeek="Thursday" weekOrdinal="Fourth" /></Strategy>
<Strategy><WeekdayNearDate month="5" day="24" dayOfWeek="Monday" direction="OnOrBefore" /></Strategy>
<Strategy><RelativeWeekdayInMonth month="11" dayOfWeek="Monday" weekOrdinal="First"
                                  relativeDayOfWeek="Tuesday" direction="After" /></Strategy>
<Strategy><OffsetFromRule notableDateRef="easter-sunday" ruleRef="default" offsetDays="-2" /></Strategy>
<Strategy><Algorithm key="western-easter" /></Strategy>

Alongside these, the schema provides positional strategies (<OrdinalDayOfMonth>, <DayOfYear>, <IsoWeekDate>), dynamic-reference strategies (<WeekdayNearRule>, <NthWeekdayFromRule>), and business-day strategies (<WorkingDayOffsetFromRule>, <WorkingDayInMonth>) that resolve against the working-week and applicable non-working occurrences. A rule may instead declare a <Recurrence> - a repeating cadence (<DailyInterval>, <Weekly>, <MonthlyDay>, <MonthlyWeekday>) that yields many occurrences - and may carry a <Duration> whose end date is either a fixed day count or calculated from a second strategy. The complete catalogue, with a choosing guide and a common-scenarios cookbook, is Notable-date rule strategies.

month accepts either a number (1-12) or an English month name (January). weekOrdinal is a WeekOrdinal value (First…Fifth, Last); direction is a WeekdayProximity value (Before, OnOrBefore, Nearest, OnOrAfter, After). For per-element attribute tables and worked examples see NotableDateRule and adjustment-policy reference; for the <Algorithm> key catalogue and custom algorithms see Date calculation algorithms.


Adjustment policies

A weekend-substitution or "move-to-next-working-day" shift is authored once as a reusable <AdjustmentPolicy> in <AdjustmentPolicies>, then referenced from any rule via <Adjustment policyRef="...">. Adjustments are always referenced by id - there are no inline per-rule adjustment definitions.

<AdjustmentPolicies>
  <AdjustmentPolicy id="weekend-roll" priority="100"
                    description="If the holiday falls on a weekend, observe it on the following Monday.">
    <Trigger type="IfWeekend" />
    <Action type="MoveToNextWorkingDay" skipWeekends="true" skipNonWorkingDates="false" maxSearchDays="7" />
    <Emission mode="ObservedOnly" reason="Substitute public holiday" />
  </AdjustmentPolicy>
</AdjustmentPolicies>

A policy pairs a <Trigger> (when it fires) with an <Action> (what it does) and an <Emission> (whether the actual day, the observed day, or both are emitted), plus an optional <Scope> that limits it to a territory, calendar, category, or year range. A rule opts in by reference:

<Rule id="au">
  <Applicability calendar="Gregorian"><Territory code="AU" /></Applicability>
  <Strategy><Fixed month="January" day="26" /></Strategy>
  <Adjustments><Adjustment policyRef="weekend-roll" /></Adjustments>
</Rule>

The full trigger, action, emission, and scope vocabulary - and the worked weekend-substitution patterns for AU/NZ, the UK, and the US - are covered in Observance adjustment rules and Holiday patterns and examples.


Importing the common catalogues

A regional document rarely starts from scratch. The base package ships a set of common catalogues - global-core, christian-western, global-family, global-remembrance, global-cultural, global-buddhist, global-hindu, and friends - that carry the bare calculation strategy for shared concepts. An <Import> pulls those concepts in; the local document supplies the territory scope, category, non-working flag, and any adjustment.

<Imports>
  <Import resource="global-core">
    <Use notableDateRef="new-years-day" territory="AU">
      <Adjustments><Adjustment policyRef="weekend-roll" /></Adjustments>
    </Use>
  </Import>

  <Import resource="christian-western">
    <Use notableDateRef="good-friday"   territory="AU" />
    <Use notableDateRef="easter-sunday" territory="AU" />
    <Use notableDateRef="easter-monday" territory="AU" />
    <Use notableDateRef="christmas-day" territory="AU">
      <Adjustments><Adjustment policyRef="working-day-substitute" /></Adjustments>
    </Use>
  </Import>
</Imports>

Each <Import resource="..."> names a catalogue. Inside it, a <Use> directive cherry-picks one concept by notableDateRef and may:

  • rename it locally with as,
  • re-scope it to a territory,
  • override the category or nonWorking flag,
  • attach adjustment policies via a nested <Adjustments> block.

An <Import> with no <Use> children imports every concept in the catalogue. When a local concept and an imported concept share an id, the local one wins. The catalogue names accepted by the resolver include default-minimal, global-core, global-all, christian-western, christian-orthodox, global-islamic, global-hindu, global-jewish, global-buddhist, global-cultural, global-remembrance, and the UN / health / science / education / environment / food / family / social families.

Loading a document that imports

<Imports> are resolved by a Func<string,string?> passed to the loader. CommonNotableDateResources exposes that resolver over the bundled catalogues - pass CommonNotableDateResources.Resolver:

using Bodu.Globalization.Calendar;

NotableDateResource resource =
    NotableDateResourceLoader.Load(xml, CommonNotableDateResources.Resolver);
NotableDateService service = new NotableDateService(resource);

A document with no <Imports> loads with the single-argument overload, NotableDateResourceLoader.Load(xml). The companion Bodu.Globalization.Calendar.<Region> data packs are built exactly this way - each region resource imports from the common catalogues and is loaded through the same resolver. See Calendar data packs.


ID-targeted overrides

<Overrides> are edits applied at load time, after imports are resolved, targeted by id. They let a regional document tweak an imported concept without forking it. Three operations are available:

  • <AddRule notableDateRef="..."> wraps a new <Rule> and appends it to an existing concept.
  • <PatchRule notableDateRef="..." ruleRef="..."> replaces parts of an existing rule. The targeting attributes are required; scalar attributes (priority, category, nonWorking, durationDays, comment) patch in place, and a nested <Applicability>, <Strategy>, <Tags>, or <Adjustments> replaces that section wholesale. A patch that replaces the occurrence source carries one <Strategy> or one <Recurrence>, not both: one that carries both, or a strategy or recurrence naming no recognized kind, fails with BODU-CAL-RULE-SOURCE.
  • <RemoveRule notableDateRef="..." ruleRef="..."/> deletes a single rule.
<Overrides>
  <!-- Suppress an imported rule for this consumer … -->
  <RemoveRule notableDateRef="boxing-day" ruleRef="default" />

  <!-- … bump another rule's priority and re-scope it … -->
  <PatchRule notableDateRef="labour-day" ruleRef="default" priority="200">
    <Applicability calendar="Gregorian"><Territory code="AU-VIC" /></Applicability>
  </PatchRule>

  <!-- … and add a company event to an existing concept. -->
  <AddRule notableDateRef="company-founding-day">
    <Rule id="hq">
      <Applicability calendar="Gregorian"><Territory code="AU" /></Applicability>
      <Strategy><Fixed month="June" day="15" /></Strategy>
    </Rule>
  </AddRule>
</Overrides>

Overrides run during loading and produce a normal immutable resource. Runtime change (swapping the rule set after the service is built) is a separate mechanism: load a new resource and hand it to a MutableNotableDateResourceProvider, then resolve through a ReloadableNotableDateService. See Using NotableDateService.


Authoring in JSON

JSON is an equivalent surface for the same document model; the choice is presentation-only. Load it with NotableDateResourceLoader's LoadJson overloads (LoadJson(json), LoadJson(json, resolver), LoadJson(json, resolver, algorithms), LoadJson(Stream)). The element names map directly to JSON property names:

{
  "schemaVersion": "1.0",
  "resourceId": "demo",
  "notableDates": [
    {
      "id": "new-years-day",
      "displayName": "New Year's Day",
      "category": "PublicHoliday",
      "defaultNonWorkingDay": true,
      "rules": [
        {
          "id": "default",
          "strategy": { "fixed": { "month": "January", "day": 1 } }
        }
      ]
    }
  ]
}
using Bodu.Globalization.Calendar;

NotableDateResource resource = NotableDateResourceLoader.LoadJson(json, CommonNotableDateResources.Resolver);

The larger sections map the same way: <AdjustmentPolicies> → adjustmentPolicies, with <Trigger> / <Action> / <Emission> becoming the nested trigger / action / emission objects; <Adjustments> becomes an adjustments array of policy-id strings; and <Imports> becomes imports, each entry a resource plus a uses array:

{
  "schemaVersion": "1.0",
  "resourceId": "data.au",
  "adjustmentPolicies": [
    {
      "id": "weekend-roll",
      "priority": 100,
      "trigger": { "type": "IfWeekend" },
      "action": { "type": "MoveToNextWorkingDay", "maxSearchDays": 7 },
      "emission": { "mode": "ObservedOnly", "reason": "Substitute public holiday" }
    }
  ],
  "imports": [
    {
      "resource": "global-core",
      "uses": [
        { "notableDateRef": "new-years-day", "territory": "AU", "adjustments": ["weekend-roll"] }
      ]
    }
  ],
  "notableDates": [
    {
      "id": "australia-day",
      "displayName": "Australia Day",
      "category": "PublicHoliday",
      "defaultNonWorkingDay": true,
      "rules": [
        {
          "id": "au",
          "applicability": { "calendar": "Gregorian", "territories": ["AU"] },
          "strategy": { "fixed": { "month": "January", "day": 26 } },
          "adjustments": ["weekend-roll"]
        }
      ]
    }
  ]
}

JSON and XML are accepted by separate loader entry points - LoadJson for JSON, Load for XML - and produce identical resources; there is no auto-detection.

A JSON document is not validated against a schema the way an XML document is against the XSD, so a misspelled property name is ignored rather than reported. Its identifiers, references and territory codes are held to the XSD's patterns all the same: "id": "New-Year", a reference "Anchor" or a territory "au" fails with BODU-CAL-SCHEMA, as it does in XML. So does a property the XSD requires that is missing or null (schemaVersion, a concept's displayName, a strategy's month, …), a concept's rules or a weekly recurrence's days that is empty, and an integer outside the XSD's range ("durationDays": 0, a year 70000, an ordinal 0 or "+5"), rather than taking a default; an empty optional list, such as "tags": [], reads as absent. A misspelled value is reported: a field that takes one of a fixed set of names (a category, a policy, a weekday, …) and holds anything else fails with BODU-CAL-ENUM, and a field that takes an integer, a Boolean, a yyyy-MM-dd date or a trigger month and holds text that is not one ("priority": "high", a year-list item "next") fails with BODU-CAL-VALUE, rather than taking the field's default. So does any field that holds a value but holds an object or an array ("priority": {}, "displayName": []), and any property that holds an object or a list but holds a value of another kind ("applicability": 5, "tags": "civic"); the literal null reads as an absent field. A list item is held to the same rules: a number in a list of names ("categories": [1]) fails with BODU-CAL-ENUM, and anything but a string in a list of territory codes, references or tags, or an object or an array in a list of names or years, fails with BODU-CAL-VALUE, rather than being dropped from the list, and so does anything but an object in a list of concepts, rules, adjustment policies, imports, uses or overrides ("notableDates": [5]), rather than being read as an empty object. A message names such a value or item by its JSON kind (object, array, number, …) rather than quoting it. The semantic checks are shared: a rule that declares no recognized strategy or recurrence, or more than one, fails with BODU-CAL-RULE-SOURCE in either format, as does a PatchRule override that replaces the occurrence source with none or more than one, and an untilDate end strategy naming no recognized kind fails with BODU-CAL-DURATION-NOEND (more than one, BODU-CAL-DURATION-CONFLICT). An override's operation is matched ignoring case; one that is missing or names no operation ("Patch") fails with BODU-CAL-ENUM, and an AddRule override without its rule with BODU-CAL-SCHEMA, rather than the override being dropped.

To check a JSON document before loading it, in an editor or a build step, use the companion JSON Schema (draft 2020-12) the library embeds beside the XSD, as the manifest resource Bodu.Globalization.Calendar.NotableDates.schema.json. It describes every member LoadJson reads, mirroring the XSD member for member, its integer bounds and patterns included, so every document that loads in its canonical form passes it. It is stricter than the loader in a few forms the loader also reads: it rejects a property name or an enumeration name in another case, an integer or a Boolean written as a string, a null in place of a value, and a property the loader does not read. In the other direction it accepts two forms the loader rejects, which draft 2020-12 cannot tell from valid values: an integer written with a fraction (1.0) and, unless the validator asserts format, a yyyy-MM-dd date that names no day (2024-02-30).


Year periodicity

Beyond fromYear / toYear bounds, <Applicability> supports a periodicity pair for rules that recur every nth year: everyYears sets the period and anchorYear the reference year it is counted from. A quadrennial civic day active from a known base year is everyYears="4" with anchorYear="2024". They surface on the loaded NotableDateRule's applicability alongside OnlyYears / ExceptYears. See NotableDateRule and adjustment-policy reference.


Validation

Loading parses the document, resolves <Imports>, applies <Overrides>, assembles the concepts, and runs semantic validation. Any error-severity diagnostic throws a NotableDateValidationException; its Diagnostics collection carries every NotableDateValidationDiagnostic (Severity, Code, Message), warnings and informational messages included. A successful Load returns only the resource, so to see the warnings of a document that loads, use TryLoad / TryLoadJson, which return every diagnostic either way:

using Bodu.Globalization.Calendar;

try
{
    NotableDateResource resource = NotableDateResourceLoader.Load(xml, CommonNotableDateResources.Resolver);
}
catch (NotableDateValidationException ex)
{
    foreach (NotableDateValidationDiagnostic d in ex.Diagnostics)
        Console.WriteLine($"{d.Severity} {d.Code}: {d.Message}");
}

Typical errors include a duplicate concept or rule id, an unknown adjustment policyRef, an unknown <Algorithm> key, an impossible fixed date, or a fromYear after toYear.


Where to go next