Canonical identity and addressing for configuration states
PROPOSAL · Specification v2 — an early public proposal for discussion and experimentation, derived from implementation experience. Feedback and critique are welcome via GitHub Issues and Discussions.
A Stable Key is a compact, deterministic and transport-friendly address for one normalized configuration state in a defined configuration space. Its complete form, the canonical Stable Key, is that state's unique identity.
VALVE-DN050-PN16-EPDMStable Keys provide ordered, token-based state coordinates for use across APIs, caches and integrations. This document defines Stable Key Specification v2, which supersedes v1: a grammar, two identity and address rules, and a stated boundary. It is deliberately small enough that edge cases should be derivable from this core.
This work is licensed under CC BY 4.0.
Configurable industries have encoded configuration semantics into structured ordering codes for decades. HVAC, industrial automation, electrical engineering, pneumatics, valves and machinery all use compact token sequences because compositional identifiers scale with the number of coordinates without requiring every variant to be enumerated and named individually.
These codes originated in catalogs, ERP and procurement long before web APIs, but usually remain vendor-specific and are rarely exposed as formal interface identities. Stable Keys formalize this established pattern rather than inventing a new one. With a fixed grammar and a precise account of what a key denotes, it becomes usable across services, caches and integrations.
Stable Keys are defined within a configuration space: a scoped domain such as a product model, model series or catalog domain. It supplies the vocabulary and ordered coordinate model that gives a key its meaning.
A token is a compact ASCII identifier. In the grammar, a ProductToken names a configuration space; a canonical value token is a StructuredToken that the configuration space admits for one coordinate.
For Stable Keys to be defined, a configuration space specifies at least:
- its
ProductToken, which names the space; - its ordered coordinates, which define the positions of state values;
- the canonical value tokens each coordinate admits.
A normalized configuration state is an ordered vector containing, for every coordinate, exactly one canonical value token or explicit unset (_).
_ denotes explicit unset. It is neither a value token, a wildcard nor an omitted coordinate. A state may contain unset coordinates and is still one specific state.
Stable Keys operate on this already-normalized token state. Whether source values, unit expressions or external representations are equivalent before normalization is a question for the configuration space, not for this specification.
Throughout the examples below, VALVE is a space with three coordinates: nominal diameter, pressure rating and seal material.
VALVE-DN050-PN16-EPDM canonical: all coordinates set
VALVE-DN050-_-_ canonical: two coordinates explicitly unset
VALVE-DN050 short: addresses the same state as aboveThe canonical Stable Key of a normalized state writes the ProductToken followed by every coordinate, in order. It is that state's identity and its only complete, canonical spelling.
Within a configuration space, this is a bijection: every position is written and contains exactly one canonical token or _, so distinct states cannot share a canonical spelling and no state has two canonical spellings.
A short Stable Key omits a trailing run of coordinates. It addresses a state rather than providing a second identity: it expands by appending _ for each omitted position, and expansion is idempotent.
In the three-coordinate VALVE space, all of these address the same state:
VALVE-DN050
VALVE-DN050-_
VALVE-DN050-_-_VALVE addresses the all-unset state. Only the fully written form is canonical.
normalized state ↔ canonical Stable Key
short Stable Key → canonical Stable KeyThe arrows point one way for a reason: many addresses reach one identity, and one identity has one canonical spelling. Interior coordinates cannot be omitted; they must be written _.
A composite Stable Key joins two or more component keys with --. Each component key addresses a state in its own configuration space; the composite key addresses their ordered tuple, the composed state. Component order is significant.
Each component key may independently be canonical or short. Expansion is local to a component: it appends _ only up to that component's declared cardinality and never crosses a -- boundary. A composite Stable Key is canonical only when every component key is canonical.
In a composition of the three-coordinate VALVE space and a three-coordinate ACTUATOR space, for example:
VALVE--ACTUATOR
VALVE-_-PN16--ACTUATOR
VALVE--ACTUATOR-_-_-24VStableKey := ComponentKey ("--" ComponentKey)*
ComponentKey := ProductToken ("-" AttributeToken)*
ProductToken := StructuredToken
AttributeToken := "_" | StructuredToken
StructuredToken := [A-Z0-9]+ ("_" [A-Z0-9]+)*Stable Keys are ASCII-only, with at most 32 characters per StructuredToken. Each AttributeToken is one coordinate in the order defined by its space. -- joins component keys into a composite key for a composed state.
_ has two structural roles that cannot collide. A bare _ in attribute position denotes unset. Within a StructuredToken — whether used as a ProductToken or an AttributeToken — _ separates non-empty parts, as in VALVE_SERIES. VALVE_SERIES is valid; _VALVE, VALVE_ and VALVE__SERIES are not.
No token may be empty. Only strings that conform to this grammar are syntactically well-formed; this specification defines no preprocessing or alternative spellings. In a well-formed string, -- is therefore the component separator: VALVE-DN050--ACTUATOR contains two component keys, whereas VALVE-DN050- and VALVE-DN050-- are not well-formed.
-
Canonical identity. Within a configuration space, every normalized state is represented by exactly one canonical Stable Key, and every canonical Stable Key represents exactly one normalized state.
-
Right truncation. A non-canonical Stable Key may omit only a trailing run of coordinates within a component key. It expands by appending
_for each omitted coordinate. Interior omissions must be written_.
Grammar alone does not determine the state a key addresses. A grammar-conforming string addresses a state only within a configuration space that supplies matching product tokens, coordinate cardinalities and canonical value tokens. Whether the addressed state is permitted, complete or consistent with configuration rules is a separate question.
This specification does not prescribe how configuration spaces are modeled or governed. It defines identity and syntax, not product models, rule or resolution semantics, metadata, API behaviour, storage or transport.
- Stable Keys use URI-unreserved ASCII characters and can be embedded in an HTTP path segment without additional escaping.
- A Stable Key can be carried across systems that share a configuration-space contract. It remains stable as long as that contract preserves the meaning of its
ProductToken, coordinate order and canonical value tokens. - Compact, recognizable tokens support exchange, inspection and reference in human- and machine-assisted workflows. A deliberate coordinate order and separation from presentation concerns help preserve these properties.
- Typed values and units are normalized to canonical tokens by the configuration space, not encoded by Stable Key syntax.
- Stable Keys complement rather than replace product models, rule engines, ERP, PLM, CAD and classification systems by giving them a shared state coordinate.
- Defines canonical Stable Keys as the unique identities of normalized configuration states.
- Adds explicit unset, structured tokens and composite keys to the normative grammar.
- Defines right-truncated short Stable Keys as address aliases whose omitted coordinates expand only to unset.