Skip to main content

Core concepts

Everything in TagShape hangs off six ideas.

The model at a glance​

Organization
├── Tag group  "Environment"          ← a dimension configuration varies along
│   ├── Tag    "Production"           ← a value that dimension can take
│   └── Tag    "Staging"
├── Tag group  "Region"
│   ├── Tag    "EU"
│   └── Tag    "US"
└── Library set  "orders-service"     ← what a consumer fetches as a unit
    └── Variable  "DatabaseConnection"
        ├── Value  "Server=localhost..."     tags: []
        ├── Value  "Server=prod..."          tags: [Environment/Production]
        └── Value  "Server=eu-prod..."       tags: [Environment/Production, Region/EU]
ConceptWhat it is
OrganizationThe tenancy boundary. Every record belongs to exactly one, and nothing crosses.
Tag groupA dimension your configuration varies along.
TagA value within a dimension. Written Group/Tag.
Library setA named grouping of variables, fetched as a unit. Called a variable set in the code and API.
VariableA named thing inside a library set that holds one or more values.
ValueOne concrete string, plus the tags under which it applies, plus whether it is sensitive.

Why tags rather than files​

The alternative to tags is a file, or a key prefix, per combination. That works until the combinations multiply. Three environments and two regions is six files; add a tier and it is eighteen, of which perhaps four actually contain anything different.

Tags invert it. You store a value once for each combination that genuinely differs, and TagShape works out which one applies at the moment you ask:

  • One default value, no tags — used when nothing more specific matches
  • One value tagged Environment/Production — used everywhere in production
  • One value tagged Environment/Production + Region/EU — used in the EU only

Three values cover all six combinations, and adding a region adds nothing until it needs to.

The rule that makes it work​

Resolution is a single, deliberately small rule: the value matching the most of the tags you asked for wins, and the untagged value is the fallback. There is no inheritance chain, no precedence order between tag groups, no override syntax. Whichever value knows most about where you are is the one you get.

Where identity fits​

Everything above sits inside an organization, and reaching any of it needs a token. A person gets one by signing in through their organization's identity provider; a machine gets one by presenting an API key. Either way the token carries the same claims: who you are, which organization, and the numeric permissions you hold.

What those permissions let you reach is set out endpoint by endpoint in API permissions.