- Type safety — a config defines the fields it contains and their types. Anything that uses the config is checked against that definition.
- Validation — values that don’t match the schema are rejected at edit time, before they ever reach an SDK payload.
- Composability — a config can extend another config, layering fields on top of an inherited base. You can then attach a config to a feature flag as the flag’s value, so the config’s shape is enforced on that flag.
- Import/export of values — pull a config’s value in or out as JSON.
- Import/export of type definitions — pull a config’s schema in or out as JSON Schema or TypeScript.
Anatomy of a config
A config has:- A key — a slug auto-generated from the name (e.g. “Checkout Flow” →
checkout-flow), used to reference it. - A value — a JSON object.
- A schema — the field definitions (names, types, required/optional, bounds, enums, nullability) the value is validated against.
- An optional parent — another config’s key. The config inherits the parent’s fields and value, then layers its own on top.
- Optional environment overrides — per-environment (and optionally per-project) patches layered on top of the base value, covered in Environment overrides.
Type safety and validation
A config’s schema is the source of truth for its shape. The editor builds it for you as you define fields, and validates the value against it on every save: a wrong type, an out-of-range number, or a value outside an allowed enum is rejected before it can be saved, and a missing required field is rejected when the config publishes. A draft is checked against what it would publish, using its own schema, parent, mixins, and Allow extra fields setting, in the app and over the REST API alike. By default a config allows extra fields: keys its schema doesn’t declare are accepted, and the typed fields are still validated. Turn off Allow extra fields on a base config to accept only declared keys, in its own value, its child configs, and the feature flag rules that use it. Your organization sets the default for new base configs.Composability and inheritance
A config can name another config as its parent. The child inherits the parent’s fields and value and layers its own on top — like extending a base type. Inheritance is resolved when the SDK payload is built, so children always reflect the latest parent. Precedence, lowest to highest:- The parent chain, root first (each ancestor’s value, then schema)
- The config’s own value and schema
"ignoreWarnings": true through the REST API. A scheduled publish fails instead.
Values layer as a deep (targeted) patch: when a child and its inherited value are both objects, they merge recursively, key by key, so a child restates only the leaves it changes and inherits the rest of a nested object. Arrays and scalars replace wholesale (arrays are never merged element-by-element), and null is a value (it sets the field to null, it does not delete it). A value composed from a constant via $extends is applied whole — the patch never reaches inside a referenced chunk. Constants compose the opposite way: a constant’s own keys replace what its $extends bases provide, wholesale — configs and feature values patch; constants are atomic building blocks.
A config’s value can also interpolate string constants with {{ @const:key }} inside any string field, exactly as in feature values — including constants with per-environment overrides, another way to vary a config’s value by environment alongside environment overrides.
On a config’s page, the left rail shows its family tree (ancestors and descendants), the configs that use it as a mixin, and the Feature Flags that reference any config in the family. A dot marks each config with an unpublished draft. The same family tree is available over the REST API from the lineage endpoint.
Environment overrides
By default a config resolves to a single base value used in every environment. When a value needs to differ by environment, add an environment override — a patch, scoped to one or more environments (and optionally projects), that layers on top of the base for those environments only. Manage overrides from the environment tabs on the config’s page: All Environments shows the base value, and each environment that has an override gets its own tab for editing just that environment’s patch. A dot on a tab marks an override with an unpublished draft. A config-backed feature flag then serves the base value where no override applies and the overridden value where one does. An override resolves as the last layer: the matching environment’s patch is deep-merged onto the fully-resolved base — the same targeted, key-by-key merge as inheritance — so it wins over inherited and composed values while the base still cascades for every key it doesn’t touch. When more than one override could match a given environment and project, the first match wins. Each override is itself a config, so its value carries its own revisions and goes through the same draft → review → publish flow; adding or removing an override for an environment takes effect immediately.How configs are validated
A config’s value passes through several layers of validation before it reaches an SDK payload:- Schema conformance — each field is checked against its schema definition (types, required fields, enums, bounds, nullability, and whether extra keys are allowed). This is the one-field-at-a-time check described in Type safety and validation.
- Cross-field validation rules (invariants) — mongrule conditions that express constraints across fields, which a per-field schema can’t. Covered just below.
- Custom validation hooks — optional customer-authored JavaScript that runs on save and publish. See Custom validation hooks.
- Descendant enforcement on publish — publishing a config re-checks every descendant against its effective rules. See Where rules run.
Validation rules (invariants)
Schema fields validate one field at a time. Validation rules (calledinvariants in the API) express the cross-field constraints a schema can’t — “target must not exceed max”, “if A is set, B must be too”.
Each rule has a name, the rule expression, and a human-readable message shown when it fails. Rules are part of the config’s schema — edit them alongside the fields in the app, or write the schema’s invariants array over the REST API.
Rules are inherited: a config is checked against its ancestors’ rules plus its own, accumulated base → leaf, and a rule with the same name as an ancestor’s overrides it. That means a base config’s rules guard every descendant.
Rule format
A rule is a MongoDB-style condition — the same condition syntax as feature and experiment targeting rules, so it’s a familiar, standard GrowthBook concept — extended with{ "$ref": "path" } to compare against another field of the value instead of a literal:
$eq, $ne, $lt/$lte/$gt/$gte, $exists, $and/$or/$not/$nor, …).
Nested fields are supported. A dot-separated path like buffer.target_seconds reaches into nested objects — as the tested field and as a $ref target alike. A path that doesn’t exist evaluates as null rather than erroring.
Where rules run
Rules are enforced on the GrowthBook server when a config publishes — on every publish path (direct API writes, publishing a revision, scheduled and auto-publish) — and are evaluated against the fully-resolved value (own keys plus everything inherited). They never run in SDKs; payloads carry resolved values only. While editing, the schema editor shows live pass/fail per rule, but a draft can be saved in a violating state — only publishing enforces. Because publishing a config changes every descendant’s resolved value, the publish also re-checks each descendant against its effective rules. Only violations introduced by that publish block it: a pre-existing violation elsewhere in the family never blocks an unrelated edit. The Block publishing on JSON schema errors organization setting controls what happens when a value fails its schema or a validation rule, or when a schema change makes a dependent Config or Feature Flag invalid:- On (default) — publishing is blocked. A REST API caller with Bypass draft
approvals in every Project can send
"skipSchemaValidation": trueto continue. - Off — GrowthBook returns a warning instead. Confirm the warning in the app,
or send
"ignoreWarnings": truethrough the REST API.
Custom validation hooks
You can add your own validation with Custom Hooks, which are sandboxed JavaScript functions that run when a Config is saved or published.validateConfig runs when a Config is created or updated, and
validateConfigRevision runs whenever a revision is published.
A hook can return a warning or reject the change. Anyone can acknowledge a
warning with "ignoreWarnings": true. To publish after a rejection, a REST API
caller with Bypass draft approvals in every Project must send
"skipHooks": true. The "skipSchemaValidation" field does not bypass hooks.
Hooks are scoped Global, Project, or Config; a config-scoped hook automatically covers the whole family (the scoped config and everything that inherits from it). Manage them from a config’s Validation tab or under Settings → Custom Hooks.
Custom Hooks are only available on self-hosted GrowthBook Enterprise.
Using a config as a feature flag’s value
This is where configs pay off: attach a config to a JSON feature flag — as the flag’s default value or on a specific rule — and the config’s shape is enforced on that flag. The flag serves the resolved config value, and edits to the flag are validated against the config’s schema. Any rule type can serve a config-backed value, including experiment and contextual-bandit rules, where each variation carries its own override. Because the config’s schema is authoritative, a flag can’t also define its own JSON schema while its value is backed by a config — detach the config or remove the flag’s schema. The flag’s value is stored as a small override patch layered on top of the config, so changing the config updates every flag that uses it.Seeing where a config is used
Every config tracks where its keys are consumed. On the config’s page — and over the REST API — GrowthBook lists each feature-flag default value, rule, experiment, and contextual bandit that overrides one of the config’s keys (across live and draft revisions), with the exact value each reference sets. Per-key badges surface the count at a glance, and for experiment and bandit rules you can inspect the override each variation applies.Protecting keys used by running experiments
Changing a config value that a running experiment depends on can distort that experiment’s results. You can opt a config into a guard — an organization-wide default, overridable per config — that blocks publishing a change to any key currently used by a running experiment or contextual bandit. The guard is computed live, so it clears on its own once the experiment stops; there’s nothing to unlock. Turn the guard on or off for a Config from the ⋮ menu on its page. To publish anyway, confirm the warning in the app or send"ignoreWarnings": true in the
REST API request. Disabling the guard for a Config requires Bypass draft
approvals access.
Import and export
A config’s value and its type definition can move in and out of GrowthBook:- Value — import or export the config’s JSON value.
- Schema — import or export the type definition as JSON Schema, TypeScript, or another supported typed-code format (Protobuf, Python, Go, Rust), or infer a schema from an existing value. JSON Schema is the canonical interchange format.
The TypeScript option is a feature-limited convenienceThe TypeScript import/export is a convenience for round-tripping simple
type/interface shapes — it is not a full TypeScript language parser. It understands the common building blocks (primitive fields, objects, arrays, simple unions/enums, optional and nullable fields) and ignores or rejects anything beyond that (generics, conditional/mapped types, imported types, functions, etc.). For anything non-trivial, use JSON Schema as the source of truth.Keeping code and configs in sync at scale
Configs are designed to be the source of truth for the configuration they describe. Rather than hand-maintaining the same shape in many codebases — where copies drift apart over time — define the config once in GrowthBook and have your services consume it. The schema and value live in one place; code reads them. A typical end-to-end workflow:- Define the config in GrowthBook — author it in the UI, or import it once from an existing code definition (see Import and export).
- Generate types from the config. Export the schema as TypeScript (or JSON Schema) and commit the generated types so your code is type-checked against the config’s current shape. Regenerate when the config changes — the same pattern teams use for generated API clients or protobuf types.
- Consume the resolved value at runtime through a JSON feature flag backed by the config (see Using a config as a feature flag’s value). The SDK serves the resolved value; the generated types describe its shape.
- Guard against drift in CI. The schema verify endpoint checks whether the shape your code expects still matches the config in GrowthBook. It reports whether the two are in sync and, when they differ, a categorized diff — contract changes (types, required-ness, enums, structure) separated from documentation-only changes (descriptions) — so a CI step can fail the build on real contract drift while treating doc changes as informational.
Named projections (per-source type names)
When you import a config’s schema from TypeScript and supply a source identifier (typically a service or codebase name), GrowthBook captures that source’s named-type structure — for example, that the object athttp.retry was declared as RetryPolicy. Exporting the schema with the same source reproduces those names instead of inlining the shapes:
- Without a source — nested objects are inlined:
retry: { maxAttempts: number; … }. - With a source — named interfaces are emitted:
interface RetryPolicy { … }andretry: RetryPolicy.
Editing and approvals
Config changes go through the same draft → review → publish flow as features, governed by your organization’s require-reviews settings matched on the config’s project. A config’s page has Overview, Review & Publish, and Validation tabs, a revision dropdown, and a right rail with the config’s details and the selected revision. Compare revisions from the ⋮ menu, and revert from the Review & Publish tab.- Fields, mixins, JSON, and validation rules are edited only in a draft. Start an edit while viewing the live config and GrowthBook opens your draft, or creates one, and carries on with the edit there. A note under Fields says which draft your edits will go to.
- Name, owner, description, and Project, and a base config’s Allow extra fields, are edited from Edit Information. The change is saved to a draft by default. The button reads Save to draft, Save when the change goes live at once, or Bypass approval & publish when it skips a required approval.
- In the JSON view of a draft, a new key you type that no schema declares is added to the JSON Schema beside it as an optional field.
- A new base config created in the app opens in a draft, ready for its first fields. A child config is created live.
- An archived config shows a callout at the top of its page, a draft that would archive it shows a warning, and a draft that would unarchive it says so.
- Locking pins a config at its live revision. Drafts can still be edited, but nothing publishes, and the config can’t be archived or deleted, until it’s unlocked. Lock and unlock from the ⋮ menu or with
POST /configs/{key}/lockandPOST /configs/{key}/unlock. Locking needs publish access, and unlocking needs Bypass draft approvals. - Archiving is blocked while a config is still referenced or while it has live child configs — resolve those first.
- Deleting is blocked while other configs still inherit from it (it would dangle their parent link); delete or re-parent the children first.
- Cycles in lineage or value references are rejected when a draft is saved, and so is a change that makes a config inherit the same field from two separate bases.
REST API
Configs and their revisions are fully manageable over the REST API — create, update, archive, delete, list references, fetch the full lineage, see where each key is used, manage environment overrides, import/export value and schema, and drive the revision/approval flow programmatically. Webhook events (config.*, including config.revision.*) fire on every change, modeled after the feature and constant events.
To get the override values behind a key’s usage, follow each reference back to its feature (GET /features/:id) — the key-usage endpoint reports where a key is used, and the feature is the source of truth for what it’s set to.
Editing a draft over REST
Draft edits go through/configs-revisions/{key}/{version}/.... Pass new as the version to open a draft and apply the edit in one call.
PUT .../valuestages the config’s own value. Send"inferUndeclaredFields": trueto also add an optional field, inferred from its value, for each top-level key that the config’s effective schema (its own and inherited fields) doesn’t declare. Existing fields are never changed, keys holding a@const:or@config:reference are skipped, and each added field is listed inwarningswith the codeinferred-field."inferSchemaIfMissing": trueinstead infers a whole schema when the config has none, and takes precedence.PUT .../schemastages the schema. Sendvaluewith it to stage both together, validated against each other. Use this to retype or remove a field the value already sets, which a schema write or a value write can’t do on its own.PUT .../propertyandDELETE .../propertychange one key of the value, leaving the others as they are.
Permissions
Configs share their policies with Feature Flags and Constants. Full access (FlagsFullAccess) covers creating configs, editing drafts, reviewing, publishing, reverting, archiving, and deleting, and a custom role can grant any of those actions on its own. Full access is included in the Engineer, Experimenter, Project Admin, and Admin roles by default. Configs can be scoped to specific projects.
