Stable Keys

Canonical Identifiers for Semantic Configuration States

PROPOSAL This document is an early public proposal for discussion and experimentation.

"Stable Keys" is intentionally scoped as a minimal specification for canonical identity and addressing of semantic configuration states.

It may be relevant for engineers, architects and system designers working with configurable systems, industrial product models, configuration APIs, CPQ systems or distributed engineering workflows.

This document should be understood as:

• a conceptual proposal,
• a draft specification,
• and a foundation for further discussion and implementation experience.

The current document already defines a small but normative core specification ("Stable Key Specification v1"), including grammar, invariants and explicit non-goals.

Feedback, critique and implementation experience are welcome via GitHub Issues and Discussions.

This work is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).

A Stable Key is a canonical identifier for exactly one semantic configuration state within a scoped semantic configuration space (such as a product family, model series or catalog domain).

Example:

AXV-R-DN050-PN16-SS316-EPDM-24VAC-IP65

The key consists of semantically meaningful segments and compact token values representing configuration semantics within the corresponding configuration space.

Across industrial sectors, configurable systems have long been represented through structured ordering codes and model identifiers. HVAC systems, industrial automation, electrical engineering, pneumatics, valves, machinery and related domains routinely encode configuration semantics into compact token sequences.

Historically, these structures emerged from catalog, ERP, BOM and procurement workflows long before modern web APIs, distributed service architectures or AI systems existed. Despite their ubiquity, such identifiers are usually vendor-specific, only partially machine-readable and rarely treated as formal interface primitives.

Stable Keys formalize this long-established industrial pattern into a minimal, transport-safe and semantically deterministic identity grammar suitable for modern distributed systems.

Stable Keys are intended to provide deterministic identity and stable addressing for semantic configuration states across APIs, distributed systems and AI-assisted configuration workflows.

The underlying observation is straightforward:

Industrial sectors have already spent decades evolving stable semantic configuration identifiers.

Stable Keys attempt to preserve the strengths of these systems while making them directly usable as canonical HTTP resource identifiers, interoperability identities and machine-processable semantic token structures.

Stable Keys intentionally address a narrow problem domain:

stable and deterministic identity for semantic configuration states in large variant spaces.

They intentionally build upon long-established industrial ordering code conventions and vendor-specific configuration identifiers rather than attempting to replace them.

Stable Keys do not define:

• taxonomies,
• ontologies,
• property semantics,
• engineering schemas,
• rule systems,
• transport protocols,
• or storage formats.

They operate orthogonally to existing engineering and enterprise systems, including:

Stable Keys are not intended to replace these systems.

They provide a lightweight semantic identity layer that can coexist with existing engineering, API and enterprise architectures.

A semantic configuration space defines:

• valid configuration states,
• segment semantics,
• token semantics,
• validation rules,
• and canonicalization strategies.

Stable Keys intentionally do not standardize these internal semantics.

The first segment of a Stable Key identifies exactly one semantic configuration space.

Example:

VALVE-DN050-PN16-SS316

In this example, VALVE identifies the semantic configuration space in which all following segments and tokens are interpreted.

Each segment contains a token value.

Tokens may represent:

• dimensions,
• materials,
• connection types,
• mounting variants,
• electrical properties,
• performance classes,
• or other configuration semantics defined by the configuration space.

Stable Keys intentionally do not prescribe token meaning or modeling strategy.

Compact and semantically recognizable token structures are strongly encouraged for interoperability, readability and AI-assisted processing.

Stable Keys are intentionally designed for direct use within RESTful and resource-oriented systems.

Typical applications include:

• HTTP resource paths,
• cache keys,
• resolver inputs,
• interoperability identifiers,
• and distributed configuration APIs.

Example:

GET /configure/AXV-R-DN050-PN16-SS316-EPDM-24VAC-IP65

A Stable Key identifies a concrete semantic state — not a query, recommendation or partial configuration.

This distinction is intentional: Stable Keys are designed around identity semantics rather than search semantics.

The current specification should be considered experimental and subject to change based on implementation experience and discussion.

A Stable Key consists of uppercase alphanumeric segments separated by hyphens.

Example:

AXV-R-DN050-PN16-SS316-EPDM-24VAC-IP65

Grammar:

StableKey := Segment ("-" Segment)+

Segment := [A-Z0-9]+

Within a semantic configuration space, each semantic configuration state MUST have exactly one canonical Stable Key representation.

Equivalent alternative representations MUST NOT exist.

This invariant is satisfied through the canonicalization strategy defined by the semantic configuration space.

Stable Keys v1 intentionally do not define a global normalization standard.

Within the same semantic configuration space, the same Stable Key MUST always identify the same semantic configuration state.

Stable Keys SHOULD preserve stable semantic identity across:

• APIs,
• catalogs,
• integrations,
• user interfaces,
• caches,
• and distributed service boundaries.

Stable Keys are intended to represent configuration identity independently from transport, storage or presentation concerns.

All segment and token semantics are defined exclusively within their semantic configuration space.

Stable Keys do not imply globally standardized semantics across organizations or domains.

Stable Keys MUST consist exclusively of:

• uppercase letters A-Z,
• digits 0-9,
• and hyphen - as segment separator.

No additional characters are permitted in v1.

This restricted character set is intentionally chosen for:

• URL safety,
• filesystem compatibility,
• copy/paste robustness,
• OCR readability,
• shell safety,
• case-insensitive interoperability,
• and long-term transport stability across heterogeneous systems.

Stable Keys v1 intentionally do not define:

• wildcard semantics,
• partial identities,
• truncation semantics,
• query syntax,
• inheritance semantics,
• versioning semantics,
• cross-space normalization,
• ontology semantics,
• or global semantic registries.

The following design strategies are strongly recommended where practical:

• deterministic segment ordering,
• stable segment cardinality,
• short and human-scannable token values,
• semantically recognizable abbreviations,
• canonical normalization strategies for units and numeric values,
• avoidance of presentation-specific semantics.

These recommendations are intentionally non-normative and may vary between configuration spaces and industrial domains.

Different organizations and industries may adopt different canonicalization strategies while still conforming to the core Stable Key invariants.