Skip to content

Schema and Configuration Generator

Generator tool — instantiates Specification-to-Execution Lowering

Generates the static declarations a system stands on — database schemas, validation schemas, config files — from a single higher-level model, so they can never drift out of sync with it.

A running system is surrounded by static declarations that must agree with one another — the database's table definitions, the API's request-validation schema, the config that wires it together. Hand-maintained, they drift: someone adds a column but forgets the validation rule. A Schema and Configuration Generator lowers a single higher-level model (a data model, a service descriptor, a set of typed definitions) into all of those artifacts at once, so they are correct relative to the model by construction and stay in step because they share one source. Its defining commitment — the thing that makes it more than a snippet library — is that the generated files are owned by the generator: they are outputs, not source, never hand-edited; you change the model and regenerate. That ownership rule is what keeps the guarantee true over time.

Example

An e-commerce team keeps one model of its Order domain — fields, types, required-ness, allowed states. From it, a single generator run emits three declarations: the Postgres DDL (tables, columns, NOT NULL and foreign keys, a CHECK on order status), a JSON Schema the API gateway uses to reject malformed order payloads before they reach the service, and a config file mapping environment-specific values such as per-environment connection-pool sizes. Each generated file carries a banner — "Generated from order.model — do not edit; run make schema" — and lives in a directory the build regenerates. When the team adds a gift_message field, they add it once, to the model; the column, the validation rule, and the config default all appear together on the next generate. The bug that used to bite them — an API accepting a field the database has no column for — is now structurally impossible, because both declarations descend from the same source. To keep it that way the generator is idempotent: regenerating an unchanged model produces byte-identical files, so the artifacts are safe to commit and diff.[1]

How it works

  • Read one model. A single higher-level description of the domain or service is the source of truth.
  • Project to each target's declaration form. Emit each artifact in its own language — DDL, JSON Schema, config format — from the shared model, so all of them agree by construction.
  • Fold in implementation context. Apply environment- and platform-specific values (dialect, sizes, defaults) so the generated files are deployable, not abstract.
  • Own the output. Mark generated files as generated, keep them out of hand-editing, and make regeneration idempotent so it is safe to run at any time.

Tuning parameters

  • Generation scope — how many artifact kinds one model drives (just schema, or schema + validation + config + docs). Wider scope multiplies the drift it prevents but couples more targets to one model's shape.
  • Escape-hatch policy — whether hand-written overrides are allowed beside generated files, and how they merge. Escape hatches absorb what the model can't express but reopen the drift door if they touch generated regions.
  • Regeneration discipline — regenerate-on-build vs. regenerate-and-commit. Building fresh guarantees sync; committing generated files makes diffs and history reviewable but tempts hand-edits.
  • Model expressiveness — how much the source model can state (constraints, defaults, relationships). A richer model captures more in one place but is more to learn and maintain.

When it helps, and when it misleads

Its strength is that it eliminates a whole class of drift-and-mismatch bugs by construction, makes one change to the model propagate everywhere in a single step, and turns "keep these five files in agreement" from a standing discipline into a build step nobody has to remember.

Its failure modes cluster around the ownership rule. The generator can only express what the model can express, so teams reach for escape hatches — and a hand-edit to a generated file is either silently erased on the next run or, worse, quietly preserved and allowed to drift, defeating the entire guarantee. A too-rigid generator forces awkward models to fit its templates. The classic misuse is editing the generated artifact "just this once" because changing the model is inconvenient — which breaks the single-source-of-truth the tool exists to protect. The discipline is the ownership rule enforced, not merely stated: generated files marked, checked, and regenerated, with genuine exceptions handled through sanctioned overrides rather than edits in place.

How it implements the components

  • constraint_set — the generated schemas are constraint sets: NOT NULL, foreign keys, CHECKs, JSON-Schema required/format rules, all projected from the model.
  • implementation_context — the environment- and platform-specific values (dialect, sizes, defaults) folded in so the output is concrete and deployable.
  • generated_artifact_ownership_rule — its signature: generated files are outputs owned by the generator, never hand-edited, kept in sync only by regeneration.

It does not emit running behaviour — the executable rule set that decides a case (executable_realization — that's Policy-to-Rule-Engine Compilation) or the orchestrated process with its task decomposition (obligation_decomposition_map — that's Workflow-Model Compiler); a generator emits the static declarations a system stands on, not its behaviour.

Notes

This generates a system's static declarations — schema, validation, config — from a model. Provisioning and wiring the actual infrastructure from a model is Infrastructure-as-Code Generation, a distinct sibling. The two are easily confused because both "generate config," but one describes data and its shape and the other describes machines and their wiring; a generator that starts emitting cloud resources has quietly become the other mechanism.

References

[1] Idempotence — running the generator again on unchanged input yields an identical result — is what makes generated artifacts safe to commit, diff, and regenerate on every build. Without it, regeneration produces spurious churn, teams stop trusting it, and hand-editing the output becomes the path of least resistance — the first step toward the drift the tool was meant to prevent. ↩