Tag groups and tags

A tag group is a dimension your configuration varies along. A tag is one of the values that dimension can take.

Environment ──┬── Production
              ├── Staging
              └── Development

Region ───────┬── EU
              └── US

Tier ─────────┬── Free
              └── Enterprise

Naming

A tag is always referred to as Group/Tag:

Environment/Production
Region/EU
Tier/Enterprise

The group is part of the name because a bare tag name is not unique. Production could belong to Environment or to a later Deployment group, and the qualified form settles it before the ambiguity can ever arise.

Group names are matched case-insensitively; tag names within a group are matched case-sensitively. So environment/Production finds the group, and Environment/production does not find the tag.

Choosing dimensions

The rule of thumb: a tag group is worth creating when values genuinely differ along it, and not before.

Good dimensions are ones where you can say what every value in the group means without reference to another group — Environment, Region, Tenant, Tier.

A poor dimension is one that is really two. A group holding ProductionEU, ProductionUS, StagingEU is a Environment group and a Region group that have been flattened into one, and flattening them costs you the partial matching that makes resolution useful: nothing can be tagged "production, any region".

Tags on a value

A value carries a set of tags, drawn from any number of groups. Nothing requires a value to name a tag from every group, or more than one from a group — though tagging a value with two tags from the same group means it applies when both are asked for, which is rarely what anyone wants.

The important constraint is enforced at write time: no two values of the same variable may carry the same combination of tags. A duplicate combination is refused with 409 Conflict, because it would leave resolution with two equally good answers and no way to choose.

API

Action	Endpoint	Permission
List tag groups	GET /taggroups	TagGroupList
Read one, with its tags	GET /taggroups/{id}	TagGroupRead
Create a group	POST /taggroups	TagGroupCreate
Update a group	PUT /taggroups/{id}	TagGroupUpdate
Delete a group	DELETE /taggroups/{id}	TagGroupDelete
List tags	GET /tags	TagList
Create a tag	POST /tags	TagCreate

Full detail in the library set API reference and API permissions.

POST /taggroups

{
  "name": "Environment",
  "description": "Where the code is running"
}

POST /tags

{
  "name": "Production",
  "tagGroupId": 1
}

Deleting

Deleting a tag group cascades to its tags, and the rows joining a value to a tag cascade from either side — so deleting a group takes its tags off every value carrying them without orphaning anything. A value left with no tags becomes the untagged default for its variable, which may not be what you intended; check before deleting a group that is in use.