| name | sync-reference-data |
| description | Rules for authoring or regenerating a local reference/lookup data file (e.g. src/data/countries.ts) whose values are validated against a backend-enforced set. Use before adding, regenerating, or extending any fixed list backing a picker/select control. |
Sync Reference Data With Backend Validity
Rule
When a control needs a fixed list of valid values, and the backend enforces
that list via a JSON schema enum (or similar), find the backend's actual
source constant before authoring or regenerating the list. Never assume a
named external standard ("ISO 3166-1 country codes", "IANA time zones", etc.)
maps 1:1 to what the backend accepts. Backends frequently enforce a
validated subset, not the raw standard — a control that offers a value the
backend then rejects on save is a real, user-facing bug, not a cosmetic gap.
Concrete case: src/data/countries.ts
Backs the ui.phone_input.allowlist control, validated server-side by the
ISO31661Alpha2 JSON schema. That schema is not "every ISO 3166-1
code" — it's authgear-server's pkg/util/territoryutil/alpha2.go's
Alpha2 list (phone-numbering-plan-based, via
phonenumbers.GetSupportedRegions()), which:
- excludes uninhabited/no-phone-plan territories the full ISO standard
includes (Antarctica/
AQ, Bouvet Island/BV, South Georgia/GS, Heard
Island/HM, Pitcairn/PN, French Southern Territories/TF, US Minor
Outlying Islands/UM)
- includes at least one code some ISO references omit (Kosovo/
XK)
A version of this file built from "the ISO standard" in general drifted
from what the backend actually accepts: 7 selectable codes the backend
would reject on save, 1 valid code missing entirely from the picker.
Before authoring or regenerating any such list
- Find the backend's actual enum source in
authgear-server — grep
the OpenAPI spec's schema definitions, or the Go source it's
generated/derived from. Don't assume a named standard maps onto it.
- Check whether a sibling app already solved this.
authgear-server's
own portal/ frontend has the same country-code problem already solved
and kept in sync with the backend (portal/src/data/country.json) —
prefer matching an existing, verified list over re-deriving one from a
generic reference.
- Diff the two code sets exactly, not by spot-checking a few entries.
A one-line shell diff catches this in seconds; eyeballing a 240-entry
list does not.
- Add a test pinning the count and known boundary cases (a code that
must be present, a lookalike that must be absent) so a future edit can't
silently drift again — see
src/data/__tests__/countries.test.ts.
- Leave a comment on the data file pointing at the exact backend source
file/constant, not just the name of a general standard, so whoever
updates it next diffs against the right thing, not the wrong reference.
