Skip to main content

Manage the tag taxonomy

Goal​

You'll define an organization-wide controlled vocabulary of tags — classifications like PII, Financial, or Restricted — so everyone tags data assets from the same agreed set instead of typing free text. A governed tag set keeps classification consistent (PII vs pii vs personal stops being three different tags) and makes filtering and reporting by tag meaningful.

Prereqs​

  • You're a super admin. The Tags settings page and the create / edit / delete endpoints are gated to the super admin — a workspace admin, technical admin, editor, or viewer can't curate the taxonomy. (Anyone who can edit an asset can still pick from the defined tags.)

Steps​

  1. Navigate to Settings → Tags. Other roles don't see this tab; anyone else who deep-links to it gets a clear "you don't have permission" banner rather than a broken form.

  2. Click "New tag". Give the tag a name (for example PII), an optional colour (a #RRGGBB hex used to colour the tag's chip), and an optional description explaining what the classification means. Click Create.

  3. Edit a tag with the pencil button on its row — you can rename it or change its colour/description. Names are unique per organization case-insensitively, so you can't define both PII and pii.

  4. Delete a tag with the trash button. Deleting a tag removes it from the taxonomy so it's no longer offered when tagging new assets — but assets already tagged with it keep the tag (it just reads as a legacy/unmanaged tag). This keeps delete non-destructive to historical classification.

  5. Tag an asset from the vocabulary. Open a data asset's editor (Data Assets → an asset → Edit). The Tags field is now a searchable picker constrained to your taxonomy: search, then click a tag to add it as a chip. There is no free-text add — new tags always come from the vocabulary you defined here.

Verify​

  • Settings → Tags lists the tags you created, each with its colour swatch and description.
  • Open an asset editor and confirm the Tags field offers exactly your defined tags (and search filters them).
  • Ask a teammate who isn't a super admin: they can pick tags on an asset, but their Settings has no Tags tab and they can't add a new tag to the vocabulary.

Notes​

  • Scope is per-organization, not per-workspace. A tag taxonomy is a governance classification applied consistently across every workspace, so it's defined once for the whole org. The tags live in a tenant-schema tag_definitions table isolated by org.
  • Backward compatible. The taxonomy is additive. An asset's tags stay a plain list of strings on the wire, so existing integrations don't change. Tags that were applied as free text before the taxonomy existed still display on their assets — they just can't be re-added from the picker once removed. The API does not reject an asset write whose tag isn't in the taxonomy; the vocabulary is enforced at the point of entry (the asset editor), not as a hard constraint on read.
  • See #221 for the tracking ticket and the API reference (the Tags (taxonomy) row) for the endpoint shapes.