Skip to content

Report catalog metadata — options

catalog.json is a flat array today. To show richer info (a report description, headings, etc.) we make it an object with a meta block. The only real decision is where display config lives — on S3 (catalog) or in the app install request (appConfig). Recommendation: Option C (hybrid). Small, backward‑compatible change. Separate MR, not blocking the current one.

The constraint that decides it

  • The sidenav shows each report’s name + icon before the catalog loads → those must stay in appConfig.
  • The report page loads the catalog, so description + column layout can live there.

So the question is only: keep columns/description in the install request, put them on S3, or allow both.

Options

A — Catalog owns it B — appConfig owns it C — Hybrid (recommended)
description / columns in catalog.json in appConfig catalog = default, appConfig = override
name / icon (nav) appConfig appConfig appConfig
Tweak columns without re‑install ✅ ❌ ✅
Per‑control‑room override ❌ ✅ ✅
Duplication low high (per install) low
  • A — one source of truth on S3; simplest mental model. Cost: column layout no longer visible in the install API.
  • B — everything explicit in the install request. Cost: columns/description copied into every install; changing them means re‑installing each control room.
  • C — catalog carries sensible defaults; a specific install can override. Best flexibility for “many control rooms, few report types.”

Shape (Option C)

// catalog.json — defaults travel with the data
{ "meta": {
"description": "Place & trip compliance across checkpoints for the period.",
"columns": [ { "property": "periodStart", "label": "From", "type": "date" }, … ]
},
"reports": [ { "reportId": "…", "reportPath": "…", "periodStart": "…", … } ] }
// appConfig — nav essentials (+ optional overrides)
{ "reportType": "origin-destination",
"title": "Origin-Destination Report",
"icon": "outline:sl-event-pin-distance-fill" }

Resolution in the component: appConfig → catalog.meta → built-in default.

Impact

  • Web component — accept object or array (Array.isArray(data) ? data : data.reports) and render meta.description above the table. Backward‑compatible; the loader page is unchanged.
  • Control Room — no change (nav still reads appConfig).
  • Scripts — --update-catalog writes the object form (create meta once, upsert rows).