Skip to content

CONCEPT Cited by 1 source

Register-based client capability matching

Definition

Register-based client capability matching is the server-side mechanism that decides, per feature, whether the requesting client can render that feature, by matching the client's declared capabilities (platform, app version, supported components and actions) against a list of Register entries declared by the feature. The first register whose Condition is satisfied wins; if none match, the feature is omitted from the response.

This is how an SDUI system safely ships new components without breaking old app versions: the old client simply doesn't match any register that requires the new component, and the feature is dropped (or a fallback register picks a compatible variant).

The shape (per Yelp CHAOS)

Verbatim from the 2025-07-08 post: each register specifies

  • Platform — "The platforms (e.g., iOS, Android, web) for which the registered configuration is intended."
  • Elements — "The required components and actions in this configuration that the client must support. Internally, we maintain information about which components and actions supported by a given client platform type and app version, which is used for verification."
  • Presenter Handler — "The associated handler (e.g., result_presenter) responsible for constructing the configuration if all conditions are met."

And the decision rule: "the presenter handler of the first qualifying register is selected to build the configuration. If no register qualifies, the feature is omitted from the final response."

Concretely in code (CHAOS):

Register(
    condition=Condition(
        platform=[Platform.IOS, Platform.ANDROID],
        library=[TextV1, IllustrationV1, ButtonV1],
    ),
    presenter_handler=self.result_presenter,
)

Multiple registers per feature encode fallbacks: the highest- priority (richest) variant is listed first; lower-priority variants with fewer required elements follow.

Why it's different from feature flags

Feature flag Register
Scope user / cohort / tenant client capabilities
Typical gate is this user in group X? does this client support these components?
Failure mode feature simply off feature falls through to next register, or omitted
Placement in build boolean check in application logic first-class stage of the SDUI build pipeline

The two compose — a feature flag can gate which register variant is advertised, while registers gate whether any variant is renderable for this client.

Why it's different from content negotiation

HTTP content negotiation (Accept headers, per concepts/markdown-content-negotiation) is about picking one representation of a single resource. Register-based matching is about the inclusion / exclusion of a whole feature in a composed page based on a vector of capabilities (platform × version × element library). The two solve adjacent problems; registers are the SDUI-specific evolution.

Hard problems

  • First-match is order-sensitive. Developers must list most-specific (richest) registers before fallbacks; a bug in ordering silently ships the wrong variant.
  • Capability manifest is a source of truth. The backend needs an accurate mapping from (platform, app version) → (supported components, supported actions). Errors here are silent — a client gets a feature it can't render, or is incorrectly denied one.
  • Register leakage across features. Features that share components often want to share register entries; the pattern offers no native composition mechanism.
  • Tail app versions decay indefinitely. Long tail of very old app versions means many features permanently drop for them; teams need a policy on when to stop supporting old capabilities.

Seen in

Last updated · 476 distilled / 1,218 read