Skip to content

Tag

User-defined label, optionally colored. Tenant-scoped: a tag belongs to the tenant that created it, so tenants never see each other's tag names. Rows with tenant = NULL are legacy deployment-globals from before scoping - visible to every tenant, writable only by superusers. Under enhanced site separation a tag can additionally be local to one site (owning_site).

Fields

Field Type Default Notes
id int autoincrement (taggit-managed)
tenant FK → Tenant NULL NULL = legacy global (superuser-managed)
owning_site FK → Site NULL NULL = global to the tenant; set = site-local
name char unique per tenant The visible label; see name rule
slug slug unique per tenant URL-safe
color char(7) "" Optional #xxxxxx

Name rule

The database constraint keeps name unique per tenant (the NULL-tenant bucket included). On top of it, TagManageSerializer.validate and Tag.clean refuse a create or rename whose name - trimmed, compared case-insensitively - already exists among the tags the tenant sees: its own (site-local ones included) and the global ones. A global tag is checked against every tenant. The error names the clashing tag and its scope. The check is forward-only: no constraint or data migration touches existing pairs, which are listed by GET /api/tags/duplicates/ and resolved with POST /api/tags/<id>/merge/ {"into": <id>} (see Tags & custom fields).

core.tags.find_visible_tag(name, tenant) is the lookup imports and syncs use to reuse an existing tag rather than create a second one of the same name.

Picker and management responses carry is_global (tenant is NULL).

Rendering

Tag has Renders as
color = "" (colorless) Neutral zinc-100 chip
color = "#10b981" etc Solid colored chip with computed black/white text

Text color is computed from sRGB luminance:

@property
def text_color(self) -> str:
    if not self.color:
        return ""
    h = self.color.lstrip("#")
    r, g, b = int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)
    luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255
    return "#000" if luminance > 0.6 else "#fff"

Threshold of 0.6 biases slightly toward black text on light backgrounds (e.g. amber gets black text, emerald gets white).

TaggedItem

Custom core.TaggedItem(GenericUUIDTaggedItemBase) - needed because all our content models have UUID PKs and taggit's default IntegerField object_id would overflow.

Config-context matching

api.ConfigContext.tags is a plain many-to-many to core.Tag (not a TaggedItem): the tags a config context matches on, the context's tenant's own only. A merge moves those matches onto the tag merged into; a delete removes them.

Scoping history

Tags started as one global taggit table. Tenant scoping landed with the enhanced-site-separation work: a data migration stamped each tag with the tenant(s) actually using it, cloning tags shared by several tenants and re-pointing that tenant's TaggedItem rows, so nobody lost a tag and nobody kept seeing another tenant's.