> 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 (Catalogue)
The platform's catalogue of reference data: versioned datasets and geography, with approvals, a change feed and an opt-in public catalogue
A **catalogue** is the single, governed home of a country's **reference data**: the datasets and geography that many systems use but none of them owns. Examples are genders, education levels, units of measure, benefit types, crops or administrative areas.
The **Master Data Service (MDS)** is OpenG2P's catalogue. It defines each piece of reference data once, for every service in the deployment. Every change is approved before it is published, every published version is kept, and a consumer can always say exactly which version it used. MDS is generic: it serves any sector (social protection, agriculture, health, …). The examples on these pages use one country pack (Ethiopia) and a few sectors.
What MDS holds, what it does, and who uses it
## What it holds
MDS holds reference data, plus sample people for demos:
| | What it is | Example |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Datasets** | A country's own lists. A dataset holds **entries**: each a code and labels, and optionally typed fields that refer to other datasets. Each dataset has a **theme** (Core, or a sector) | Gender, units of measure, disability type; a seed variety with its crop and maturity days |
| **Geography** | The administrative hierarchy: levels, every unit with its code (P-code), and its boundaries | Country → region → zone → woreda |
| **Releases** | Named sets of pinned dataset and geography versions | "2027.1" for a census round |
| **Sample people** | A few dozen made-up people and households from the country pack, for **testing and demos only** | — |
MDS holds no partners (see [Partner Management](/platform/platform-services/partner-management.md)) and no registry records. All data first arrives from a **country pack**; see [Country Packs](/platform/platform-services/master-data-service/country-packs.md).
## Key features
| Feature | In one line | More |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Versioned datasets and geography** | Every dataset, and the geography, has numbered versions. A consumer reads the latest, pins a version, or reads as of a date | [Concepts](/platform/platform-services/master-data-service/concepts.md#reading-latest-pinned-as-of-release) |
| **Effective dates and staged changes** | A version can be approved now and take effect on a future date | [Concepts](/platform/platform-services/master-data-service/concepts.md#effective-dates) |
| **Change control with approvals** | Edits go into a draft, which is submitted and approved by another person (maker-checker) or through the Approval Workflow Engine | [Change Control](/platform/platform-services/master-data-service/change-control.md) |
| **Codes fixed once published** | Labels can change; codes cannot. A recode is a retire plus an add. Entries are retired, never deleted | [Concepts](/platform/platform-services/master-data-service/concepts.md#codes-are-fixed-once-published) |
| **Typed fields and references** | Entries can carry typed fields, a parent (hierarchy) and references to other datasets (cross-classification) | [Concepts](/platform/platform-services/master-data-service/concepts.md#typed-fields) |
| **Multilingual labels** | Labels per language for datasets, entries and units | [Concepts](/platform/platform-services/master-data-service/concepts.md#datasets-and-entries) |
| **Geography with boundary changes** | Splits, merges and renames are recorded as change events. A crosswalk maps old codes to new. Boundaries are kept per version | [Geography](/platform/platform-services/master-data-service/geography.md) |
| **Change feed** | Every change is in an ordered feed; new and effective versions are also pushed to subscribers | [For Consumers](/platform/platform-services/master-data-service/consumers.md#following-changes) |
| **Public catalogue (opt-in)** | Datasets marked public can be read anonymously, with downloads, DCAT and SKOS, each with its [data licence](/platform/platform-services/master-data-service/public-catalogue.md#data-licence) | [Public Catalogue](/platform/platform-services/master-data-service/public-catalogue.md) |
| **Audit** | Every change and every API call is sent to the Audit Manager | [Change Control](/platform/platform-services/master-data-service/change-control.md#audit) |
| **Access rules per staff member** | Some reads are filtered by rules set per staff member in IAM (for example, which geography units they see) | [API Reference](/platform/platform-services/master-data-service/api-reference.md#authentication-and-permissions) |
| **One deployment per country** | A deployment is seeded with exactly one country pack. A second country needs a second deployment, so registry images stay country-neutral | [Deployment](/platform/platform-services/master-data-service/deployment.md) |
Why MDS is built this way is on [Design Decisions](/platform/platform-services/master-data-service/design-decisions.md). The standards it uses are on [Standards](/platform/platform-services/master-data-service/standards.md).
## Who uses it
Registries, other OpenG2P services, maps and, through the public catalogue, open-data portals. Who reads what, and how, is on [For Consumers](/platform/platform-services/master-data-service/consumers.md). Catalogue administrators manage the data in the admin UI; see the [Admin Guide](/platform/platform-services/master-data-service/admin-guide.md).
## Deployment and source code
MDS ships inside the **`commons-services`** Helm chart; see [Deployment](/platform/platform-services/master-data-service/deployment.md). Code, images and the changelog: [Software Versions](/platform/platform-services/master-data-service/versions.md).
## Pages
| Page | What it covers |
| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Concepts](/platform/platform-services/master-data-service/concepts.md) | The ideas: datasets, entries and typed fields, the geography, versions and effective dates, fixed codes and retired entries, reads and releases, the change feed |
| [Geography and Boundary Changes](/platform/platform-services/master-data-service/geography.md) | P-codes, how geography and boundaries are represented, change events, the crosswalk |
| [Change Control and Approvals](/platform/platform-services/master-data-service/change-control.md) | Drafts, approval modes, settings that apply at once, permissions, audit |
| [For Consumers](/platform/platform-services/master-data-service/consumers.md) | Who reads MDS, and how to read, cache, pin and follow changes |
| [Public Catalogue](/platform/platform-services/master-data-service/public-catalogue.md) | The opt-in, anonymous catalogue for other websites |
| [Admin Guide](/platform/platform-services/master-data-service/admin-guide.md) | Who can do what in the admin UI, and the common tasks |
| [Country Packs](/platform/platform-services/master-data-service/country-packs.md) | What a country pack is, how to build one, and how it loads |
| [Design Decisions](/platform/platform-services/master-data-service/design-decisions.md) | Why reference data needs versions, and why MDS is designed as it is |
| [Deployment](/platform/platform-services/master-data-service/deployment.md) | Installing MDS and every setting |
| [API Reference](/platform/platform-services/master-data-service/api-reference.md) | Every endpoint, and the data model: fields, statuses, typed fields schema, change log |
| [Standards](/platform/platform-services/master-data-service/standards.md) | The standards MDS uses |
| [Software Versions](/platform/platform-services/master-data-service/versions.md) | Chart and image versions, and the changelog |
---
# 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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.
