feat(sdk): add variant to the /identities response flag schema

[gagantrivedi]

RFC / schema-only. This PR proposes the remote-evaluation contract for the multivariate variant key and exists to gather feedback — there is deliberately no implementation here. Part of the variant key work: #7698, #7699, #7704, Flagsmith/flagsmith-engine#314.

• I have read the Contributing Guide.
• I have added information to docs/ if required so people know about the feature. (the SDK API reference regenerates from this spec once the contract is agreed and implemented.)
• I have filled in the "Changes" section below.
• I have filled in the "How did you test this code" section below.

Changes

Contributes to the multivariate variant key work (#7698, #7699, #7704).

Adds an optional, nullable variant to each flag in the /api/v1/identities/ response (V1IdentitiesResponseV1Flag), as a sibling of feature_state_value:

{
  "feature": { "id": 42, "name": "checkout_button", "type": "MULTIVARIATE" },
  "enabled": true,
  "feature_state_value": "blue",
  "variant": "control"
}

Design points for feedback:

• Placement — sibling of feature_state_value: it's a per-identity evaluation result, like the value itself. Not in feature (static definition) and not in the multivariate config array (that lists all variants, not the winner).
• Name — variant, matching the evaluation result contract in feat(sdk): add variant key to evaluation schemas #7704 and OpenFeature's ResolutionDetails.variant, so one term is used everywhere SDK-facing.
• null, not omitted — null when no variant was selected or the selected variant has no key, which is DRF-idiomatic and keeps the response shape stable.
• /identities/ only — /flags/ has no identity, so no percentage split ever happens there

Not in scope (follow-ups once the contract is agreed): the serialiser change in core API, Edge API parity (it serves the same contract and must match before SDKs rely on the field), and make generate-sdk-api-docs.

How did you test this code?

Schema-only change, no behaviour to test: the file validates as YAML, and the new property follows the existing anyOf/nullable conventions used by feature_state_value and trait_value in the same document.

[vercel]

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

3 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
docs	Ignored		Jun 5, 2026 8:21am
flagsmith-frontend-preview	Ignored		Jun 5, 2026 8:21am
flagsmith-frontend-staging	Ignored		Jun 5, 2026 8:21am