Design evaluation context

Build a stable, minimal context schema for targeting and rollout assignment.

Evaluation context is application-supplied data used by targeting rules. Design it as a versioned application contract, not an ad hoc dump of the current request or user object.

The Node.js SDK accepts a stable targetingKey plus nested attributes. Direct HTTP evaluation sends the nested attributes as context.

const context = {
  targetingKey: "user_123",
  attributes: {
    user: { id: "user_123", role: "member" },
    account: { id: "account_456", plan: "pro" },
    region: "au",
  },
};

Start from targeting decisions

List the decisions the application needs before adding attributes. If rules target account plan and roll out by account, the contract needs account.plan and account.id. It does not need a full profile.

Path	Type	Supplied by	Missing behaviour
`user.id`	String	Identity service	User rule misses
`user.role`	String	Authorization projection	Role rule misses
`account.id`	String	Account boundary	Account rollout misses
`account.plan`	String	Billing entitlement projection	Plan rule misses
`region`	String	Deployment or request policy	Region rule misses

Document this table with the application. Rule authors should know the source, type, allowed values, normalization, and behaviour when each path is absent.

Choose stable identifiers

Use opaque application-owned IDs for rollout assignment. A targetingKey or rollout attribute must stay stable across processes and restarts.

Choose the identifier at the desired consistency boundary. Use account.id when every member of an account must move together. Use user.id when individuals can experience different variants.

Do not use raw email addresses. They are personal data, can change, and may be normalized differently by services. An opaque immutable ID is safer and more stable.

Normalize once

Rules compare exact paths and values. Normalize case, enum names, country codes, and identifiers in application code before evaluation.

Do not let one service send "PRO" while another sends "pro". Do not silently reinterpret an existing path when its meaning changes.

When semantics change, add a new path such as account.planVersion2. Run old and new paths during a migration, update rules and callers, then remove the old contract deliberately.

Handle missing and older contexts

Missing paths are ordinary condition misses, not evaluation errors. Test each rule with:

A matching context.
A present but non-matching value.
A missing nested object.
A missing final attribute.
An older client that does not send the new path.
A malformed value of the wrong application-level type.

Negative operators do not make an absent value match. This prevents unknown subjects from entering a cohort through not equals or not in.

Minimize sensitive data

Send only attributes used by active rules. Never include raw emails, names, tokens, cookies, authorization headers, full request bodies, or sensitive profile fields.

The hosted API validates context size. Snapshot SDK evaluation stays local and does not send context or local evaluation events to FeatureGate.

Application logs should avoid full context and resolved flag values. Log a privacy-safe request ID, flag key, evaluation reason, and operational outcome only when the application truly needs them.

Review the contract

Review context when adding a new targeting path, changing identity systems, moving rollout units, or introducing browser evaluation. Browser context is user-controlled and cannot establish trust.