Skip to main content

How to manage classification codebooks

When you'd do this: when you need a shared, versioned key-to-definition dictionary that a metric observation can cite — for example, a defect-severity scale or a priority scheme — and you want every observation's citation to stay meaningful even after the codebook changes.

A classification codebook is a named set of key-definition pairs (e.g. severity_high → "Critical defect requiring immediate attention"). Metric observations can cite a codebook name and version in their dimensions_json, so a report can resolve exactly what a stored value meant at the time it was captured — even if the codebook has since moved on to version 3.

Codebooks reuse REQQA's existing context-document lifecycle (the same upload/version/retire/ restore machinery as FR-21's context library) — a codebook is just a context document tagged source_type='codebook', never chunked or embedded, and never mixed into AI prompt context.

note

There is no menu link to these pages yet — go to /codebookList directly.

Step 1 — View existing codebooks​

Go to /codebookList. Any org member can see the active codebooks and their current version; only a System Administrator sees the Upload/Retire/Restore controls.

Step 2 — Upload a new codebook​

Click Upload Codebook (/codebookUpload) — System Administrator only.

  1. Give the codebook a name, unique within your organisation.
  2. In the key/definition box, enter one pair per line as key: definition — for example: 
    severity_high: Critical defect requiring immediate attention
    severity_medium: Significant but not release-blocking
    severity_low: Cosmetic or informational
  3. Click Upload. If this is a brand-new name, it's created as version 1. If the name already exists, uploading creates a new version — the previous version is retired, not edited; its content never changes.
caution

Each key within one upload must be unique, and at least one key-definition pair is required. An empty name or an empty pair list is rejected before anything is created.

Step 3 — View version history​

From the list, click History next to a codebook to open /codebookVersions/<name>. Every version is shown with its status (Active or Retired) and upload date — nothing is ever deleted, only retired.

Step 4 — Retire or restore a version​

Still System Administrator only, from the version history page:

  • Retire an active version when it's no longer current. Retiring doesn't touch any metric observation that already cited it — historical citations keep resolving correctly against the retired version if you ask for it explicitly.
  • Restore a retired version to make it active again. This creates a new version carrying the retired one's content — it's a clone, not a status flip on the original row, so the original stays retired and the restored copy gets the next version number.

Step 5 — Cite a codebook in a metric observation​

A producer posting to /api/v1/metrics includes the codebook name and version as ordinary dimensions, for example {"codebook": "defect_severity", "codebook_version": 2}. REQQA doesn't validate the cited value against the codebook's actual content — citing a key that doesn't exist in that version is accepted; it just won't resolve to a definition later.

Result​

A versioned, auditable classification scheme that any metric observation can cite, with every historical citation still resolvable to the exact definition text that was active when it was captured.