chore: Include Features, Segments in evaluation context schema

[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 #5808.

This PR adds:

• An EvaluationResult schema that includes flag and used segment information.
• segments and features keys to the EvaluationContext schema to have all data required for evaluation in a single DTO.

The design goal was to have a structure that is extensible, simple enough to parse and read through, and that provides all required engine data, excluding any data unrelated to engine.

Some new vocabulary is added here that, IMO, make sense for evaluation:

• String "key" fields are preferred to numeric id fields to more clearly state their purpose.
• A "variants" key is used to represent multivariate feature states, where each variant includes a "weight" indicating its distribution percentage. I considered using a unified "values" array for all feature states — including non-multivariate ones (with a single { "weight": 100 } entry) — but opted against it to avoid ambiguous semantics around control values and the need to validate against empty arrays.

Both objects will be used by the new engine interface to be introduced in Flagsmith/flagsmith-engine#234.

An example EvaluationContext object:

{
  "environment": {
    "key": "abcde",
    "name": "Test Environment"
  },
  "features": {
    "feature_1": {
      "key": "1",
      "name": "feature_1",
      "enabled": true,
      "value": "foobar"
    },
    "feature_2": {
      "key": "2",
      "name": "feature_2",
      "enabled": false,
      "value": "control",
      "variants": [
        {
          "value": "a",
          "weight": 51.0
        },
        {
          "value": "b",
          "weight": 49.0
        }
      ]
    }
  },
  "segments": {
    "test_segment": {
      "key": "1",
      "name": "test_segment",
      "rules": [
        {
          "type": "ALL",
          "sub_rules": [
           {
          "type": "ANY",
          "conditions": [
            {
              "path": "$.identity.identifier",
              "operator": "IN",
              "value": "id1,id2"
            },
            {
              "path": "some-trait",
              "operator": "EQUALS",
              "value": "foobar"
            }
          ]
        }
          ]
        }
      ]
    }
  }
}

An example EvaluationResult object:

{
  "context": {...},
  "flags": [
    {
      "enabled": false,
      "value": "foobar",
      "feature": {
        "key": "1",
        "name": "feature_1"
      }
    },
    {
      "enabled": true,
      "value": null,
      "feature": {
        "key": "2",
        "name": "feature_2"
      }
    }
  ],
  "segments": [
    {
      "key": "1",
      "name": "test_segment"
    }
  ]
}

How did you test this code?

N/A

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
docs	Ignored	Preview		Aug 15, 2025 7:24pm
flagsmith-frontend-preview	Ignored	Preview		Aug 15, 2025 7:24pm
flagsmith-frontend-staging	Ignored	Preview		Aug 15, 2025 7:24pm

[github-actions]

Docker builds report

Image	Build Status	Security report
ghcr.io/flagsmith/flagsmith-api-test:pr-5867	Finished ✅	Skipped
ghcr.io/flagsmith/flagsmith-e2e:pr-5867	Finished ✅	Skipped
ghcr.io/flagsmith/flagsmith-frontend:pr-5867	Finished ✅	Results ✅
ghcr.io/flagsmith/flagsmith-api:pr-5867	Finished ✅	Results ✅
ghcr.io/flagsmith/flagsmith:pr-5867	Finished ✅	Results ✅
ghcr.io/flagsmith/flagsmith-private-cloud:pr-5867	Finished ✅	Results ✅

[Zaimwa9]

Looks solid overall. One piece feels missing to make the evaluation fully representative imo - but let me know if it's really useful.

Right now we have:

• the flag being evaluated
• the identity under evaluation
• the segments that can override
• the final evaluation result

What could be missing in the result is the why do I have those values. We know which segment overid but we don't have necessarily its values (especially thinking with multi-variate where the possibilities are wider).
Do you think it would make sense to surface the override override configuration (blue 40%/red60% instead of blue80%/Green20%) ?

[khvn26]

I had to add some stuff while finalising https://github.com/Flagsmith/flagsmith-engine/pull/239/files:

• I brought back FeatureContext.name in c67d7b8 to simplify serialisation of FlagResults.
• Added FeatureContext.feature_key in 04103f3. Feature (not feature state) ids are used to correctly apply overrides, and are surfaced in FlagResult objects to maintain backwards compatibility. Additionally, I removed nesting from FlagResult.
• Fixed incorrect priority field documentation in f50fb30.