Targeting reference

FlagWire evaluation is deterministic for the same published bundle and context. This page defines the matching order and failure behavior shared by the edge service and local evaluation engine.

Evaluation order

For an active flag, evaluation proceeds in this order:

1. If the bundle is invalid or revoked, return the code default.
2. If the flag does not exist, return the code default.
3. If the flag is off, serve its configured off variant.
4. Evaluate rules from top to bottom. The first matching rule wins.
5. If no rule matches, use the flag’s fallthrough behavior.

Rules do not partially match. Every clause in a rule must match.

Context

{
  "key": "user-123",
  "attributes": {
    "region": "ap-south",
    "country": "IN",
    "appVersion": "2.4.1",
    "betaTester": true,
    "groups": ["staff", "design-partner"]
  }
}

key is the stable identity used for deterministic rollouts. Attribute values may be:

• a string
• a finite number
• a boolean
• an array of strings

Missing or incompatible attributes do not throw. The clause does not match, and evaluation continues safely.

Clause semantics

Clauses within a rule use AND. Values within one clause use OR. negate reverses a valid match or no-match result; it does not turn malformed input into a match.

Operator	Match behavior
eq	Same primitive type and equal value
neq	Same primitive type and unequal value
in	Attribute equals any configured value
contains	String contains a substring, or string array contains a value
startsWith	String begins with a configured string
endsWith	String ends with a configured string
gt	Numeric value is greater than the configured value
gte	Numeric value is greater than or equal to the configured value
lt	Numeric value is less than the configured value
lte	Numeric value is less than or equal to the configured value
semverEq	Semantic version is equal
semverGt	Semantic version is greater
semverLt	Semantic version is lower
regex	String matches a JavaScript regular expression
segment	Context matches any referenced segment

Numeric comparisons accept finite numbers and strings that convert to finite numbers. Empty strings, arrays, non-finite numbers, and failed conversions are invalid for numeric comparison.

Semantic versions accept an optional leading v, prerelease identifiers, and build metadata. Both the context value and configured comparison value must be valid semantic versions.

Regular-expression patterns are limited to 256 characters. An invalid pattern is treated as an evaluation error for that clause rather than being allowed to throw through the SDK.

Segments

A segment contains one or more rule groups:

• groups use OR
• clauses inside a group use AND
• a segment clause matches when any referenced segment matches

Circular segment references and missing segments are invalid matches and do not throw.

Rollouts

A rollout distributes traffic across variants using 100,000 basis points. Weights must total exactly 100000, and each variant can appear only once.

FlagWire hashes three stable inputs:

context.key : flag key : flag salt

The resulting bucket is deterministic, so the same context stays in the same variant until the flag key, flag salt, rollout, or context key changes. A rollout without a context key serves the configured off variant with the reason ERROR_MISSING_KEY.

Evaluation reasons

Detailed evaluation can return:

Reason	Meaning
RULE_MATCH:<id>	The named rule was the first match
FALLTHROUGH	No rule matched and fallthrough was used
OFF	The flag was disabled
FLAG_NOT_FOUND	The bundle did not contain the requested flag
REVOKED	The environment bundle was revoked
ERROR_MISSING_KEY	A rollout needed a stable context key
ERROR	State was invalid or could not be evaluated safely

Next: bundle format or Node.js quickstart.