docs: Context values for Segments

[khvn26]

Thanks for submitting a PR! Please check the boxes below:

• I have added information to docs/ if required so people know about the feature!
• I have filled in the "Changes" section below?
• I have filled in the "How did you test this code" section below?
• I have used a Conventional Commit title for this Pull Request

Changes

Closes #5615.

This PR outlines the Context values for Segments functionality primarily aimed to solve the use case outlined in #5557, open the door for solving #136, #5635, #3971, and more.

Context values are used as Segment rule properties to enable more flexible segmentation. Currently, Context values include the Environment Name, Identity Identifier, and Identity Traits. The % Split operator, previously locked to Identity Identifier, can now be used with any Context value just as any other operator.

In the future, we'll be able to add more useful predefined Context values like:

• User-defined contexts, for proper multi-context support.
• Feature evaluation results, should allow us to implement dependent flags.
• User application names/versions and user agents from the SDK metrics tracking (being added in feat: Backend for SDK metrics #5623).
• Current timestamp, to segment by datetime (do we need such a convenient shortcut for scheduled flags? 😄)

The PR contains the following changes:

• Documentation for Context values. I'll be gathering feedback on that to more closely understand how to scope out the feature further.
• Mocked-up (not actually working) changes to Segment creation UI to exhibit an idea how the feature should look for end users.
• The Evaluation context schema now includes the Environment Name Context value. Rather than using it for the SDKs as initially planned, I'm looking to repurpose the schema for the next major version of the Flagsmith evaluation engine, as it clearly defines dependencies for flag evaluation.

How did you test this code?

N/A

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 23, 2025 9:30am

2 Skipped Deployments

Name	Status	Preview	Comments	Updated (UTC)
flagsmith-frontend-preview	⬜️ Ignored (Inspect)	Visit Preview		Jul 23, 2025 9:30am
flagsmith-frontend-staging	⬜️ Ignored (Inspect)	Visit Preview		Jul 23, 2025 9:30am

[matthewelwell]

I've added one minor comment to a specific line I wasn't sure about.

On the whole though, it looks good to me. I think that one thing that I'd love to see (whether they make it into the docs for release or not) is some example use cases listed out and how to achieve them.

For example,

"A multi-tenant platform where we want to roll-out a feature by percentage such that all users in a given tenancy get a consistent experience"

• I think this can be achieved using this functionality + transient traits

I'm sure there are other use cases that we've received feedback about that we're trying to achieve with this too. What about different device types, are there use cases there?

Also, on a general functionality point of view, should we consider being able to define logical context values somehow? Like a hash of their identifier, and some other trait value for example? I'm not suggesting this is part of v1, but does it need to be considered as part of the data-model?

[emyller]

Looks promising!

[khvn26]

@matthewelwell

On the whole though, it looks good to me. I think that one thing that I'd love to see (whether they make it into the docs for release or not) is some example use cases listed out and how to achieve them.

I've added 2 use cases in 08b9330 that made sense to me, let me know your thoughts.

Also, on a general functionality point of view, should we consider being able to define logical context values somehow?

I agree this might be a worthwhile endeavour. I can see two ways to achieve that:

1. Add more operators, and build proper UX around nested conditions.
2. Think on supporting some DSL for conditions (jsonlogic?)

If we go route 2, we might want to think early on data accessor format to use for Context values, so the answer to

does it need to be considered as part of the data-model?

should be "Yes".

[khvn26]

Some additional thoughts as to opportunities unlocked by Context values:

• We'll be able to nuke MV features backend by preserving existing MV UX around environment-scope segments.
• Per-identity overrides can be condensed to environment == x, identifier IN y[] type segments, which should save us a lot of storage and memory, and improve the local evaluation experience, especially in conjunction with Spike: Removing segment / feature / overrides limits from Edge projects #3763.

[khvn26]

For reference, these are free logical operations we receive with jsonpath-ng extensions:

https://github.com/h2non/jsonpath-ng?tab=readme-ov-file#extensions

[khvn26]

Thinking we could use jq syntax as well, if we prove the jq bindings to be performant enough.

jq is Turing-complete so this could be an overkill, or just the right solution depending on how flexible we want to allow this feature to be.

[emyller]

https://jmespath.org/ is worth mentioning — it's adopted by the AWS CLI.

Seems abandoned in GitHub.

[matthewelwell]

As discussed on our call earlier today, in answer to the questions here, we plan to go ahead with JSONPath for context values in segment conditions.

We verified that there are currently no conditions in our SaaS DB that begin with $. so we can (fairly) safely assume that we can rely on that to determine if a condition is context value or a trait (although thinking about it, the user has to make a decision in defining the segment, so why don't we just store them separately in the data model or add a flag to the model?).

[khvn26]

One more thought: Looks like we can ditch the FeatureSegment model as well if we come up with a performant enough implementation for the $.feature.name context value.

[emyller]

Looks great!

[Zaimwa9]

Approving because it's already good as of but I have 2 minor comments that I let you decide if worth

[Zaimwa9]

Out of clarity, I would add just a sentence before explaining the default behavior that would store the organisation_name and why that transient trait would be preferable in some situations

[khvn26]

I'd like to avoid duplicating the trait docs tbh. I think the word "persisting" gives a strong hint here.