# Directory topic schemes API reference Source: https://docs.settlemint.com/docs/api-reference/reference/directory-topic-schemes Read the platform-wide directory of claim topic schemes, including the claim data shape each one defines, through the DALP Platform API. A topic scheme defines a kind of verifiable claim, such as a Know Your Customer result or an accredited-investor attestation, and the data shape that claim carries. DALP compliance checks reference these schemes when they decide whether a transfer or other gated operation may proceed. An auditor or compliance lead needs an authoritative view of which topic schemes the platform recognises and exactly what data shape each one defines. These endpoints provide that platform-wide view. The directory topic scheme registry is the platform-wide (global) tier. Schemes registered here are inherited by the systems beneath them, so a single scheme can apply across many systems at once. Each scheme record reports `inheritedBySystemsCount`. A reviewer reads that count to see how far a scheme reaches before anyone changes it. This surface is read-only. It lists and reads topic schemes. It does not register, edit, or remove them. ## How this differs from system claim topics [#how-this-differs-from-system-claim-topics] DALP resolves topic schemes across tiers: the platform-wide directory and each system. These endpoints read the platform-wide directory tier only. A scheme that exists here is the global definition that downstream systems inherit, unless a system has registered its own scheme under the same numeric topic id. | You want to | Use | | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | Audit every topic scheme the whole platform recognises | These directory endpoints | | Inspect the trusted issuers authorised for each topic | [Directory trusted issuers API](/docs/api-reference/reference/directory-trusted-issuers) | | Discover the contracts and registries backing the active network | [System directory API](/docs/api-reference/reference/directory) | ## Required role [#required-role] Reading the platform-wide directory requires the platform `admin` role. These endpoints sit above the per-system permission model, so a system-scoped role cannot call them. Set the standard request headers before calling these endpoints. See [Request headers](/docs/api-reference/reference/request-headers). ## Endpoints [#endpoints] | Endpoint | Use it for | | -------------------------------------------- | ------------------------------------------------------- | | `GET /api/v2/directory/topic-schemes` | List every topic scheme in the platform-wide directory. | | `GET /api/v2/directory/topic-schemes/{name}` | Read one directory topic scheme by its name. | The list response uses the collection envelope with `data`, `meta`, and pagination `links`. The read response uses the single-resource envelope with `data` and `links.self`. ## Topic scheme fields [#topic-scheme-fields] The list and read endpoints return the same scheme record. | Field | Type | Description | | ------------------------- | ------- | ----------------------------------------------------------------------------------------------- | | `id` | string | Synthetic identifier for the row, combining the registry address and topic id. | | `topicId` | string | Numeric topic id as a decimal string, matching the on-chain value. | | `name` | string | Human-readable scheme name, such as `Know Your Customer`. | | `signature` | string | ABI type list that defines the claim's data shape, such as `(string)` or `(uint256,bool)`. | | `registry` | object | The global topic scheme registry, as `{ "id": "0x..." }`. | | `isShadowed` | boolean | `true` when at least one system has registered the same `topicId` with a different `signature`. | | `inheritedBySystemsCount` | number | How many systems inherit this scheme through the registry chain. | The `signature` is the contract that downstream claims must satisfy. Two schemes that share a `topicId` but disagree on `signature` describe incompatible claim shapes for the same topic. That mismatch is what `isShadowed` flags. ## Shadowed schemes [#shadowed-schemes] A scheme is shadowed when a child system has registered the same numeric `topicId` under a different `signature`. The global definition still stands, but at least one system reads that topic with a conflicting claim shape. A reviewer treats `isShadowed: true` as a signal to reconcile the system-tier registration before relying on claims for that topic, because a claim valid under one signature does not validate under the other. ## List directory topic schemes [#list-directory-topic-schemes] `GET /api/v2/directory/topic-schemes` returns the schemes registered in the platform-wide directory, ordered by name. The list supports pagination, sorting by `name` or `topicId`, and filtering by `topicId`, `name`, and `signature`. It also supports global search with `filter[q]`, which matches across the name, signature, and topic id in one query. ```bash curl --globoff "https://your-platform.example.com/api/v2/directory/topic-schemes?filter[name]=Customer&sort=name" \ -H "x-api-key: YOUR_API_KEY" ``` ```json { "data": [ { "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F#1", "topicId": "1", "name": "Know Your Customer", "signature": "(string)", "registry": { "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F" }, "isShadowed": false, "inheritedBySystemsCount": 3 } ], "meta": { "total": 1, "facets": {} }, "links": { "self": "/v2/directory/topic-schemes?page[offset]=0&page[limit]=50", "first": "/v2/directory/topic-schemes?page[offset]=0&page[limit]=50", "prev": null, "next": null, "last": "/v2/directory/topic-schemes?page[offset]=0&page[limit]=50" } } ``` The list returns 50 schemes per page by default, up to 200. Use `page[offset]` and `page[limit]` to page through larger registries. The `name` filter matches case-insensitively, so `filter[name]=customer` and `filter[name]=Customer` return the same rows. ## Read one topic scheme [#read-one-topic-scheme] `GET /api/v2/directory/topic-schemes/{name}` returns a single scheme by its name. The path segment is the scheme name, not the numeric topic id, and the lookup is case-sensitive with no normalization. ```bash curl "https://your-platform.example.com/api/v2/directory/topic-schemes/Know%20Your%20Customer" \ -H "x-api-key: YOUR_API_KEY" ``` ```json { "data": { "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F#1", "topicId": "1", "name": "Know Your Customer", "signature": "(string)", "registry": { "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F" }, "isShadowed": false, "inheritedBySystemsCount": 3 }, "links": { "self": "/v2/directory/topic-schemes/Know%20Your%20Customer" } } ``` URL-encode names that contain spaces or other reserved characters, as shown above. The endpoint returns `DALP-0619` with status 404 when no scheme matches the name on the global registry. Confirm the name and that the scheme was registered before retrying. Because the read reflects the indexed registry, a recently registered scheme may need a moment for indexing to catch up. ## When the global registry is unavailable [#when-the-global-registry-is-unavailable] Both endpoints resolve the platform-wide topic scheme registry from the active network's directory before reading. If the directory address is missing for the active network, or the indexer has not yet processed the global registry, they return `DALP-0618` with status 404. Confirm the platform's directory address is configured for the active network and that indexing has caught up, then retry. ## When to use it [#when-to-use-it] Use these endpoints when you need to: * Produce an audit list of every claim topic scheme the platform recognises. * Confirm the exact claim signature a topic enforces before relying on claims that use it. * Spot shadowed topics, where a system has redefined a global topic with a different claim shape, through `isShadowed`. * Measure how far a scheme reaches across systems through `inheritedBySystemsCount` before a change. To see which trusted issuers may attest each topic, use the [Directory trusted issuers API](/docs/api-reference/reference/directory-trusted-issuers).