Skip to content
Almathal Handbook

ADR-0007: Typed Variation Points

Accepted

Date: 2026-06-10

Context

An Archetype’s user-configurable choices (database, entity definitions, auth provider, etc.) can be expressed as:

  • Option A: Flat key/value overrides. Simple, but no typing, validation, or UI hints.
  • Option B: Typed Variation Points with explicit type, constraints, defaults, and UI hints.

The hybrid form-plus-conversation input model (ADR-0011) needs structured information about each Variation Point to render form fields automatically and validate user input.

Decision

Variation Points are typed and constrained. Each Variation Point declares:

  • Identifier
  • Type (enum, user_defined_list, string, integer, boolean, etc.)
  • Options/constraints (enum values, min/max, regex, schema reference)
  • Default value
  • UI label and help text

The form UI for an Archetype is auto-generated from its Variation Point declarations.

Rationale

  • Auto-generated forms stay in sync with Archetype evolution; manually maintained forms drift.
  • Typed validation catches errors at input time rather than during generation.
  • UI hints localize without requiring separate translation files.
  • Standard JSON Schema patterns apply directly.

Consequences

  • Archetype authoring includes form UX design as a first-class concern.
  • The Resolver’s input handling becomes type-aware.
  • A small library of Variation Point types exists in the platform; new types are added when needed but require an ADR.

References