Skip to content

Config as source of truth

SEK’s central design decision is where a section’s structure lives. In SEK it lives in git-versioned YAML config in your theme, never in the database. The database holds only the values an editor typed. This split is the source of almost everything else SEK does.

  • Structure (what fields a section has, their types, their order, their validation, which template renders them) is declared in blocks/<handle>.yaml and the post-type configs. These are files in your theme, under version control.
  • Values (the headline someone wrote, the image they picked, the order they dragged sections into) are stored as JSON in the post’s _sek_data meta. Just the values, keyed by field handle. No structure, no HTML.

A page’s rendered output is the two halves combined at request time: the config says how, the stored values say what.

No database drift. Because structure is not stored per-post, there is no way for one page’s idea of “what a hero is” to diverge from another’s. Every hero on the site reads the same hero.yaml. Change the definition once and every instance reflects it: there is no migration to run just to add a field to a section type (see reconciliation for how existing values catch up).

Structure changes are code changes. Adding a field, renaming a handle, or swapping a template is an edit to a YAML file. It goes through the same review, the same pull request, and the same deploy as any other code. Your section definitions have a history, and you can roll them back.

Portability. The stored values are plain, structured JSON keyed by handle, not serialized HTML and not tied to a particular renderer. The same _sek_data could be rendered by a different template, or consumed by something other than the Blade layer, without a rewrite. Content is decoupled from presentation.

A safety net for edits. Because the config is authoritative, SEK can tell exactly which saved values still have a home when the config changes and which do not. It keeps the homeless ones instead of dropping them. That is lost values / Inactive Fields.

theme (git) database (per post)
──────────── ───────────────────
blocks/hero.yaml ── structure ──┐
config/post-types ── structure ──┼──▶ render ◀── values ── _sek_data (JSON)
blocks/hero.php ── template ───┘

If you remember one thing: the YAML is the truth about shape; the database is only the truth about content. When the two disagree (because you changed the config), the config wins, and SEK reconciles the stored values against it rather than the other way around.