Skip to main content

Attributes & the Registry

Attributes are how GEM stores nearly everything that varies per entity. A single mechanism carries both configuration (a device's IP address, a zone's relay mapping) and live runtime state (current brightness, temperature, online status).

What an attribute is​

An attribute is a named value attached to a target:

(target_type, target_id, name) → value

For example, (device, 7, ip_address) → "192.168.1.50" or (zone, 12, brightness) → 50. Attributes have a value type (string, integer, boolean, JSON, …) that governs how they're cast.

Because configuration and state share one mechanism, the same tools read both — gem.getAttribute(...) / gem.setAttribute(...) work uniformly, and live values are merged onto the in-memory entity objects (see Architecture).

The Attribute Registry — a schema of meaning​

The attribute registry is a catalog describing what each attribute means, per (target, name, context). Each entry can specify:

  • value_type — how the value is cast and edited.
  • description and category — documentation and grouping.
  • default, value_options — a default value and a fixed option list.
  • secure / readonly / history flags.
  • unit — for display.
  • option_source — a rule for populating a dropdown dynamically (from settings, a table query, or a device command).

The registry is what lets the admin UI auto-fill an attribute's type and hints, and what lets the AI assistant read attribute semantics instead of guessing from names. It's seeded at boot from a source-of-truth seed file and diffed against the database on each start.

:::note readonly means "locked from the UI," not "runtime state" A readonly attribute is configuration that shouldn't be edited from the UI — it's still configuration, and belongs in exports and migrations. Don't confuse it with secure (which is excluded from some flows because it's encrypted). :::

Dynamic options — option_source​

Rather than hardcoding dropdown choices, a registry entry can declare where options come from:

  • static — a fixed list.
  • settings — a dot-path into gem.settings.
  • query — a table query (value/label/meta fields).
  • command — a device command whose response yields the options.

The same DSL drives both registry-backed attribute editors and widget metadata dropdowns, through one shared resolver.

Secure attributes​

Attributes whose names look sensitive (password, api_key, private_key, …) — or any attribute explicitly marked secure — are encrypted at rest. See Secure Attributes.