Displaying Both Ingested and Manually Edited Descriptions Using Structured Properties – DataHub Customer Support Portal

Area: Best Practices

Sub-Area: Description Management and Metadata Annotation

Issue

DataHub displays only one description per asset (table or column) at a time. When a user edits a description in the DataHub UI or via the API, that edited version takes precedence over the ingested source description. As a result, users cannot simultaneously view both the ingested description (e.g., from Snowflake or dbt) and any DataHub-specific annotation added manually. Organizations that want to preserve upstream source descriptions while also capturing DataHub-managed notes need a pattern that keeps both pieces of information visible and independently maintainable.

You Might Be Asking

Is there a DataHub setting to show both the ingested description and the manually edited description at the same time?
Will a new ingestion run overwrite my manually edited descriptions?
How can I add DataHub-specific notes to an asset without hiding the source system description?
Can non-owners propose changes to structured properties, similar to description change proposals?

Solution

There is no built-in setting in DataHub to display the ingested description and an edited description side by side within the same description field. Understanding how DataHub stores and prioritizes descriptions will help you choose the right pattern for your organization.

How Description Priority Works

Ingestion writes source descriptions to:
- datasetProperties.description (tables)
- schemaMetadata.fields[].description (columns)
Manual edits made in the DataHub UI or via the API are stored separately in:
- editableDatasetProperties.description (tables)
- editableSchemaMetadata (columns)
The UI surfaces the edited description first. If no edited description exists, the ingested description is shown.
A subsequent ingestion run refreshes the source description in its own aspect but does not overwrite the manually edited aspect. The edited text continues to be shown on top.
Users with edit access can see the current ingested description in the read-only panel within the edit dialog, but general readers cannot.

Recommended Pattern: Use Structured Properties for DataHub-Specific Annotations

The cleanest approach that keeps both pieces of information visible and independently maintained is to:

Leave the description field owned by ingestion. Do not manually edit the description field. This ensures the ingested source description is always visible to all users in the main description area of the asset.

Create a structured property for DataHub-specific notes. Structured properties are not touched by ingestion, so they will never be overwritten by an ingestion run. Use a structured property to store any additional context, annotations, or team-specific notes.

# Example: Creating a structured property via the DataHub UI
# Navigate to: Govern > Structured Properties > + Create
# Set:
#   Name: e.g., "DataHub Notes"
#   Type: String (or Rich Text)
#   Applies To: Datasets, Schema Fields (as needed)
#   Visibility: Visible to all roles

Apply the structured property to relevant assets. Once created, the property appears as a dedicated field on each asset page, clearly separated from the ingested description.

Change Proposals for Structured Properties

Structured properties support the same change proposal workflow as descriptions. Users who do not have direct edit rights (e.g., those with a Reader role) can still propose a value for a structured property:

Navigate to the asset and open the structured property field.
Click Propose in the edit dialog instead of saving directly.
The proposed value is marked as pending on the asset until an owner, editor, or admin approves or rejects it.
Approvers review structured property proposals in the same interface used for description proposals.

By default, users with edit rights (Editors, Admins, and asset Owners) can set structured property values directly without a proposal step. Users without edit rights automatically follow the proposal workflow.

Alternative Options

Combine both texts in the editable description (manual or scripted): A script can read both the ingested aspect and the edited aspect via the DataHub API and write a merged result back. This requires re-running the script whenever the source description changes.

# Pseudocode: Merging ingested and edited descriptions via API
# 1. GET /openapi/v3/entity/dataset/{datasetUrn}/datasetProperties
#    → extract .description (ingested)
# 2. GET /openapi/v3/entity/dataset/{datasetUrn}/editableDatasetProperties
#    → extract .description (edited)
# 3. Compose merged text, e.g.:
#    "Source: <ingested_description>\n\nNotes: <edited_description>"
# 4. PATCH /openapi/v3/entity/dataset/{datasetUrn}/editableDatasetProperties
#    with the merged description value

Remove edited descriptions to restore ingestion as source of truth: If edited descriptions should be cleared so the ingested description shows again, use the OpenAPI v3 DELETE endpoints. No re-ingestion is required; the ingested description becomes visible immediately after deletion.
```
# Delete edited table description
DELETE /openapi/v3/entity/dataset/{datasetUrn}/editableDatasetProperties

# Delete edited column descriptions
DELETE /openapi/v3/entity/dataset/{datasetUrn}/editableSchemaMetadata
    
```
Use Documentation links or Glossary Terms for supplementary reference information that does not need to be inline text.

Additional Notes

This is expected product behavior, not a bug or regression. The separation of ingested and editable description aspects has been consistent across DataHub versions.
For assets with siblings (e.g., a Snowflake table linked to a dbt model), manual edits are applied to the primary sibling's editable aspect.
A "Restore to Source" button (which would reset the editable description back to the ingested value via the UI) is a known feature request but is not currently available.
Future DataHub versions may introduce improved priority rules for descriptions (e.g., handling blank edits or AI-generated descriptions), but simultaneous display of both description sources in one field is not on the current roadmap.
Structured properties are available in DataHub Cloud. Verify feature availability for your specific deployment version.
Notification settings for change proposal approvals should be reviewed and configured separately to ensure the right stakeholders are alerted when proposals are submitted.