Flag types and values

Every FeatureGate flag has one permanent value type. Environment fallbacks, rule outcomes, SDK getters, and caller defaults must agree with it.

Choose the smallest type that expresses the decision. Smaller contracts are easier to validate, review, migrate, and remove.

Type	Use it for	Example
Boolean	On/off decisions and emergency controls	false
String	A small named mode or variant	"compact"
Number	A bounded runtime parameter	25
Object	Cohesive structured configuration	{ "limit": 25 }

Boolean flags

Use a boolean when application code has two branches. A release flag, maintenance guard, or kill switch normally begins here.

const enabled = featuregate.getBooleanValue("new-checkout", false, context);

if (enabled) {
  return renderNewCheckout();
}

return renderExistingCheckout();

Avoid replacing one boolean with several overlapping booleans when the real domain has named modes. Use a string flag so only one mode can be selected.

String and number flags

Strings work well for compact named variants such as "compact", "comfortable", and "dense". Keep the accepted values in application code and handle unknown values defensively.

Numbers suit bounded parameters such as page size, timeout class, or concurrency. The application must validate acceptable ranges. A correctly typed number can still be operationally unsafe.

const configuredPageSize = featuregate.getNumberValue("page-size", 25, context);
const pageSize = Math.min(100, Math.max(10, configuredPageSize));

Do not use numbers to encode categories. A string such as "standard" communicates intent better than a magic value such as 2.

Object flags

Use objects when several fields must change as one coherent configuration. Values must be JSON-compatible. Validate the returned shape before it controls consequential behaviour.

interface SearchLimits {
  pageSize: number;
  timeoutMs: number;
}

const fallback: SearchLimits = { pageSize: 25, timeoutMs: 800 };
const value = featuregate.getObjectValue("search-limits", fallback, context);

Object flags create a larger compatibility surface. Prefer separate flags when fields have different owners, rollout schedules, or failure policies.

Defaults and type mismatches

Every getter and HTTP evaluation supplies a typed default. A missing flag or type mismatch returns that value rather than coercing data.

The boolean getter never treats the string "true" as enabled. A number getter never parses "25". This prevents configuration mistakes from changing application semantics silently.

Details getters reveal whether the default was used and why. Use them in tests, diagnostics, and integration checks. Keep normal application branching on the typed value.

Change a flag contract

Flag type cannot change after creation. When meaning or type must change:

1. Create a new key with the new contract.
2. Add code that can read the new flag safely.
3. Configure and validate it in non-production.
4. Roll callers onto the new key.
5. Remove the old guarded code.
6. Archive the old flag.

Never reuse an old key for a different meaning. Long-running processes, old deployments, and tests may still interpret it under the original contract.

Security and data handling

Do not place secrets or personal data in values. Server snapshots distribute values to every trusted process holding the environment key. Client-exposed values can be delivered to browsers.

Flags are runtime decisions, not a secret store or database. Use application-owned storage for data that needs access control, transactional updates, or durable history.

Related pages: Configure flags across environments and Errors and fallbacks.