Skip to content

CONCEPT Cited by 1 source

Client spec version

Definition

A client spec version is a bundled-with-the-client manifest that lists, as data, the versions of every component interface the client can handle. At request time the client sends its spec identifier (e.g. android@23.0) to the server; the server consults the named spec and sends only component versions that the client can decode.

{
  "version": "23.0",
  "interfaces":    { "cookbook.Button": "1.0" },
  "enumerations":  { "cookbook.ButtonStyle": "0.1" }
}

The spec file is bundled into the generated client library (and pinned to the app-build that shipped it). Every running app version therefore advertises a fixed, known capability surface — no dynamic negotiation, no probing.

Canonical wiki instance (Yelp Konbini)

Konbini generates a spec file per platform and bundles it into the four generated libraries. Verbatim: "Each client (Android/iOS/Web) has a spec file that includes a version number and lists all supported components with their versions ... The spec file is saved inside the Konbini repository and gets bundled into all of the four generated libraries. Whenever a new component is updated or created, it must be included in the spec so that the classes for it get generated. At the same time, when there's any change made to a spec, its version has to be bumped."

At request time, a Konbini context object is passed carrying spec_name@spec_version (e.g. android@23.0). Backend reads that spec, picks compatible component versions, and — if the backend wants to send a newer major than the client's spec allows — invokes the migrate function to backport.

Comparison with feature flags

Feature flags vary per-user and change at runtime; spec versions vary per-app-build and are fixed for the lifetime of that build. The two address different problems:

  • Feature flag — "does this user get this feature?" — rollout + experimentation.
  • Spec version — "does this app build speak this component's new shape?" — schema-compatibility + rollout.

They compose: feature flags gate whether the new component is even attempted; spec version decides which shape is sent.

Comparison with Register-based client capability matching

Yelp CHAOS has another client-capability mechanism — Register-based matching — that operates at feature-provider granularity: each register declares a required set of platform × component classes × action classes, and the backend picks the first register whose condition is satisfied. Spec versions operate at component-version granularity and are a cross-cutting substrate that Register conditions sit on top of. Register decides which feature to serve; spec-version decides which version of each component in that feature.

Why bundling the spec into the client matters

  • No round-trip to discover capability. The server knows the client's capability surface purely from the spec ID.
  • Fixed-at-build-time is auditable. Every app on every phone of every user is running a known spec; diagnostic tooling can reason about the fleet as a distribution over spec versions.
  • Immutable per app version. The spec can't shift under the running app; version drift is a separate deploy event.

Spec-file vs component-version bump rules

  • Component major version bump (e.g. Button 0.8 → 1.0) → the spec file for each platform that now speaks the new version must be updated; the spec-file's version also bumps.
  • New component added → every platform's spec file must include it (at some version), or that platform will not generate the class.
  • Component removed from a spec → clients on specs that no longer reference the component will not receive it.

Yelp: "when there's any change made to a spec, its version has to be bumped."

Preconditions

  • Stable spec naming scheme. Platform name android, ios, web + monotonic numeric version is enough. Yelp uses android@23.0.
  • Backward-compat story for each major-version transition. A spec version that still references CookbookButton: "0.8" when the backend wants to ship "1.0" is only safe if a migrate is implemented and registered.
  • Release-train coordination. When a new spec version publishes, some users take days/weeks to upgrade. The spec version's existence means old clients keep working — but the backend has to hold compat for however long the app-deprecation window is.

Seen in

Last updated · 550 distilled / 1,221 read