Repository navigation
docs(adr): update targeting-variant-metadata for schema PR decisions #2136
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,7 +3,7 @@ | |
| status: accepted | ||
| author: Parth Suthar | ||
| created: 2026-07-30 | ||
| updated: 2026-10-16 | ||
| updated: 2026-11-18 | ||
| --- | ||
|
|
||
| # Per-evaluation metadata from targeting rules | ||
|
|
@@ -29,20 +29,54 @@ Add a `resolve` operator to `schemas/json/targeting.json`, alongside `fractional | |
| "type": "array", | ||
| "minItems": 1, | ||
| "maxItems": 3, | ||
| "prefixItems": [ | ||
| { "type": "string" }, | ||
| { "type": ["string", "null"] }, | ||
| "items": [ | ||
| { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "array", | ||
| "prefixItems": [ | ||
| { "type": "string" }, | ||
| { "type": ["string", "number", "boolean"] } | ||
| ], | ||
| "minItems": 2, | ||
| "maxItems": 2 | ||
| } | ||
| "description": "Variant: string, or boolean coerced to \"true\"/\"false\". Literal numbers and null are rejected. A computed rule is also accepted; it is coerced like a plain targeting result.", | ||
| "oneOf": [ | ||
| { "type": "string" }, | ||
| { "type": "boolean" }, | ||
| { "$ref": "#/definitions/anyRule" } | ||
| ] | ||
| }, | ||
| { | ||
| "description": "Reason: string, null, or a computed rule. A null or omitted reason keeps TARGETING_MATCH.", | ||
| "oneOf": [ | ||
| { "type": ["string", "null"] }, | ||
| { "$ref": "#/definitions/anyRule" } | ||
| ] | ||
| }, | ||
| { | ||
| "description": "Metadata: [key, value] pairs. The list, each pair, each key, and each value may also be a computed rule. flagSetId and version are reserved for flag-set metadata.", | ||
| "oneOf": [ | ||
| { "$ref": "#/definitions/anyRule" }, | ||
| { | ||
| "type": "array", | ||
| "items": { | ||
| "oneOf": [ | ||
| { "$ref": "#/definitions/anyRule" }, | ||
| { | ||
| "type": "array", | ||
| "minItems": 2, | ||
| "maxItems": 2, | ||
| "items": [ | ||
| { | ||
| "oneOf": [ | ||
| { "type": "string", "not": { "enum": ["flagSetId", "version"] } }, | ||
| { "$ref": "#/definitions/anyRule" } | ||
| ] | ||
| }, | ||
| { | ||
| "oneOf": [ | ||
| { "type": ["string", "number", "boolean"] }, | ||
| { "$ref": "#/definitions/anyRule" } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
|
|
@@ -51,29 +85,30 @@ Add a `resolve` operator to `schemas/json/targeting.json`, alongside `fractional | |
|
|
||
| ### Arguments | ||
|
|
||
| - **`variant`** (1st): string. The only **required** argument, and the exact equivalent of the plain-string return: `"red"` and `{ "resolve": ["red"] }` are interchangeable terminals selecting the variant `red`. | ||
| - **`reason`** (2nd): string or `null`, optional. Free-form, operator-defined; overrides the top-level evaluation `reason` for this branch. The schema does not constrain it to an enum (see [Narrowing the coarse `reason`](#narrowing-the-coarse-reason)). | ||
| - **`metadata`** (3rd): array of `[key, value]` pairs, optional, shallow. Values are restricted to `string | number | boolean`, matching flag and flag-set metadata. | ||
| - **`variant`** (1st): a literal string; a literal boolean, coerced to `"true"` or `"false"`; or a computed expression. The only **required** argument, and the exact equivalent of the plain-string return: `"red"` and `{ "resolve": ["red"] }` are interchangeable terminals selecting the variant `red`. Literal numbers and `null` are rejected. Computed variants are coerced like plain targeting results: booleans become `"true"`/`"false"`, and the behavior of numbers is not defined. | ||
| - **`reason`** (2nd): string, `null`, or a computed expression, optional. Free-form, operator-defined; overrides the top-level evaluation `reason` for this branch. A `null` or omitted `reason` keeps `TARGETING_MATCH`. The schema does not constrain it to an enum (see [Narrowing the coarse `reason`](#narrowing-the-coarse-reason)). | ||
| - **`metadata`** (3rd): array of `[key, value]` pairs, optional, shallow. The whole list, each pair, each key, and each value may also be a computed expression. Literal values are `string | number | boolean`, matching flag and flag-set metadata. `flagSetId` and `version` are reserved for flag-set metadata and cannot be overridden by rules; the schema rejects them as literal keys, and computed keys that happen to match are not checked by the schema. | ||
| - **`details`**: a well-known metadata key: free-text explanation of why this branch fired. | ||
|
|
||
| `resolve` is **terminal**: it is only valid as the whole targeting rule, or as a result branch of `if` / `?:` (recursively). Implementations reject it anywhere else when the flag is loaded, so its result always passes through to the resolver unchanged. | ||
| `resolve` is **terminal**: it is only valid as the whole targeting rule; the result branches of `if` (recursively); and `fractional` bucket variants, in both the shorthand and the bucketing-value form. Every bucket variant is evaluated, and the selected one is returned. | ||
|
|
||
| The `resolve` operation is validated the same way as others: via JSON schema at load time only. The schema enforces terminality through separate `terminalIfRule` and `terminalFractionalRule` definitions reachable only from terminal positions, and by restricting the first `if` argument (always a condition) to plain args. | ||
| What the schema cannot enforce: `resolve` as a later else-if condition (positions 2, 4, … in a chained `if`), and `resolve` reached through `$ref` shared evaluators. Those cases are undefined behavior. | ||
|
|
||
| ### Evaluator changes | ||
|
|
||
| In `evaluateVariant` (`core/pkg/evaluator/json.go`), the current unconditional quote-strip of the JsonLogic result gains a `resolve` case ahead of it: | ||
|
|
||
| - `resolve` result: use its `variant` as the variant key; shallow-merge its `metadata` pairs into the returned metadata; if `reason` is present, use it in place of `TARGETING_MATCH` (a `null` or omitted `reason` keeps `TARGETING_MATCH`) | ||
| - `resolve` result: use its `variant` as the variant key (booleans are coerced to `"true"`/`"false"` officially; numbers are coerced like plain terminals, behavior not defined); shallow-merge its `metadata` pairs into the returned metadata; if `reason` is present and non-null, use it in place of `TARGETING_MATCH` (a `null` or omitted `reason` keeps `TARGETING_MATCH`) | ||
| - everything else → unchanged from today: `null` exits targeting to `defaultVariant`; strings, booleans, and numbers are quote-stripped into a variant key (so a boolean `true` still resolves the `"true"` variant, as `schemas/json/targeting.json` documents and the existing tests cover); a key absent from `variants` errors exactly as it does now | ||
|
|
||
| Metadata merge precedence, lowest → highest, so more specific wins: flag-set metadata → flag metadata → **rule-returned metadata**. | ||
|
|
||
| !!! warning "Breaking change to the config schema" | ||
| Metadata merge precedence, lowest > highest, so more specific wins: flag-set metadata < flag metadata < **rule-returned metadata**. The reserved keys (`flagSetId`, `version`) are the exception: the schema rejects them as literal rule metadata keys, so they come from the existing flag evaluation flow. | ||
|
|
||
| Existing configs keep working on a new binary, but the reverse does not hold: a config using `resolve`, evaluated by an older flagd binary, fails with an unknown-operator error. | ||
| !!! warning "Forward compatibility" | ||
|
|
||
| There's no schema/feature version negotiation today, so the config schema version has to gate it: operators on an older binary must stay on the older schema version, and flagd has to be upgraded fleet-wide before any config starts using `resolve`. This needs a schema version bump and a migration note in the release. | ||
| Existing configs keep working on a new binary, but the reverse does not hold: a config using `resolve`, evaluated by an older flagd binary, fails with an unknown-operator error. flagd has to be upgraded fleet-wide before any config starts using `resolve`. This needs an explicit migration note in the release. | ||
|
|
||
| Gating on the schema version is sufficient on its own — providers and flagd embed a snapshot of the schema in each version, so an older release rejects `resolve` at validation time rather than misbehaving at evaluation time. | ||
| flagd-schemas is pre-1.0, so `resolve` merges into the `v0` schema without a version bump; flagd core decides which schema version it uses by pinning the embedded snapshot it ships with. | ||
|
|
||
| **Hold the hosted schema back.** `https://flagd.dev/schema/v0/flags.json` is what editors and IDE tooling resolve against. Do not publish `resolve` there until it has landed in flagd and a few providers — otherwise editors will happily autocomplete a construct most of the fleet cannot evaluate. | ||
|
|
||
|
|
@@ -142,31 +177,20 @@ Each branch tags the evaluation with the rule that fired: | |
| } | ||
| ``` | ||
|
|
||
| ### Example — nested `if` with a fractional split | ||
| ### Example — `if` with a fractional split | ||
|
|
||
| `fractional` returns a plain string (`"on"` or `"off"`), and both are truthy under JsonLogic — so it can't be used directly as an `if` condition; wrapping it in `==` against a target bucket label makes it a real boolean: | ||
| `resolve` is valid as a `fractional` bucket variant, so each bucket can carry its own reason and metadata directly: | ||
|
|
||
| ```json | ||
| { | ||
| "targeting": { | ||
| "if": [ | ||
| { "==": [{ "var": "locale" }, "en-US"] }, | ||
| { | ||
| "if": [ | ||
| { | ||
| "==": [ | ||
| { | ||
| "fractional": [ | ||
| { "var": "targetingKey" }, | ||
| ["on", 10], | ||
| ["off", 90] | ||
| ] | ||
| }, | ||
| "on" | ||
| ] | ||
| }, | ||
| { "resolve": ["on", "SPLIT_RANDOM", [["details", "us-10pct-rollout"]]] }, | ||
| { "resolve": ["off", "SPLIT_FALLTHROUGH", [["details", "us-holdback"]]] } | ||
| "fractional": [ | ||
| { "var": "targetingKey" }, | ||
| [{ "resolve": ["on", "SPLIT_RANDOM", [["details", "us-10pct-rollout"]]] }, 10], | ||
| [{ "resolve": ["off", "SPLIT_FALLTHROUGH", [["details", "us-holdback"]]] }, 90] | ||
|
Comment on lines
+192
to
+193
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Specify how The example at lines 182–193 relies on each bucket returning its own The evaluator changes section only covers
Add these changes to the evaluator changes section so that the example and the evaluator contract agree.
|
||
| ] | ||
| }, | ||
| { "resolve": ["off", "FALLTHROUGH", [["details", "non-us-off"]]] } | ||
|
|
@@ -232,10 +256,9 @@ Those scenarios run across the gRPC, OFREP, and in-process paths that `test/inte | |
| - **Good** — direct answer to "which branch fired" without overloading the variant key; no wire-format changes. `flagMetadata` is already emitted on OpenFeature evaluation events and picked up by SDK hooks (OpenTelemetry, logging, custom exporters), so anything reading it — OTel spans, A/B dashboards, debug logs — picks up rule-level attribution automatically. | ||
| - **Good** — backwards compatible for existing configs: string, boolean, number, and null returns are byte-for-byte unchanged on an upgraded flagd binary. | ||
| - **Good** — no OpenFeature spec change required. `reason` is already a first-class spec field, and `details` rides `flagMetadata`, so no SDK gains a new resolution field. | ||
| - **Bad** — not forward compatible: a config using `resolve`, evaluated by an older flagd binary, fails with an unknown-operator error. No schema/feature version negotiation exists today, so rollouts must upgrade flagd before configs start using `resolve`. Needs an explicit migration note. | ||
| - **Bad** — not forward compatible: a config using `resolve`, evaluated by an older flagd binary, fails with an unknown-operator error. Rollouts must upgrade flagd before configs start using `resolve`. Needs an explicit migration note in the release. No schema version bump is needed — flagd-schemas is pre-1.0 and `resolve` merges into the existing `v0` schema; flagd core pins the snapshot it embeds. | ||
| - **Bad** — automatic telemetry attribution requires the separate `RecordEvaluation` work called out in Background; without it, rule ids ride `flagMetadata` for SDK-side hooks but don't reach flagd's own OTel metrics. | ||
|
|
||
| ## Open questions | ||
|
|
||
| - **Config version.** Proposal: bump the targeting/flags schema to `v0.1` and gate the new terminus on it, leaving `v0` untouched for existing fleets. Sequencing of the hosted schema at `flagd.dev` is covered in the migration warning above. | ||
| - **Fractional buckets.** `fractional` returns a variant string directly, so it can't tag the picked bucket with metadata without a separate operator extension (e.g. an optional third element per weight tuple). Proposal: defer — ship the base `resolve` operator first. Nesting metadata into fractional is meaningfully more complicated and shouldn't block this. | ||
| None outstanding. Schema version bump and fractional bucket support were both resolved during schema review (flagd-schemas#238, flagd#2127): no version bump is needed (pre-1.0), and `resolve` is now valid as a `fractional` bucket variant. | ||
Uh oh!
There was an error while loading. Please reload this page.