# Child Support data dictionary

The downloadable workbook is `public/docs/child-support-data-dictionary.xlsx`.
Its Register, Follow-up, and Release sheets document form/export keys, labels,
types, required fields, current option codes, date/ID formats, and repeating data.
The generator renders empty form definitions and never loads patient records.

Rebuild after changes to the forms, serializers, or export formats:

1. Run `php scripts/child-support-dictionary/render-forms.php /tmp/child-support-dictionary` from the project root.
2. Run `python scripts/child-support-dictionary/extract.py /tmp/child-support-dictionary` with `lxml` available.
   Then run `python scripts/child-support-dictionary/build-export-layout.py /tmp/child-support-dictionary` to refresh the shared column order and groups.
3. Copy `build.mjs` into that temporary directory and link its `node_modules` to a runtime providing `@oai/artifact-tool`. Run `node /tmp/child-support-dictionary/build.mjs /tmp/child-support-dictionary/dictionary.json /tmp/child-support-dictionary/output`.
4. Review the generated workbook and preview images. Copy the workbook to `public/docs/child-support-data-dictionary.xlsx`.
5. Deploy the workbook and bump the cache version in `public/service-worker.js` so existing PWA installations cache the refreshed dictionary.

Update the version date in `build.mjs` on each rebuild. Form labels and option
lists are extracted automatically. Derived fields and serialization/export notes
are documented in `extract.py` and should be reviewed when those behaviors change.

The generated export layout lives in `resources/data/child-support-export-layout.json`
for PHP and `public/js/child-support-export-layout.js` for the browser. Both are built
from the rendered forms. Register collections stay in their table positions, with
`core_family_members_count` immediately before `core_family_members`. Follow-up
exports include `name_count` immediately before `name`, counting non-blank names.
Register exports include `current_household_members_count` immediately before
`current_household_members`, counting non-empty member objects. Counts are computed
at export time, with 0 for empty collections. Follow-up normalized aliases stay
next to their corresponding inputs. Hidden register links
and additional saved fields go after the visible form fields.

Excel exports have four header rows: section, subtitle, form label, and field key.
Data begins on row 5. CSV has one field-key header row in the same order. The
browser writer is the locally bundled ExcelJS 4.4.0, so colours, merges, filters,
and frozen headers are available offline. Server-generated Excel exports use the
same layout and styles through `ChildSupportExportLayout` and `RegisterRowsExport`.

The shared download link is `child_support.partials.data_dictionary_download`.
It is included in each form header and uses the workbook modification time to
refresh browser downloads. The service worker caches the workbook for offline use
and ignores that version query when looking up the offline copy.
