> 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/public-catalogue.md).

# Public Catalogue

The opt-in, anonymous, read-only public catalogue of MDS: what it shows, visibility and licence, downloads, DCAT and SKOS, and how to switch it on

MDS has no public website: its UI is for administrators. What it can do is make its catalogue **openly readable** by other websites and open-data portals (a national data portal, CKAN, a ministry site) through an anonymous, read-only API, with downloads and standard metadata they can harvest.

## What it offers

|               |                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------- |
| **Datasets**  | Each public dataset with its entries, at the latest version, a pinned version or as of a date |
| **Geography** | Levels and units, and each level's boundaries                                                 |
| **Releases**  | Published releases, with their public members only                                            |
| **Downloads** | CSV and JSON per dataset version; CSV and GeoJSON per geography level                         |
| **DCAT**      | A catalogue description that open-data portals can harvest                                    |
| **SKOS**      | Each dataset as a concept scheme                                                              |

Responses can be cached (they carry `ETag` and `Last-Modified`), can be read from any website (CORS), and can be rate limited (see [Deployment: public catalogue host](https://docs.openg2p.org/platform/platform-services/master-data-service/deployment.md#public-catalogue-host)). Every operation, with its parameters, is in the [API Reference: Public API](https://docs.openg2p.org/platform/platform-services/master-data-service/api-reference.md#public-api).

### DCAT catalogue

The DCAT catalogue (JSON-LD) lists each public dataset with a published version in effect, and the geography when it is public, each with its licence, theme, version and one download per format. CKAN's DCAT harvester and other portals can harvest it. See [Standards](https://docs.openg2p.org/platform/platform-services/master-data-service/standards.md#catalogue-metadata-public-catalogue).

It is metadata, not data: it says what exists and where to get it, for portals and harvesters rather than applications. Even with one dataset it is long, because JSON-LD spells every term out:

| Part                           | What it is                                                                                           |
| ------------------------------ | ---------------------------------------------------------------------------------------------------- |
| `@context`                     | The vocabularies the terms come from (DCAT, Dublin Core `dct:`, SKOS, …); the same in every response |
| The catalogue (`dcat:Catalog`) | Its title, description, last change and home page                                                    |
| `dcat:themeTaxonomy`           | The themes (core, agriculture, …) as a small SKOS scheme                                             |
| `dcat:dataset`                 | One entry per public dataset: identifier, title, dates, theme, version, licence (when set)           |
| `dcat:distribution`            | Per dataset, one entry per format (CSV, JSON, SKOS), each with its download URL and media type       |

The entries themselves are not in it: an application reads them from `/public/datasets/{code}/entries`, or a download.

### SKOS concept schemes

Each public dataset can be read as a SKOS concept scheme (JSON-LD): one concept per active entry, with its entry code, labels per language and parent. A concept's address does not include the version, so an entry code keeps the same address across versions. See [Standards](https://docs.openg2p.org/platform/platform-services/master-data-service/standards.md#datasets-and-entries).

## What is public

Two switches decide what is served:

1. **The deployment** switches the public catalogue on. While it is off, nothing is served. It is off by default in the MDS chart and on in Commons Services, on its own host `catalogue.<base domain>`, reachable on the internal network only until an operator publishes that host on the internet; see [Deployment: public catalogue host](https://docs.openg2p.org/platform/platform-services/master-data-service/deployment.md#public-catalogue-host).
2. **An administrator** marks each dataset, and the geography, **public**. Everything is **private** by default, including what a country pack loads.

Whatever the settings, only **published versions** are shown. Drafts, private datasets, the change feed, who made or approved a version, and the sample people are never reachable. A private dataset and one that does not exist get the same "not found", so the API does not reveal what exists behind it.

Authenticated callers, such as registries, are not affected: their API ignores visibility.

## Visibility and licence

Each dataset, and the geography, has:

* a **visibility**: *Private* (default) or *Public*;
* an optional **data licence**: a label and a URL, for example *CC BY 4.0*.

Both are set in the admin UI and apply at once; they are not part of a version. Making the geography public makes all its published versions readable. A public dataset is listed once it has a published version in effect. The country-pack loader never makes anything public. The steps are in the [Admin Guide](https://docs.openg2p.org/platform/platform-services/master-data-service/admin-guide.md#make-a-dataset-public).

### Data licence

The licence of a dataset or of the geography is the **terms under which others may reuse that data** once it is public. It is shown with the data in the public catalogue and its downloads, as open-data catalogues (DCAT) expect.

* It often follows the **source's licence**. A country's boundaries from OCHA COD-AB, for example, are CC BY-IGO, which requires attribution wherever they are shown. The country-pack loader therefore sets the geography's licence from the pack's manifest when none is set; see [Sources and licence](https://docs.openg2p.org/platform/platform-services/master-data-service/country-packs.md#sources-and-licence).
* It is set per dataset by the catalogue administrator, who knows the terms of each source.
* It is **not** the licence of OpenG2P's code (MPL 2.0).

{% hint style="info" %}
Staff data policies do not apply to the public catalogue: marking a dataset public is the decision to show all of it.
{% 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 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/public-catalogue.md?ask=<question>&goal=<user_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.
