From 8772f1cdd3a9d833f7ed4ef9e97294cad09cbe9c Mon Sep 17 00:00:00 2001 From: Michael Anderson Date: Sun, 28 Jun 2026 01:31:56 -0500 Subject: [PATCH] README: document ui_datadict.db (UI projection) Add a "UI projection" section describing the derived ui_datadict.db: how to build it, the Categories -> Groups -> UI_DataItems schema, the Wizard group, the CharLength/ByteLength governance columns, ValidationSpecs, and CI coverage. Co-Authored-By: Claude Opus 4.8 --- README.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/README.md b/README.md index 9aa3a37..8685adb 100644 --- a/README.md +++ b/README.md @@ -195,6 +195,41 @@ CREATE UNIQUE INDEX ux_dataitems_natural --- +## UI projection (`ui_datadict.db`) + +A second, **derived** database aimed at UI / form generation and resource +governance. `tools/build_ui_dict.py` reads `datadict.db` (read-only) and rebuilds +`ui_datadict.db` + `ui_datadict.sql` from scratch: + +```bash +python3 tools/build_ui_dict.py +sqlite3 ui_datadict.db "SELECT * FROM UI_DataItems LIMIT 5;" +``` + +It reshapes the dictionary into a 3-level hierarchy — **`Categories → Groups → +UI_DataItems`** (12 categories, **120 groups**, 3,688 items): + +- **`Groups`** — one per entity (the part before the last dot of `Name`). The + 43 transient wizard / relation (junction) entities collapse into a single + **`Wizard`** group; `gs1` is kept. Each group carries its `CategoryID`. +- **`UI_DataItems`** — `Name` is reduced to just the field; every item is treated + as **UTF-8** with an *implied* `DataType`, plus governance columns: + - **`CharLength`** — declared VARCHAR length, else a per-type default + - **`ByteLength`** = `CharLength × 4` (UTF-8 worst case) + - **`ValidationSpecs`** — the source mask (e.g. GS1) when present, else + generated from type / allowed values / scale + +| Groupname | Name | DataType | CharLength | ByteLength | ValidationSpecs | +|---|---|---|--:|--:|---| +| patient | dob | DATE | 10 | 40 | `^\d{4}-\d{2}-\d{2}$` | +| patient | first_name | VARCHAR | 255 | 1020 | `maxlength: 255` | +| patient | blood_group | VARCHAR | 255 | 1020 | `one of: A Positive\|A Negative\|…` | + +`datadict.db` is never modified; CI rebuilds and validates `ui_datadict.db` +(completeness, FK integrity, `ByteLength = CharLength*4`, unique `(GroupID, Name)`). + +--- + ## How it's built ```