feat(competitions): schema, 50-record dataset, contributing guide

[AnayDhawan]

Competitions is StudyMap's second data vertical after places. This issue lands the data layer: a JSON Schema, 50 curated records, and the human-facing contributing guide. Everything else in the competitions label depends on it.

The places dataset is the precedent and we follow it exactly: JSON arrays on disk, a draft-07 schema, a zero-dependency validator in CI, and a static ESM import so the whole dataset bundles at build time.

Files to add

• data/competitions/<category>.json - one file per category, mirroring data/places/<type>.json. Root value is a JSON array.
• data/competitions.schema.json - modelled directly on data/places.schema.json.
• data/competitions/CONTRIBUTING.md - mirroring data/CONTRIBUTING.md.
• .github/ISSUE_TEMPLATE/add-competition.yml - mirroring .github/ISSUE_TEMPLATE/add-place.yml.

Record shape

{
  "id": "breakthrough-junior-challenge",
  "name": "Breakthrough Junior Challenge",
  "organizer": "Breakthrough Prize Foundation",
  "organizer_url": "https://breakthroughjuniorchallenge.org",
  "category": "stem",
  "subjects": ["physics", "science communication"],
  "description": "One to three sentences, written by us.",
  "format": "online",
  "age_min": 13,
  "age_max": 18,
  "participation": "individual",
  "region": "international",
  "fee": { "amount": 0, "currency": "USD" },
  "prize": "USD 250,000 scholarship plus a lab grant",
  "official_url": "https://breakthroughjuniorchallenge.org",
  "cycle_year": 2026,
  "dates": [
    {
      "label": "Submission deadline",
      "date": "2026-06-25",
      "type": "deadline",
      "timezone": "UTC-4",
      "estimated": false,
      "source_url": "https://breakthroughjuniorchallenge.org/rules"
    }
  ],
  "country_tracks": [
    {
      "country": "IN",
      "official_url": "https://www.iarcs.org.in/",
      "stages": [
        { "name": "ZIO", "date": "2026-11-15", "estimated": false, "source_url": "https://www.iarcs.org.in/" }
      ]
    }
  ],
  "added_by": "github-username",
  "verified": { "by": "github-username", "on": "2026-09-05" },
  "valid_till": "2027-09-05"
}

Enums:

• category: stem | mathematics | coding | essay_writing | creative_writing | arts_design | film_video | business | finance | humanities | history | debate_mun | research | scholarship | interdisciplinary
• format: online | in_person | hybrid
• participation: individual | team | individual_or_team
• region: international, or an ISO-3166 alpha-2 code
• dates[].type: registration_open | registration_close | deadline | round | results | ceremony
• country_tracks[].country: one of IN US GB CA AU SG DE FR CN JP KR BR ZA

Carry two conventions over from data/places.schema.json: "format": "date" for every ISO date string, and the verified: { by, on } sub-object with additionalProperties: false.

source_url and timezone are required, not decorative

A countdown timer is a precision claim. It renders a wrong date as confidently as a right one, and a student who misses a scholarship because our clock was stale does not come back. Every date carries the URL it was read from so the next person can recheck it in one click, and valid_till plus the freshness cron is what stops the catalog rotting.

Content sourcing rules

Take facts only: names, organizers, dates, fees, eligibility, age ranges, prizes, official URLs. Facts are not copyrightable.

Write every description fresh. Do not copy prose from doq.world or any other catalog. Their write-ups are their own work, this repo is public, and a lift would be visible in git history forever. One to three sentences, plain, no marketing register.

Do not import anyone else's prestige or selectivity rating. We are not making that editorial call.

The 50 records

All global, with per-country qualifier tracks where a real national pathway exists. Aim for spread across categories rather than 30 essay contests. Marquee names worth including: IMO/IOI national feeders, HMMT, Meta Hacker Cup, Breakthrough Junior Challenge, Foyle Young Poets, Bow Seat Ocean Awareness, Regeneron ISEF, Google Science Fair successors, John Locke, Harvard Crimson Global Essay, Diamond Challenge, Conrad Challenge, NASA Space Apps, F1 in Schools.

country_tracks is where the real value is and it is the part no other catalog has in machine-readable form. Example: an informatics olympiad's entry gets India's ZIO/ZCO/INOI pathway with iarcs.org.in, the US's USACO pathway, the UK's BIO pathway, and so on for whichever of the 13 have a national body.

Acceptance criteria

• 50 records validate against the schema with npm run validate (once #N2 lands)
• Every id is globally unique across all category files
• Every date entry has a source_url that resolves
• No description is copied from another site
• No em dashes anywhere in the data (CI enforces this; see scripts/validate-places.mjs:145-149)
• At least 20 records carry at least one country_tracks entry
• data/competitions/CONTRIBUTING.md documents the id convention, the sourcing rules, and the verification expiry window

[yakew7]

Implemented in fbfd14f.

• data/competitions.schema.json: draft-07 schema modeled directly on data/places.schema.json, with the full field set from the issue (organizer/organizer_url, category enum, subjects, format, age_min/age_max, participation, region, fee, dates[] with type/timezone/estimated/source_url, country_tracks[] restricted to the 13-country enum, verified, valid_till).
• data/competitions/.json: 50 records across all 15 categories (stem 9, mathematics 4, coding 4, essay_writing 4, creative_writing 3, arts_design 5, film_video 1, business 4, finance 4, humanities 2, history 3, debate_mun 3, research 1, scholarship 1, interdisciplinary 2).
• Facts (organizer, dates, fees, eligibility, prizes, official URLs) sourced from doq.world's embedded per-competition data plus the organizers' own official sites; every description was written fresh, no prose copied from doq.world or anywhere else.
• 20 of the 50 records carry at least one country_tracks entry with a real national qualifying pathway (e.g. India's ZIO/ZCO/INOI via iarcs.org.in for informatics, INMO/INPhO/INChO/INBO/INAO via HBCSE, USACO, British Physics/Biology/Informatics Olympiads, NHD China/Korea affiliates, WRO India, FIRST Robotics Canada/Australia, DECA Canada, World Scholar's Cup Gurgaon/Singapore rounds, and more).
• Every date's source_url was verified to resolve with a live GET request; two organizers (MAA/USAMO and the JFK Library) block automated requests site-wide, so those two date entries cite a Wayback Machine snapshot instead of the live page (flagged for a manual look).
• No em dashes anywhere in the new data or docs (checked with grep).
• data/competitions/CONTRIBUTING.md and .github/ISSUE_TEMPLATE/add-competition.yml mirror the places equivalents, documenting the id convention, sourcing rules, and a 6-month verification window (shorter than places' 12 months, since competition dates go stale faster).

npm run validate (places), typecheck, and prettier all pass. The competitions validator/CI wiring is #194's job, so this issue only adds the data layer per its own scope.