> 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/features/data-discovery/entity-description.md). # Entity description Every data entity in the catalog carries an **operator-authored description** — free-form Markdown that documents what the entity is for, who reads from it, what the columns mean, and any in-house context that the source system does not carry. The description appears on the entity's detail page as the primary narrative surface above the structural panels (schema, lineage, tags, terms), and it surfaces in search-result rows and the Recommended-tile previews as the first-encounter snippet. This page covers the authoring workflow, the supported Markdown surface, the permissions that gate editing, the audit trail, and a load-bearing security caveat that applies to **six** of the platform's free-text Markdown surfaces. ## Where to find it Open any data entity's detail page → **Overview** tab. The description occupies the top of the Overview body. Operators with the [`DATA_ENTITY_DESCRIPTION_UPDATE`](/configuration-and-deployment/enable-security/authorization/permissions.md) permission see an **Edit** affordance; readers without the permission see the rendered description and nothing else. The same description text is also surfaced as the **preview snippet** on: * [Search](/features/data-discovery/search.md) result rows. * The Recommended-tile cards on the [Catalog Overview](/features/data-discovery/catalog-overview.md) home page. * The [Directory](/features/data-discovery/directory.md)'s level-4 entity list rows. The full Markdown rendering happens on the Overview tab; the preview surfaces above render an abbreviated plain-text projection. ## Authoring the description The Edit affordance opens an inline Markdown editor (`@uiw/react-md-editor`) with split-pane preview. Operators type the description in Markdown; saving issues `PUT /api/dataentities/{id}/description` with a JSON body carrying the new description string. The platform persists the text **verbatim** into the `data_entity.internal_description` column (PostgreSQL `text`, no length cap, no transformation other than mapping the empty string to `null`). Supported Markdown surface — what the renderer understands and the editor previews: * Headings (`#`, `##`, `###`, …). * Bold, italic, strikethrough. * Inline and fenced code blocks (syntax highlighting on the fenced form via the renderer's highlighter). * Bulleted and numbered lists, including nested lists. * Links — `[text](https://...)` plus the auto-link convention `[[Namespace:Term]]` that resolves to a glossary term (see [Manual Object Tagging](/features/data-discovery/tagging.md) and the [Business Glossary](/features/data-glossary/business-glossary.md) for the term-linking workflow). * Tables (GitHub-flavored). * Raw HTML — the renderer parses embedded HTML (`rehype-raw`); as of 0.28.0 it then sanitises the parsed HTML (`rehype-sanitize`) before display, stripping scripts and event-handler / `javascript:` vectors. See the security caveat below. The editor is the only place to author the description; there is no API-only path that bypasses the editor's preview. Third-party API clients calling `PUT /api/dataentities/{id}/description` directly write the same field — the stored value is verbatim either way (HTML sanitisation happens at render time, not on write). ## Permissions Editing the description is gated by **one** permission: | Permission | What it gates | | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | [`DATA_ENTITY_DESCRIPTION_UPDATE`](/configuration-and-deployment/enable-security/authorization/permissions.md) | The Edit affordance on the Overview tab plus the `PUT /api/dataentities/{id}/description` endpoint. | The permission is bound to the data entity in the URL (per the platform's RBAC model — see [Permissions](/configuration-and-deployment/enable-security/authorization/permissions.md) for the full per-resource gating story). Operators without it see the rendered description but no Edit affordance. ## Activity trail Description edits emit a `DESCRIPTION_UPDATED` event on the [Activity Feed](/features/active-platform-features/activity-feed.md). The event carries the entity id, the editor's identity, and the timestamp — and, in its old-state / new-state payload, the **full previous description and the full new description**. The Activity Feed is therefore a content-diff log for description edits, not merely an audit-of-occurrence: the per-entity Activity tab on the detail page reconstructs both *that* a description changed and *what* it changed from and to. ## Security caveat — stored-XSS family across six Markdown surfaces The platform's description-authoring surfaces apply **no write-time HTML sanitisation** — operator-typed Markdown is persisted verbatim. Rendering is the defence point: as of **0.28.0** the platform's shared Markdown renderer sanitises parsed HTML (`rehype-raw` → `rehype-sanitize`) before display, so `