Metadata & Geography — How it works
Overview
The metadata engine owns the platform's shared reference/lookup data — principally the geography hierarchy (country → state → county → city → community). It is centrally seeded, read-mostly data that other engines reference by id: the demographic engine validates a person's address against it, and the facility engine anchors facilities in it for geographic access scoping.
Data model & ownership
| Table | Purpose |
|---|---|
country | Top of the geography hierarchy. |
state | Belongs to a country. |
county | Belongs to a state. |
city | Belongs to a county. |
community | Belongs to a city (finest grain). |
Primary keys: these are the deliberate exception to the platform's UUID rule — because they are
seeded centrally and never created concurrently across nodes, they use stable numeric
(Long/Integer) surrogate keys. See the architecture overview.
Key rules & invariants
- Each level references its parent, forming a valid country → state → county → city → community chain; consumers (e.g. the demographic address service) reject ids that do not form a consistent hierarchy.
- Reference rows are stable and shared — engines store the id, not a copy of the name.
API
See the API Reference. Endpoint groups under /api/v1/metadata: countries, states,
counties, cities, communities.
Configuration & feature flags
None.
Related features
- Demographic (address validation), Facility (geography roll-up), Access control (geographic scopes).