View as Markdown

Data sources and feeds

How WD, !BankHolidays knows what a bank holiday is.

A feed is a JSON file on the internet that Calendite turns into a named set of dates. That set becomes a category you can add or subtract in any recurrence rule.

Bank holidays are the obvious case, but nothing about it is holiday-specific: anything with dates in it works, from term dates and fixture lists to bin collections and a rota published as JSON.

Data sources are Android only for now. On iOS and web the form appears but can't be saved yet.

Adding one

More → Data sources → + New data source.

  1. Tag name: e.g. Bank Holidays. Feed events get this tag, so they get a colour and show on the calendar.
  2. Category: auto-derived PascalCase and read-only, e.g. BankHolidays. This is what you type in rules.
  3. Tag colour.
  4. URL: e.g. https://www.gov.uk/bank-holidays.json.
  5. JSONPath: where the list of items lives in that document. Type it, or tap Build and click through the fetched document to pick it. For gov.uk that's $['england-and-wales'].events[*].
  6. Calendite fetches after a short pause and reports Found N items with K keys.
  7. Map the keys: which is the title, which is the date, and what format the date is in (ISO, day-month-year, month-day-year, or a Unix timestamp).
  8. Optionally a qualifier field and time fields; see below.
  9. Check the preview rows, then Save.

Using it in a rule

Once saved:

WD, !BankHolidays                every working weekday
BankHolidays                     just the holidays
BankHolidays(Christmas)          one member, matched on its title
Feed(BankHolidays)               the explicit form, same thing
-1__Feed(BankHolidays)__OF__YEAR the last bank holiday of the year

The bare name and the Feed(...) form resolve identically. Use Feed(...) when you also have a tag or event by the same name and want to be unambiguous.

The qualifier field

Some feeds publish two entries for one day that mean different things: gov.uk marks a substitute day with a notes field reading "Substitute day".

Set that key as the qualifier and Calendite keeps those entries distinct instead of merging them. The event then displays as "Boxing Day (Substitute day)".

Merging

Christmas arrives from a bank holidays feed, from a Christian holidays feed, and from a general UK events feed. You want one all-day event on 25 December, not three identical ones stacked on top of each other.

Events from different feeds that describe the same day collapse into one rather than stacking up. Two entries merge when their start date and title both match; those two fields are the whole test. Title matching strips a trailing "Day", so Christmas Day and Christmas merge. Matching goes no further than this: there's no fuzzy matching beyond the trailing "Day", so Christmas and Xmas stay two events, and so do a feed's Christmas and your own Dentist on the same date. The stripping is only for the comparison; the stored title is never rewritten.

When they merge, the second feed's tag is added to the existing event rather than replacing it. That matters for rules: a Christmas that arrived from three feeds is still a member of all three categories, so !BankHolidays still excludes it even though its pill takes the colour of whichever feed got there first.

Whichever feed creates the event owns it. The feed that lands first sets the title and the primary tag (the one the colour comes from). Later feeds contribute only their tag, added to the end of the list. There's no way to give one feed priority over another; it's whichever imported first. Re-running the same feed next year is a no-op: it finds the existing event, adds no second copy and no duplicate tag.

Open the event and you'll see the full list of tags it carries, in order, even though the bar on the calendar is a single colour. See tags, colours and filtering for what an event with several tags means elsewhere in the app.

If two entries on the same day mean different things, use the qualifier field above. A qualifier becomes part of the event's identity: "Boxing Day (Substitute day)" and "Boxing Day" no longer match, so they stay separate events.

Times

Most date feeds are all-day, but if yours carries times, expand Time Field Mapping: start time key, end date key, end time key, duration key. The time pattern is usually auto-detected.

One gap: the end time key is saved but not currently read, so it has no effect.

When feeds refresh

There is no refresh schedule. Feeds re-sync when you save one, and when you bring the app to the foreground. There is no "refresh now" button and no background polling.

That suits a bank-holiday list. For something that changes weekly, you're getting it at app launch, not live.

What isn't supported

  • No .ics subscription. You can't paste a webcal/iCalendar URL. Feeds are JSON only.
  • No file import. There's no "open this .ics" flow.
  • The only calendar import is your device's own: More → Calendar sync. That reads the phone's calendar directly. On iOS it imports only recurring events; one-off events are skipped.

Two things to watch

Category naming is validated loosely. The form only rejects empty names and ones starting with a digit, but the rule parser is stricter: it wants at least one lowercase letter. So UEFA or Sports2024 will save and then produce a rule token the parser rejects. Stick to names like BankHolidays, TermDates, BinCollections.

Feed URLs are stored as plain text in the app's settings, not in your device's secure keychain. Don't put a URL containing a secret token in one.

The JSONPath builder

If you don't want to write a JSONPath, tap Build next to the field. Calendite fetches the document and shows it as an expandable tree: objects, arrays with their length, and leaf types. Click into it, hit Select all items [*] at the array you want, and Use this path.

It emits dot notation, bracket-quoting keys that need it: $['england-and-wales'].events[*].

The builder only offers whole arrays and the first element as a sample; it can't express filters or recursive descent. Those do work if you type them by hand.

Next