Model catalogue

models.json is the machine-readable declaration of which models exist in the dataset. Its zod authority is modelCatalogueSchema from windgram/contract; provider evidence lives in the dated forecast feed reference.

Entry structure

Group	Fields	Consumer use
Identity	slug, label, provider	Path identity and reader-facing label
Schedule	stepHours, horizonHours, runIntervalHours	Time sampling, horizon, and expected publication cadence
Grid	gridKm	Declared horizontal resolution
Lifecycle	experimental, optional sunset	Availability context and machine-readable retirement
Kind	deterministic or ensemble	Document interpretation without a named-model branch
Capabilities	levels, omega provenance, heat fluxes, gust/precipitation semantics, convection, PBL and cloud fields	Honest feature presence and labels

stepHours declares the finest published step, not a whole-horizon promise: NAM drops from hourly to three-hourly output after 36 hours and GEPS from three-hourly to six-hourly after 192 hours. The dated forecast feed reference records each model’s full cadence.

Discover models from the catalogue

read-models.ts

import { parseModelCatalogueJson } from "windgram/contract";

export function modelLabels(text: string): string[] {
  const catalogue = parseModelCatalogueJson(text);
  if (!catalogue) throw new Error("unsupported model catalogue");

  return catalogue.models.map(
    (model) => `${model.slug}: ${model.label} (${model.capabilities.gust})`,
  );
}

Non-profile datasets discover separately: the optional smokeModels array lists smoke-document models (RAQDPS today) with the same identity and cadence metadata but no profile capabilities. It is deliberately not part of models — a capabilities-less entry there would fail every already-deployed catalogue guard, while an unknown top-level key is stripped harmlessly. Absence of the array means the catalogue predates smoke documents; see the smoke document reference. The optional observationModels array follows the same compatibility logic for observation datasets (GOES-18 DSR and AOD today): identity, gridKm, and a cadenceMinutes freshness yardstick in place of run scheduling — see the observation document reference.

A new catalogue entry is not a package enum change.

Site context beside the catalogues

site-context.json is the third catalogue-root file, published at the dataset root beside models.json and sites.json: static, machine-generated terrain and land-cover context for every catalogued site. Fetch it once, guard it with parseSiteContextJson, and join its entries against sites.json by slug — it echoes no coordinates or surveyed elevations of its own. It has no cadence and no runs; it changes only when the site catalogue does. Its shape, sources, and licences live in the site context reference.

Absence and semantics are declarations

Capability booleans state whether a family exists. Gust and precipitation go further by declaring meaning: readers must not label two different windows as the same measurement. Vertical velocity declares both provenance and the subset of levels that carries it.

Render the declaration. Do not infer features from the provider, grid size, kind, slug, or another model in the same family. See Model capabilities for the reading consequences and Choose models for task-oriented selection.