Resource hierarchy

Taxonomy organises everything into three kinds of container: an organisation at the top, groups that act as folders within it, and workspaces that hold your resources. This page describes how they nest and the rules the service enforces.

The three resources

Organisation

An organisation is the root of the tree. It has no parent and sits above everything else. It carries a name and an owner, an identity from IAM. Every group and every workspace belongs to exactly one organisation.

Group

A group is a folder that organises workspaces within an organisation. Groups form a tree of their own: a group is either root-level, directly under the organisation, or a child of another group, and nesting can go as deep as you need. A group carries a name and an optional description.

Workspace

A workspace is the isolation boundary every other service builds on. It belongs to an organisation and may optionally sit inside a group; when it names no group, it rests directly at the organisation root. A workspace never contains other workspaces or groups, so it is always a leaf of the tree.

Containment rules

The service guarantees:

Single parent. A workspace belongs to exactly one organisation and at most one group. A group belongs to exactly one organisation and has at most one parent group.
No cycles among groups. A move is rejected if it would place a group inside itself or inside one of its own descendants, so the group tree stays acyclic.
Organisation-scoped moves. A group or workspace cannot move between organisations. Only its position within its organisation changes, by moving it to a different parent.

Why the hierarchy matters

Groups exist so that access control composes. An access binding granted on a group automatically covers every workspace placed inside it, so moving a workspace into a group is also an authorization decision, not just an organisational one. See the security baseline for scoping guidance.

Knowing what is inside

Reading an organisation or a group tells you how many scopes sit inside it, broken down by lifecycle state. This is what lets an interface draw the tree without asking about each folder in turn, and lets it tell a genuinely empty folder from one whose contents have all been archived.

Two figures are offered. The direct figure counts what is immediately inside — for a group, its child groups and the workspaces placed in it; for an organisation, its top-level groups together with any workspace that names no group and therefore rests at the organisation root. The subtree figure counts everything beneath the resource at any depth.

Each figure reports the three lifecycle states separately, and each child is counted by its own recorded state rather than one inherited from an ancestor. A folder is worth opening when its direct active and suspended counts together come to more than zero: an archived child still exists and is still counted, but it is not somewhere a reader will navigate. A folder holding nothing but archived children therefore reads as a leaf, while one holding a suspended child remains navigable.

The counts describe what you can see. A figure never exceeds what the same request would return if you opened that scope, so a reader whose access covers part of an organisation sees counts narrowed to their own view rather than the organisation’s true totals.

Asking for the subtree figure

The direct figure is always present. The subtree figure is computed only when the request asks for it, because summing a whole subtree is more work than counting one level and most callers never need it.

That opt-in carries one consequence worth knowing. A request for the subtree figure over an extremely large hierarchy is refused rather than answered with a partial count, and the refusal names the limit it reached. A partial total would be indistinguishable from a true one, which is the outcome the refusal exists to prevent. A request that does not ask for the subtree figure is unaffected.

Zero and absent mean different things. A subtree figure reporting zero means the request asked and the subtree is genuinely empty. A subtree figure that is absent means the request did not ask.