> For the complete documentation index, see [llms.txt](https://docs.opendatadiscovery.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opendatadiscovery.org/developer-guides/api-reference/glossary.md). # Glossary The Business Glossary surface — `Glossary` and `Terms` are registered aliases on `main-concepts.md` "Terms & Aliases" — is exposed under `/api/terms/` plus a small set of linkage endpoints owned by the data-entity and dataset-field controllers. The endpoints below back the in-app `Dictionary` tab and the Term-to-\* linking workflows. For the term creation flow, the description-text vs direct-link distinction, and the user-side walkthrough, see the [Business Glossary](/features/data-glossary/business-glossary.md) page under [Data Glossary](/features/data-glossary.md). ## Authentication and authorization caveats Several glossary write endpoints do not gate the way an operator reasoning from the permission catalog would expect. Read these before authoring separation-of-duties roles — each lets a holder of a narrow `TERM_*` permission perform an action that looks like it should require a different, dedicated permission. {% hint style="warning" %} **Creating or updating a term auto-creates its namespace without `NAMESPACE_CREATE`.** Both `createTerm` (`POST /api/terms`, gated by `TERM_CREATE`) and `updateTerm` (`PUT /api/terms/{term_id}`, gated by `TERM_UPDATE`) call the namespace service's get-or-create on the submitted namespace name. A caller who holds only `TERM_CREATE` or `TERM_UPDATE` — and explicitly not `NAMESPACE_CREATE` — can mint a brand-new platform-wide namespace just by typing a novel name into the term form. If you separate namespace administration from term authoring, this path bypasses that separation. {% endhint %} {% hint style="warning" %} **Replacing a term's tags auto-creates any missing tags without `TAG_CREATE`.** `createTermTagsRelations` (`PUT /api/terms/{term_id}/tags`, gated by `TERM_TAGS_UPDATE`) calls the tag service's get-or-create for every name in the submitted list. A caller who holds only `TERM_TAGS_UPDATE` — and not `TAG_CREATE` — can mint new platform-wide tags through this endpoint. The tag directory accretes silently; the dedicated tag-creation permission does not gate this path. {% endhint %} {% hint style="danger" %} **The `DATA_ENTITY_ADD_TERM` / `DATA_ENTITY_DELETE_TERM` gates on the term-to-entity link endpoints never fire — those endpoints are open to any authenticated user.** The security-rule registry binds the two permissions to the **singular** paths `/api/dataentities/{id}/term` and `/api/dataentities/{id}/term/{term_id}`, while the endpoints the contract and this page expose are the **plural** `/api/dataentities/{id}/terms` (`addDataEntityTerm`) and `/api/dataentities/{id}/terms/{term_id}` (`deleteTermFromDataEntity`). The path-matcher never matches, so the requests fall through to the global "any authenticated user" rule. The direct term-to-term link endpoints (`POST`/`DELETE /api/terms/{term_id}/term`) have no security rule registered at all and are likewise open to any authenticated user. Do not rely on `DATA_ENTITY_ADD_TERM` / `DATA_ENTITY_DELETE_TERM` for separation-of-duties on term linkage until the platform-side path fix lands. {% endhint %} **Term CRUD and lookup** | Method | Path | Operation ID | Purpose | | -------- | ---------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/api/terms` | `getTermsList` | Paginated list of terms. Optional `query` (free-text), `updated_at_range_start_date_time`, and `updated_at_range_end_date_time` filters. | | `POST` | `/api/terms` | `createTerm` | Create a new term. Body: `TermFormData` (name, namespace, description). Returns `TermDetails`. Gated by `TERM_CREATE`; auto-creates the namespace without `NAMESPACE_CREATE` (see [caveats](#authentication-and-authorization-caveats)). | | `GET` | `/api/terms/{term_id}` | `getTermDetails` | Get full term details (metadata, ownership, tags, link counts). | | `PUT` | `/api/terms/{term_id}` | `updateTerm` | Update an existing term. Body: `TermFormData`. Returns the updated `TermDetails`. | | `DELETE` | `/api/terms/{term_id}` | `deleteTerm` | Delete a term. | | `GET` | `/api/terms/namespaces/{namespace_name}/names/{term_name}` | `getTermByNamespaceAndName` | Resolve a term by its namespace and name (the natural-key lookup form). Returns `TermRef`. | **Term-side linkage — read and write from a term** The first three endpoints read the entities, columns, and other terms linked to a given term. The last two are the term-to-term linking writes — for the user-facing description of the two link modes (description-text mentions vs direct links), see [Business Glossary → Term-to-term linking](/features/data-glossary/business-glossary.md#term-to-term-linking). | Method | Path | Operation ID | Purpose | | -------- | -------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/api/terms/{term_id}/linked_entities` | `getTermLinkedEntities` | Paginated list of data entities currently linked to the term. Optional `entity_class_id` filter. | | `GET` | `/api/terms/{term_id}/linked_columns` | `getTermLinkedColumns` | Paginated list of dataset fields (columns) linked to the term. | | `GET` | `/api/terms/{term_id}/linked_terms` | `getTermLinkedTerms` | Paginated list of other terms linked to this term (the term-to-term graph). | | `POST` | `/api/terms/{term_id}/term` | `addLinkedTermToTerm` | Create a direct term-to-term link. Body: `LinkedTermFormData` carrying the target term's id. Bi-directionally visible from either term. No RBAC permission is registered for this path — open to any authenticated user (see [caveats](#authentication-and-authorization-caveats)). | | `DELETE` | `/api/terms/{term_id}/term/{linked_term_id}` | `deleteLinkedTermFromTerm` | Remove a direct term-to-term link. | **Linkage from the linked resource's side** These four endpoints attach or detach a term from the perspective of the resource the term is being linked **to**. The dataset-field endpoints accept and return `LinkedTerm`. For term ↔ query-example linking, see [Query Examples → Per-entity / per-term lookup and linking](/developer-guides/api-reference/query-examples.md#per-entity--per-term-lookup-and-linking-6-endpoints). | Method | Path | Operation ID | Purpose | | -------- | ------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `POST` | `/api/dataentities/{data_entity_id}/terms` | `addDataEntityTerm` | Link a term to a data entity. Body: `DataEntityTermFormData`. Returns `LinkedTerm`. The `DATA_ENTITY_ADD_TERM` gate is registered on a different (singular) path and never fires — open to any authenticated user (see [caveats](#authentication-and-authorization-caveats)). | | `DELETE` | `/api/dataentities/{data_entity_id}/terms/{term_id}` | `deleteTermFromDataEntity` | Remove a term link from the data entity. | | `POST` | `/api/datasetfields/{dataset_field_id}/terms` | `addDatasetFieldTerm` | Link a term to a dataset field (column). Body: `DatasetFieldTermFormData`. Returns `LinkedTerm`. | | `DELETE` | `/api/datasetfields/{dataset_field_id}/terms/{term_id}` | `deleteTermFromDatasetField` | Remove a term link from the dataset field. | **Faceted search** The same multi-step facet flow the main catalog uses — start a search, then read / update / paginate against the resulting `search_id` (a UUID). | Method | Path | Operation ID | Purpose | | ------ | -------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `POST` | `/api/terms/search` | `termSearch` | Start a search. Body: `TermSearchFormData`. Returns `TermSearchFacetsData` carrying the `search_id` and initial facet aggregations. | | `GET` | `/api/terms/search/{search_id}` | `getTermSearchFacetList` | Re-read the current facets for a search. | | `PUT` | `/api/terms/search/{search_id}` | `updateTermSearchFacets` | Update the search query and re-aggregate facets. | | `GET` | `/api/terms/search/{search_id}/facet/{facet_type}` | `getTermFiltersForFacet` | Countable filter values for one facet (paginated, with optional `query`). `facet_type` is one of the `MultipleFacetType` enum values. | | `GET` | `/api/terms/search/{search_id}/results` | `getTermSearchResults` | Paginated result list for the search. | | `GET` | `/api/terms/search/suggestions?query=…` | `getTermSearchSuggestions` | Top-five matching term names for the search-input typeahead. | **Term ownership and tags** | Method | Path | Operation ID | Purpose | | -------- | ----------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `POST` | `/api/terms/{term_id}/ownership` | `createTermOwnership` | Add an ownership entry to the term. Body: `OwnershipFormData`. Returns `Ownership`. | | `PUT` | `/api/terms/{term_id}/ownership/{ownership_id}` | `updateTermOwnership` | Update an existing ownership (typically to change role). Body: `OwnershipUpdateFormData`. | | `DELETE` | `/api/terms/{term_id}/ownership/{ownership_id}` | `deleteTermOwnership` | Remove an ownership entry. | | `PUT` | `/api/terms/{term_id}/tags` | `createTermTagsRelations` | Replace the term's tag set. Body: `TagsFormData` (the full target list). Tags that don't yet exist on the platform are created. Returns the updated `TagList`. Gated by `TERM_TAGS_UPDATE`; auto-creates tags without `TAG_CREATE` (see [caveats](#authentication-and-authorization-caveats)). | ## See also * [API Reference hub](/developer-guides/api-reference.md) — the full per-feature index. * [Business Glossary](/features/data-glossary/business-glossary.md) — feature description, term creation flow, term-to-term linking. --- # 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: ``` GET https://docs.opendatadiscovery.org/developer-guides/api-reference/glossary.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.