Configuration Axis

Origin & evolution

Feature⭐FeatureProduct SpecificationA product capability or featureView reference → toggles gave teams a way to ship code that is present but inactive. The useful distinction in Martin Fowler's account is between the short-lived release🚢ReleaseProduct SpecificationA shipped version of the productView reference → toggle, which exists to be removed, and the long-lived permission or ops toggle, which becomes part of the product's shape and never goes away. Plan tiers, permission levels and beta programmes reached the same shape from other directions: each is a lever that changes what a customer's product actually contains.

Software product line engineering had already named the general problem. A family of related products is better modelled through explicit variation points than through a branch per variant🆎VariantGrowthA variant in an A/B testView reference →, because the branch-per-variant approach makes every shared fact a thing you maintain several times. What none of these supplied was a place to write the family down that a product model could read. A toggle lives in the deployment📤DeploymentEngineeringA deployment eventView reference → system, a tier lives in billing, and a product model showing one configuration inherits an unstated condition from both.

The configuration axis lifts the lever into the graph, one axis per semantic decision⚖️DecisionStrategyA recorded decision with context, rationale, and consequencesView reference → rather than per mechanism. The consequence worth stating is the zero-migration guarantee: a graph that declares no axis describes a product with one configuration, which is exactly what every graph written before the type existed already meant. Silence still means true everywhere.

How it works in practice

A team is halfway through a navigation change. Half the product model describes the new sidebar, half still describes the old one, and neither half says which is which. A new joiner reads the graph and builds against a navigation that only a third of accounts see. The usual fix is a note in a description field, and the usual outcome🏆OutcomeStrategyA desired business or user outcomeView reference → is a note that is true for six weeks.

Modelled as an axis, the lever gets a name, a closed set of values, and a link to the flag that drives it. The two navigations both stay in the graph and each declares which values it is present_under. Nothing about the product changes that day. What changes is that an unqualified read now returns the union honestly, and a reader who wants one configuration asks for it by name instead of inferring it from which half of the model somebody wrote most recently.

The rule that saves the most trouble is one axis per semantic lever, not one per code flag. Two flags that cannot be set independently, where one forces the other on, are one axis with two values. Modelling them as two axes asserts a four-configuration family of which three members do not exist, and the arithmetic compounds: five independent axes claim thirty-two configurations. Link each driving flag with feature_flag_drives_configuration_axisFeature FlagdrivesConfiguration Axiscross-domain. The mechanism lives in engineering; the lever lives here.

Configuration axis vs. its neighbours

• Classification axis↔️Classification AxisMarket IntelligenceA single dimension in a competitive classification matrix that defines one axis of comparison across alternatives.View reference → sorts subjects into cells. A subject may sit in several at once, each placement carries evidence🔎EvidenceValidationData supporting or refuting a hypothesisView reference → and confidence, and the axis describes a landscape. A configuration axis selects which graph you are reading: exactly one value holds at a time, placements carry no evidence, and changing the value changes what exists. The shapes rhyme and the questions do not, which is why the same field names would be a trap.
• Feature flag🎌Feature FlagEngineeringA feature toggle for controlled rolloutView reference → is the mechanism, not the lever. It is a real thing in a deployment system with a rollout percentage and a kill switch, and several flags can drive one axis. Recording flags alone leaves the model with a list of booleans and no statement of what decision they add up to.
• Variant belongs to experimentation: one arm of a test, alive for the length of the experiment🧫ExperimentValidationA test designed to validate a hypothesisView reference → and then retired in favour of a winner. A configuration axis outlives any experiment, because a plan tier or a permission level is a permanent property of what the product is.

In the graph

In the Unified Product Graph, configuration_axis🎚️Configuration AxisProduct SpecificationA named dimension along which the product's composition differs: a feature flag, a plan tier, a permission level, a beta programme. The stored graph is the union of the family; one configuration is a projection of it. sits in the Product Spec domain and hangs off the product that defines it through product_defines_configuration_axisProductdefinesConfiguration Axishierarchy. Inbound, feature_flag_drives_configuration_axisFeature FlagdrivesConfiguration Axiscross-domain names the mechanism and surface_varies_by_configuration_axisSurfacevaries byConfiguration Axiscross-domain names what changes along it. Structural relationships are edges, per the P14 principle, so the axis holds no list of the things that vary; it holds only its own values and its kind.

Three marking mechanisms hang off it, and choosing between them is most of the work. present_under is for a thing that only exists under some values. active_when is for a relationship that changes while both of its ends persist. surface_alternates_with_surfaceSurfacealternates withSurfacesemantic is for a one-of-these-depending pair, declared from the surface present under the default value. validate_graph enforces the closed-values rule under its configuration_drift scope, which is the check that keeps a projection meaningful: an axis whose values are open cannot support one, because nothing bounds the family being projected from.