Technical Spec

Use this only when a webmaster or developer wants to build the file directly.

Field reference

Top-level and entry fields

Start here if you are implementing the file or validating it in your own system.

Open schema-v2.json

Top-level fields

version: Required string. Must be 2.0.
venue_name: Required string for the venue or location name.
venue_url: Required absolute http or https URL for the exact venue.
location_id: Required stable identifier for this venue location on the same host.
last_updated: Required ISO date in YYYY-MM-DD format.
timezone: Optional IANA timezone. Strongly recommended.
specials: Required object containing only happy_hour, daily_deals, late_night, and events.
hpyhr_meta: Optional metadata about how the file was generated.

Entry fields

label: Optional but strongly recommended short title.
days: Optional array of Mon, Tue, Wed, Thu, Fri, Sat, Sun.
date: Optional ISO date for one-off entries, especially events.
expires_on: Optional ISO date for when an entry should stop showing after that day.
all_day: Optional boolean for entries that run for the full business day.
start_time: Optional HH:MM 24-hour start time.
end_time: Optional HH:MM 24-hour end time.
until_close: Optional boolean for entries that run until close.
details: Optional freeform venue wording for the offer or event.
primary_tag: Optional main tag such as wings, trivia, or karaoke.
tags: Optional array of extra tags.
notes: Optional extra note or context.
evidence_url: Required exact proving page or asset URL for this entry.
source_page_title: Required title of the proving page.
proof_type: Required proof type: html, pdf, image, json, or calendar.
observed_at: Required ISO datetime for when the proving content was observed.
content_hash: Required entry-level provenance hash.
delegated_from: Required string. Use an empty string when there is no delegated source.

Validation rules

Hard rules

version, venue_name, venue_url, location_id, last_updated, and specials are required.
last_updated, date, and expires_on must use YYYY-MM-DD.
observed_at must use ISO datetime format.
start_time and end_time must use HH:MM.
end_time cannot appear without start_time.
all_day must be a boolean when present.
Category keys are fixed. Unknown category keys are invalid.
days values must be weekday abbreviations only.
tags must be an array when present.
Every entry must include the required source fields so HPYHR can treat the file as first-party evidence.

Modeling guidance

How to shape the data

Use separate entries when the day pattern or time range changes.
Use days for recurring weekly items.
Use date for one-off events or date-specific items.
Use expires_on when a recurring deal or event should stop showing after a certain date.
Use all_day when the offer runs all business day. Leave the time fields blank.
until_close: true usually means end_time should be blank.
Keep pricing details, caveats, and wording in details.
Use evidence_url for the exact page or asset that supports the entry, not just the venue home page.
Use delegated_from only when the venue page directly links to an off-host source page.
Using both days and date is allowed, but it should be intentional.
Preferred location is yoursite.com/hpyhr.json. On shared chain domains, a same-host location path can be used.

Reference shapes

Document and entry examples

These shapes are short reference examples for people building the file directly.

Top-level object

Document

{
  "version": "2.0",
  "venue_name": "Example Pub",
  "venue_url": "https://examplepub.ca",
  "location_id": "loc_7f3a2c10",
  "last_updated": "2026-03-24",
  "timezone": "America/Vancouver",
  "specials": {
    "happy_hour": [],
    "daily_deals": [],
    "late_night": [],
    "events": []
  },
  "hpyhr_meta": {
    "spec_version": "2.0",
    "generator": "hpyhr.ca",
    "generator_version": "2.0",
    "generated_at": "2026-03-24T20:15:00Z"
  }
}

Entry object

Entry shape

{
  "label": "Spring Taco Feature",
  "days": [
    "Tue"
  ],
  "expires_on": "2026-06-30",
  "all_day": true,
  "details": "Dine-in taco feature available through spring.",
  "primary_tag": "tacos",
  "tags": [
    "seasonal",
    "weekly"
  ],
  "notes": "Optional extra context.",
  "evidence_url": "https://examplepub.ca/features/taco-tuesday",
  "source_page_title": "Tuesday Features",
  "proof_type": "html",
  "observed_at": "2026-03-24T20:15:00Z",
  "content_hash": "hpyhr_4a1d9f7c",
  "delegated_from": ""
}

Sample files

Working examples

Use these examples to compare output or start your own file from something that already works.

Simple venue A small starter file with one entry in each category. Different happy hour by day Separate entries for weekday-specific happy hour timing. Multiple daily deals on one day Multiple Thursday daily-deal entries in one file. Recurring weekly events Weekly trivia, karaoke, and live-music examples. One-off dated events Date-specific event entries for one-time programming. Until close Examples that use `until_close` instead of a fixed end time.

Next step

Check it, then optionally submit it.

Once your file is live, run the quick check and then send us the live URL if you want HPYHR to use this optional venue file.

Open Checker Open Submit Use Generator Instead