Report YAML Reference

Field-level specification for Report YAML definitions (reports/report_*.yaml).

File Convention

• Location: reports/report_*.yaml
• report_id must match the filename stem (e.g. report_executive_summary.yaml requires report_id: report_executive_summary)
• Compiles to per-report data models, a union view, and a registry table
• Validator: python3 scripts/reportcheck.py
• Compiler: python3 scripts/reportcompile.py

Top-Level Fields

Field	Type	Required	Description
report_id	string	Yes	Must match filename stem
version	string	Yes	Version string (e.g. "1")
title	i18n mapping	Yes	Report title (en/de/fr required)
description	i18n mapping	Yes	Report description (en/de/fr required)
audience	list of strings	No	Target audience roles (e.g. [cfo, coo])
page	mapping	No	See Page
sections	list	Yes	Non-empty list of sections. Section id values must be unique. See Sections

All i18n fields are mappings with keys en, de, fr (all three required).

Page

Field	Type	Required	Default	Valid Values
orientation	string	No	portrait	portrait, landscape
size	string	No	A4	A4, A3, letter

Sections

Every section has these common fields:

Field	Type	Required	Description
id	string	Yes	Unique section identifier within the report
type	string	Yes	See Section Types
title	i18n mapping	No	Section title. Must be i18n if present

Section Types

Type	Required Fields	Description
kpi_grid	items	Grid of KPI cards. Optional columns (integer, default 4)
callout	items	Highlighted metric cards. Optional columns (integer)
severity_bar	query	Stacked bar showing severity distribution
table	query	Data table with optional column definitions
text	content	Static text block (i18n mapping, en/de/fr required)
footer	text	Footer text block (i18n mapping, en/de/fr required)
chart_bar	query	Bar chart from query results
chart_trend	query	Trend/line chart from query results

Items (for kpi_grid and callout)

Field	Type	Required	Description
label	i18n mapping	Yes	Display label (en/de/fr required)
query	string	Yes	SQL query returning a single value column
format	string	No	See Valid Formats. Default: number

Query Field (for severity_bar, table, chart_bar, chart_trend)

A SQL string. Supports template helpers:

Template	Resolves to	Example
{{ gold('entity') }}	{{ ref('gold_entity') }}	{{ gold('shipments') }}
{{ silver('entity') }}	{{ ref('silver_entity') }}	{{ silver('cases') }}
{{ ref('model') }}	Pass-through dbt ref	{{ ref('probe_findings') }}
{{ tenant_id }}	{{ var("tenant_id") }}	Used in WHERE clauses

Severity Bar Query

Must return columns: high, medium, low, total (all integers).

Columns (for table)

Optional. When provided, controls column display.

Field	Type	Required	Description
field	string	Yes	Column name from query result
label	i18n mapping	Yes	Display header (en/de/fr required)
width	integer (1-12)	No	Grid width
align	string	No	left, center, or right
format	string	No	See Valid Formats

Valid Formats

number, chf, chf_compact, percent, date, text

Example

report_id: report_executive_summary
version: "1"
title:
  en: "Executive Summary"
  de: "Zusammenfassung"
  fr: "Resume executif"
description:
  en: "High-level overview of analytical findings and financial exposure."
  de: "Ueberblick ueber analytische Befunde und finanzielle Exposition."
  fr: "Vue d'ensemble des resultats analytiques et de l'exposition financiere."

audience: [cfo, coo]

page:
  orientation: portrait
  size: A4

sections:
  - id: kpi_grid
    type: kpi_grid
    title:
      en: "Key Metrics"
      de: "Kennzahlen"
      fr: "Indicateurs cles"
    columns: 4
    items:
      - label: { en: "Total Cases", de: "Faelle gesamt", fr: "Cas totaux" }
        query: "SELECT count(*) as value FROM {{ gold('cases') }}"
        format: number
      - label: { en: "Total Billing", de: "Umsatz gesamt", fr: "Facturation totale" }
        query: "SELECT coalesce(sum(amount), 0) as value FROM {{ gold('billing_events') }}"
        format: chf_compact
      - label: { en: "Findings", de: "Befunde", fr: "Resultats" }
        query: "SELECT count(*) as value FROM {{ ref('probe_findings') }}"
        format: number
      - label: { en: "Confirmed Theses", de: "Bestaetigte Hypothesen", fr: "Theses confirmees" }
        query: "SELECT count(*) as value FROM {{ ref('hypothesis_verdicts') }} WHERE status = 'confirmed'"
        format: number

  - id: severity_distribution
    type: severity_bar
    title:
      en: "Finding Severity Distribution"
      de: "Befund-Schweregrad-Verteilung"
      fr: "Distribution de gravite des resultats"
    query: >
      SELECT
        count(*) FILTER (WHERE severity = 'high') as high,
        count(*) FILTER (WHERE severity = 'medium') as medium,
        count(*) FILTER (WHERE severity = 'low') as low,
        count(*) as total
      FROM {{ ref('probe_findings') }}

  - id: top_findings
    type: table
    title:
      en: "Top Findings by Risk"
      de: "Top-Befunde nach Risiko"
      fr: "Principaux resultats par risque"
    query: >
      SELECT probe_id, severity, money_at_risk
      FROM {{ ref('probe_findings') }}
      ORDER BY money_at_risk DESC
      LIMIT 10
    columns:
      - field: probe_id
        label: { en: "Signal", de: "Signal", fr: "Sonde" }
        width: 4
      - field: severity
        label: { en: "Severity", de: "Schweregrad", fr: "Gravite" }
        width: 2
      - field: money_at_risk
        label: { en: "CHF at Risk", de: "CHF Exposition", fr: "CHF a risque" }
        format: chf
        align: right
        width: 3

  - id: footer
    type: footer
    text:
      en: "All findings are algorithmically derived and should be reviewed by domain experts."
      de: "Alle Befunde sind algorithmisch abgeleitet und sollten von Fachexperten geprueft werden."
      fr: "Tous les resultats sont derives algorithmiquement et doivent etre examines par des experts."