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	Jun 27, 2025 4:57pm

2 Skipped Deployments

Name	Status	Preview	Comments	Updated (UTC)
flagsmith-frontend-preview	⬜️ Ignored (Inspect)	Visit Preview		Jun 27, 2025 4:57pm
flagsmith-frontend-staging	⬜️ Ignored (Inspect)	Visit Preview		Jun 27, 2025 4:57pm

[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!

[emyller]

Let's say I have the following segment setup:

• Identifier IN id3,id4,id5
• "some trait" % Split 50

Can identity "id4" fall into the 50% bucket?

[khvn26]

Based on the docs, it does. Hopefully the % Split documentation is now clearer after 584a1a1.

[emyller]

it does

Sorry, not clear: it does, or it can? Given the two rules are combined with an OR operator, I'd assume it can.

Also, aren't these two paragraphs very similar? To my Friday brain, the explanation around combining traits and context values feels a bit confusing.

L255:

Percentage Split deterministically assigns an Identity to a bucket based on a provided [context value](#context-values)
or a trait. This means that Segment overrides that use Percentage Split will always result in the same feature value for
a given identity in the chosen context.

L262:

Percentage Split deterministically assigns a "bucket" to each identity based on a provided identifier or a
[context value](#context-values). This means that Segment overrides that use Percentage Split will always result in the
same feature value for a given identity in the chosen context.

Here's a suggestion, based on my own understanding. It's close to the first variation above:

Percentage Split deterministically assigns a "bucket" to each identity based on a provided context value or a trait. This means that Segment overrides that use Percentage Split will always result in the same feature evaluation for a given identity.

I feel like the following sounds confusing, though it can be my own lack of familiarity:

• "feature value" makes me wonder if this is also valid for a feature state.
• "in the chosen context" sounds confusing. I know we're introducing the idea of contexts though this phrase sounds like I need to take a step back and learn something.

[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 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?).

[matthewelwell]

I'd perhaps argue that, while this use case showcases what's possible, when you think about it, it feels like it boils down to the same as what we have right now where not everyone in a given tenancy is getting a consistent experience. As I understood it, that was the key use case that we're trying to solve.