---
title: Table Configuration (table_config.yaml)
---

# Specification: Table Configuration (table_config.yaml)

## Title and Purpose

Defines the **external, user-editable YAML file** (`table_config.yaml`) that controls which columns appear in the repository-overview table, their order, labels, visibility, and the default sort order & group notes used by downstream renderers.  
The file is loaded at runtime via `Settings.table_config` (see `src/gitlab_overviewer/config/settings.py`) and is consumed by the **sorting** and **rendering** infrastructure ([Table Sorting](./spec_table_sorting.md), [Table Rendering & UI](./spec_table_rendering_ui.md)).

## Scope and Boundaries

* **In scope** – file structure, required/optional keys, validation rules, default behaviour, error handling.
* **Out of scope** – CLI flags that override sorting (`--sort`) or alternative configuration sources.
* **Dependencies** – relies on the column semantics defined in the data model and the behaviour specified in related specs above.

---

## 1  YAML Top-Level Keys

| Key | Type | Required | Purpose |
|-----|------|----------|---------|
| `columns` | list(dict) | **Yes** | Declares table columns (order = list order). |
| `default_sort` | list(str) | No | Fallback sort keys (§3) when the user supplies none. |
| `group_notes` | dict | No | Optional explanatory notes rendered under group sections. |

Any additional keys are ignored and MUST NOT influence program flow.

---

## 2  `columns` Entries

Each element of `columns` is a mapping with the following fields:

| Field | Type | Required | Default | Behaviour |
|-------|------|----------|---------|-----------|
| `key` | str | **Yes** | – | Column key that **must** exist in every row. |
| `label` | str | No | Same as `key` | Header text displayed in the table. |
| `visible` | bool | No | `true` | If `false`, the column is omitted from header & body. |

### 2.1 Validation Rules

* The list must not contain **duplicate `key` values**.
* Every `key` **must** match a property present in the overview data; unknown keys raise a *TableConfigurationError* **before any rendering starts**.
* `visible` missing → treated as `true` (spec default).

---

## 3  `default_sort`

A list of sort-key strings complying with the grammar defined in [Table Sorting](./spec_table_sorting.md#1-sort-key-definition).  
They are evaluated left-to-right when no CLI/ENV override is supplied.

Validation occurs via the sort-utilities module:

* Unknown columns or unsortable virtual columns raise *SortConfigurationError*.
* If omitted, the application falls back to `repo:asc` (repository name ascending).

---

## 4  `group_notes`

Optional mapping controlling the informational paragraph appended **after** each group table (see rendering spec §5):

```yaml
# Example structure
group_notes:
  default: "Note shown for groups without specific override."
  groups:
    alpha-group: "Alpha specific note."
    beta-group: "Beta specific note."
```

| Sub-Key | Type | Required | Meaning |
|---------|------|----------|---------|
| `default` | str | No | Note used for groups *not* listed under `groups`. May be empty. |
| `groups` | mapping | No | Explicit overrides `group-name → note`. |

When absent entirely, no notes are rendered.

---

## 5  Error Handling Summary

| Condition | Raised Exception | Origin |
|-----------|------------------|--------|
| `columns` key missing | `TableConfigurationError` | `validate_column_configuration` |
| Duplicate or unknown column `key` | `TableConfigurationError` | idem |
| Invalid `default_sort` entry (unknown column, bad direction) | `SortConfigurationError` | `parse_sort_keys` |
| File path set in `Settings.table_config` does not exist | **Runtime warning** (log) – **not fatal** | `Settings.__init__` |

The application MUST fail fast on configuration errors but remain robust against a *missing* config file by issuing a warning and operating with **built-in defaults**.

---

## 6  Testing Requirements

1. **Positive Cases** – snapshot tests must include at least one valid `table_config.yaml` verifying:
   * Column order & labels propagate to rendered Markdown.
   * Invisible columns are omitted.
   * `default_sort` influences sort order when no CLI override is present.
2. **Negative Cases** – unit tests must assert that misconfigurations raise the correct exceptions (see table above).
3. **Integration** – approval tests covering the full pipeline (`OverviewData → table → Markdown/Quarto`) must pass with the gold-standard `table_config.yaml` located at project root.

---

## 7  Non-Goals

* The spec does not mandate the location of the YAML file except that its path is provided via `Settings.table_config` (defaulting to `table_config.yaml` in the working directory).
* Styling of the rendered table (HTML/CSS) is out of scope.
* Runtime overrides (CLI `--columns`, etc.) are beyond this document.