Skip to content

[Flagship] Add structured context support and evaluation API documentation - #34390

Open
madhugb wants to merge 2 commits into
cloudflare:productionfrom
madhugb:mbalakrishna/document-json-context
Open

madhugb wants to merge 2 commits into
cloudflare:productionfrom
madhugb:mbalakrishna/document-json-context

Conversation

@madhugb

@madhugb madhugb commented Oct 16, 2026 •

Copy link
Copy Markdown

Summary

Documents structured (JSON) evaluation context support and the Flagship evaluation API:

  • New page flagship/reference/evaluation-api.mdx — the data-plane evaluation API, covering GET with scalar query context and POST with structured JSON context, including an <APIRequest> example.

  • Structured context in the Workers binding — recursive values (nested objects, arrays, null), Date normalization to ISO 8601, rejection of non-finite numbers and cyclic values, and the resulting INVALID_CONTEXT error. Documents the recursive public context declarations and how to serialize Date values for TypeScript.

  • Two new targeting operators — has and not_has (11 → 13) added to the operators reference, targeting overview, and Wrangler --rule examples.

  • Dot-path attribute traversal — up to five segments, with literal top-level key precedence — documented in targeting rules and percentage rollout bucketing.

  • Evaluation context limits — attribute count, key length, nesting depth, serialized size, and traversal count — added to the limits reference.

  • errorMessage field on FlagshipEvaluationDetails, plus new invalid-context behavior docs: binding *Details() methods return the default value with error fields, while the HTTP POST endpoint returns 400.

  • Context support matrix on the SDK index covering structured context through the direct binding, evaluation API POST, and TypeScript, Python, and Go SDKs from version 0.6.0. The SDKs automatically use POST for structured HTTP context; Wrangler --context values remain strings.

  • Clarifies across Wrangler and SDK pages that JSON-looking query values remain strings and do not create nested context.

  • Changelog — adds flagship/2026-10-23-structured-evaluation-context.mdx, dated Friday, October 23, covering nested targeting, array membership, and SDK support.

Documentation checklist

  • Is there a changelog entry (guidelines)? If you don't add one for something awesome and new (however small) — how will our customers find out? Changelogs are automatically posted to RSS feeds, the Discord, and X.
  • The change adheres to the documentation style guide.
  • If a larger change - such as adding a new page- an issue has been opened in relation to any incorrect or out of date information that this PR fixes.

@github-actions github-actions Bot added the product:flagship Related to Flagship product label Oct 16, 2026
@cloudflare-docs-bot

cloudflare-docs-bot Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

AI Review

✅ Reviewed d113f34 · 0 findings · incremental

Resolved (1) · Dismissed (0)
  • Resolved: Duplicate case "STATIC" makes the later branch unreachable · read_repo_file at head d113f34 shows the example switch now has a single case "STATIC": (line 63); line 67 is the DEFAULT case's log. No duplicate label or unreachable branch remains, so the reported dead code no longer exists at head.
Commands
  • /review Run a review now.
  • /full-review Review the entire PR diff.
  • /disable-auto-review Stop automatic reviews.
  • /rebase Rebase against production.

@cloudflare-docs-bot

cloudflare-docs-bot Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Review coverage

✅ All 2 ownership areas are covered.

✅ 2 areas already covered
Area Approved by
flagship
17 files changed
/src/content/docs/flagship/
akshitsinha
flagship
1 file changed
/src/content/changelog/flagship/
akshitsinha
CODEOWNERS mappings for displayed areas (2)
Pattern Owners
/src/content/docs/flagship/ @akshitsinha, @irvinebroque, @ishita1805, @karishnu, @vaibhavshn, @madhugb, @cloudflare/flagship, @cloudflare/product-owners
/src/content/changelog/flagship/ @akshitsinha, @irvinebroque, @ishita1805, @karishnu, @vaibhavshn, @madhugb, @cloudflare/flagship, @cloudflare/pm-changelogs, @cloudflare/product-owners

Comment thread src/content/docs/flagship/binding/types.mdx Outdated
Comment thread src/content/docs/flagship/binding/types.mdx Outdated
Comment thread src/content/docs/flagship/reference/evaluation-reasons.mdx Outdated
Comment thread src/content/docs/flagship/reference/evaluation-reasons.mdx Outdated
| Serialized UTF-8 JSON size | 32 KiB | All evaluation paths |
| Values visited during traversal | 10,000 values | Data-plane HTTP and Workers binding only |

Flagship control-plane `POST` endpoints do not apply the 10,000-value traversal limit. Other context limits still apply.

@akshitsinha akshitsinha Oct 16, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Potential follow-up: shouldn't POST also have traversal limits?

Comment thread src/content/docs/flagship/sdk/client-provider.mdx Outdated
@@ -41,7 +41,8 @@ The binding provides type-safe methods for evaluating feature flags. If an evalu
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const enabled = await env.FLAGS.getBooleanValue("new-feature", false, {
userId: "user-42",

@akshitsinha akshitsinha Oct 16, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we retain userId along with the rest of the JSON context fields we added? Would be helpful for folks who just want to provide a simple string or number as context.

@irvinebroque
irvinebroque requested a review from a team as a code owner October 17, 2026 15:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants