> For the complete documentation index, see [llms.txt](https://docs.openg2p.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openg2p.org/platform/platform-services/master-data-service.md). # Master Data Service The **Master Data Service** (MDS) is where OpenG2P keeps the reference data that more than one service needs, so it is defined once and reused everywhere. ## What it contains * **Geography** — the administrative hierarchy for the country this deployment serves, every administrative unit with its **P-code**, and a link to where each unit's map shape can be fetched. * **Code lists** — the country's own vocabularies: genders, education levels, water sources, crops and so on, with their values. * **Sample people** — a few dozen individuals and households belonging to the country, used for demos and smoke tests. * **Partners** — the register of partner organisations (mnemonics, key-manager reference IDs, active status) used for inter-service trust and routing. The first three come from a **country pack**. What a pack is, where packs live and how a country is configured end to end is covered in [Country Data Architecture](/platform/country-data-architecture.md) — this page does not repeat it. ## What it serves, and to whom | Consumer | What it takes | How | | ---------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------- | | **Registries** (NSR, Farmer Registry, …) | Code lists, the geo hierarchy, sample people | At **install**, copied into the registry's own tables | | **Staff portal screens** | Geo units, level by level | At **runtime**, via the Geo API — this is what fills cascading address dropdowns | | **Bulk data generators** | The hierarchy and code lists | At install, so generated records point at real units | | **PBMS, Bridge, SPAR** | Partner and geo lookups | At runtime, via the APIs | | **Map and reporting surfaces** | Map shapes | From the country pack at build time — **not** from MDS at runtime | {% hint style="info" %} **Registries depend on MDS at install time, not on every write.** A registry copies what it needs into its own tables during seeding and validates against that copy afterwards. MDS being unavailable later does not stop a registration. {% endhint %} See the [API Reference](/platform/platform-services/master-data-service/api-reference.md) for the endpoints themselves. ## One deployment serves one country MDS is **single-tenant with respect to country**. A deployment is seeded with exactly one country pack, declared in one place: ```yaml geoSeed: countryPack: ETH # the single place a deployment declares its country ``` Everything MDS holds — the hierarchy, the code lists, the sample people — belongs to that pack. There is no country dimension on the data and no way to serve two countries from one instance; serving a second country means a second deployment. This is what keeps registry images country-agnostic: the same registry build serves Ethiopia or Kamuntu depending only on which pack the MDS beside it was seeded with. ## Source code {% hint style="warning" %} **The code has moved from GitHub to GitLab.** The GitHub repository is frozen and no longer receives changes. {% endhint %} * **Repository:** [`gitlab.com/openg2p/master-data-service`](https://gitlab.com/openg2p/master-data-service) One repository holds all of the service's parts together — the FastAPI application, the Docker image build, the Helm chart, and the country-pack seeder. ## Versions Versions are tracked in the changelog published by CI: * [**Master Data Service changelog**](https://openg2p.gitlab.io/versions/master-data-service/CHANGELOG.html) ## Deployment MDS is **not installed on its own**. It ships as part of the **`commons-services`** Helm chart, alongside the other shared platform services. * **Chart repository:** [`gitlab.com/openg2p/commons`](https://gitlab.com/openg2p/commons) {% hint style="warning" %} **Version bumps must be made in `commons-services`.** Publishing a new Master Data chart or image does not change any deployment by itself — the version pinned in the `commons-services` chart is what an install actually gets. A new MDS version that is not picked up there is a version nobody runs. {% endhint %} Country-pack selection (`geoSeed.countryPack`, and which parts of the pack to load) is therefore also configured through `commons-services`. ## Legacy versions {% hint style="info" %} Superseded by the [changelog](https://openg2p.gitlab.io/versions/master-data-service/CHANGELOG.html) above, and retained for history. These rows point at the former GitHub repository and at Docker Hub images predating the move to GitLab. {% endhint %}
Helm versionMaster Data DockerLast modifiedComments
0.0.0-develop.8master-data-api:develop10-Jul-2026Changes since 2ac3823: registry-DB integration + IAM auth for geo data-policy resolution; new geo-level APIs; 0.0.0-develop.N chart versioning.
0.0.0-developmaster-data-api:develop15-Jun-2026
  1. Single consolidated repository master-data-service — master-data source, Docker image, and the Helm chart now live in one repo (previously three separate repositories).
  2. Single Helm chart openg2p-master-data under deployments/charts.
  3. Docker image is built from local in-repo source and tagged with the repository ref — on develop the image is tagged develop.
1.0.0openg2p-gen2-master-data-api:v1.0.017-Apr-2026
  1. Initial version of the Master Data API — Partners and Geo lookup data.

THIS VERSION HAS BUGS. Use develop.

{% hint style="info" %} On the `develop` branch the Docker image is tagged `develop` (the image tag always matches the `master-data-service` repository ref — a branch name or git tag). The Helm chart's base version is `0.0.0-develop`, but each publish appends the CI run number, so the artifact published to the Helm repo is `0.0.0-develop.` (this keeps Rancher / the GH-Pages CDN from serving a stale cached chart). Release branches publish `N.N.0-develop.`, and frozen `N.N.N` releases carry that semantic version with no suffix. The **Last modified** date of the `0.0.0-develop` row should be updated whenever that version changes. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.openg2p.org/platform/platform-services/master-data-service.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.