Skip to content
FlagSwiftDocs

Choose a flag type and variants

Pick the type that matches what your code needs, and define variants when a flag must serve more than on or off.

Time
About 8 min
Who can do it
Product manager, Developer, Release manager or Admin to define variants. Release manager or Admin to change a live value in production.
Where
New Flag, then the flag's Variants and Targeting & rollout tabs
You finish with
A flag that serves the right kind of value, with each environment choosing who gets which variant

What and why#

What it is#

Every flag answers a question for one person at a time. A Boolean flag answers yes or no. The other three types answer with a value your code can use directly: a text, a number or a small object. Each possible value is a variant with its own key.

When to use variants#

  • Compare two or more versions of something, such as a checkout layout, and measure which one converts better.
  • Control a setting without a deploy: a page size, a timeout or a rate limit as a Number, or a block of settings as JSON.
  • Keep Boolean for anything that is simply on or off. It is the default, needs no variants and is the easiest to clean up.

How it works#

Variants are defined once per flag. Each environment then decides two things: which variant people get when the flag is off, and how people are split between variants (weights that add up to 100) when it is on. A person always lands on the same variant for the same flag.

Before you start#

  • Know what your code will do with the answer: switch a feature, pick a text, set a number or read a small object.
  • The type is chosen when you create the flag and cannot change, so decide first. If you chose wrong, create a new flag.
  • Permission: flags.create to create, flags.update to edit variants, and rollouts.update to change an environment's split. In a production environment, Developers and Product managers cannot change the split.

The four types#

Flag types
TypeVariantsDescription
BooleannoneOn or off. The default, and the right choice for most flags.
String2 to 20Serves a text value, such as a layout name or a button label. Up to 16,384 characters.
Number2 to 20Serves a finite number, such as a limit or a timeout.
JSON2 to 20Serves an object or an array, such as a set of settings, up to 16,384 characters once serialized. A plain string, number or null is refused.

Walk through it#

  1. Choose the type

    Open New Flag. In the Create Flag form, set Type. For anything other than Boolean, a Variants section appears with two starting rows named control and treatment. The hint under Type reads: “Serves a value. Define the variants below; each environment decides who gets which.”

  2. Define the variants

    Each variant row has these fields. Choose Add variant for more and the remove button on a row to delete one.

    Variant fields
    FieldLimitDescription
    Keyrequired, 50Lower case letters, numbers, hyphens and underscores, with no leading, trailing or doubled separators. Unique within the flag. What SDKs and rules refer to.
    Label (optional)80A friendlier name for the console. The placeholder reads Shown in the console.
    ValuerequiredTyped by the flag: text for String, a finite number for Number, and valid JSON (an object or array) for JSON.

    A flag needs at least 2 variants and can have up to 20. Create Flag stays disabled until every key and value is valid.

    Variant rows for a Number flag. Each row has Key, Label (optional) and Value, and Number values must be finite numbers.

    Row errors appear under the field: Key is required, Lowercase letters, numbers, hyphens and underscores only, Key is used twice, Value is required, Enter a valid number, Enter valid JSON and Enter a JSON object or array. A list problem reads Add at least 2 variants or At most 20 variants. Switching Type resets the rows to two fresh starting rows (Number starts at 0 and 1, JSON at empty objects).

    You should see. The flag opens with a Variants tab next to Overview. Boolean flags never show it.
  3. Decide what each environment serves

    Open the Targeting & rollout tab and pick an environment. Step 6, Variants, has two controls. Served when the flag is off picks the variant for people the flag is not on for (it is also served when the kill switch is active). Next to each variant, a Weight from 0 to 100 sets how people are split when the flag is on. The total shows under the list and must be exactly 100. Choose Save changes.

    A new flag serves its first variant at 100% everywhere, and the first variant is the off variant. When you add a variant later, it starts at weight 0.

    Step 6, Variants, for one environment: the off variant and a weight per variant.
    You should see. The total reads Total 100% and Save changes is enabled. Use Check who gets this flag with a test identifier to see the variant chosen.
  4. Edit variants later

    On the Variants tab, change labels and values, add variants, then choose Save variants (or Discard). Saved keys are locked and cannot be renamed. A variant that any environment still serves, by weight or as its off variant, cannot be removed until you move its traffic to another variant.

  5. Read the variant in code

    The client evaluation response carries the variant for multivariate flags. Check it with one request, or use an SDK.

    bash
    curl -s "https://flags.example.com/api/v1/evaluation/client?user_identifier=user-123" \
      -H "Authorization: Bearer $KEY"
    200 OK
    {
      "environment": "development",
      "hashVersion": 1,
      "version": "f1c2",
      "flags": {
        "new-dashboard": { "enabled": true, "version": 2 },
        "checkout-layout": { "enabled": true, "variant": "compact", "value": "compact", "version": 3 }
      }
    }

    Each flag has enabled and, for a flag with variants, variant and value. SDKs offer calls such as getVariant and getValue for this. Always pass a fallback value, because a flag check never throws.

Changing a saved value is live everywhere

A value belongs to the flag, not to one environment, so changing it affects every environment at once. The server therefore requires production write access (rollouts.update in production) for a value change or a removal. Developers and Product managers are refused; Release managers and Admins are not.

Do it with the API#

These are Dashboard API calls that use your session cookie and return the usual { status, message, data } envelope.

Replace the variants and set an environment's split

Sending the variant list replaces it: whatever you leave out is removed, subject to the rules above. The response is trimmed here. Variants are set at creation with the variants field of POST /api/flags. See the Flags API and Rollouts API.

Request
# Replace the whole variant list (flags.update)
curl -X PUT "https://flags.example.com/api/flags/FLAG_ID/variants" \
  -b jar.txt -H "Content-Type: application/json" \
  -d '{"variants":[
    {"key":"classic","name":"Classic layout","value":"classic"},
    {"key":"compact","name":"Compact layout","value":"compact"}
  ]}'

# Split people 50/50 in development (rollouts.update)
curl -X PATCH "https://flags.example.com/api/flags/FLAG_ID/environments/development" \
  -b jar.txt -H "Content-Type: application/json" \
  -d '{"offVariant":"classic","allocation":{"classic":50,"compact":50}}'
Response
{
  "status": "success",
  "message": "Environment updated successfully",
  "data": {
    "id": "b7d2e4f1-91c3-4a58-8e60-2c1f7a9d3b05",
    "name": "checkout-layout",
    "type": "string",
    "variants": [
      { "key": "classic", "name": "Classic layout", "value": "classic" },
      { "key": "compact", "name": "Compact layout", "value": "compact" }
    ],
    "environments": {
      "development": { "enabled": true, "offVariant": "classic", "allocation": { "classic": 50, "compact": 50 }, "version": 4 }
    }
  }
}

What to check#

  • The Variants tab appears on the flag, and only for non-boolean flags.
  • The response shows the variant you expect for a test person, and the same person gets the same variant on the next request.
  • The weights for each environment add up to 100.

Good to know#

Prefer Boolean when you can

A Boolean flag has no variants to remove later, and its cleanup is a one-line code change. Reach for variants when code genuinely needs different values, not as a way to store configuration.
Can I turn a Boolean flag into a String flag?
No. The type is fixed at creation. Create a new flag, move the code over, then archive the old one.
What does a person get when the flag is off?
The variant chosen under Served when the flag is off, which defaults to the first variant. The same variant is served when the kill switch is active.
Why can I not rename a variant key?
Environments, rules and your code refer to the key. Add a new variant with the key you want, move its traffic over, then remove the old one.
How do variants relate to rollout percentage?
The rollout and targeting decide whether the flag is on for a person. The weights then choose which variant an on person gets.

If something goes wrong#

A string flag needs at least 2 variants

Why: Non-boolean flags must have 2 to 20 variants. The server answers 400 with this message (with your type in it).

Fix: Add another variant, or choose Boolean if you only need on and off.

Variant "x" needs a valid json value, or Enter a JSON object or array

Why: A JSON variant must be an object or array. A bare string, number or null is refused, as is invalid JSON or text over 16,384 characters.

Fix: Wrap the value, for example {"limit": 10}.

Allocation must add up to 100%

Why: The weights for the environment do not total 100, within two decimals.

Fix: Adjust the weights until the total under the list reads 100%.

Variant "x" is still served in production. Move its traffic to another variant first

Why: An environment still gives that variant a weight above 0 or uses it as the off variant (a 409).

Fix: Set its weight to 0 in each named environment, change the off variant if needed, save, then remove it.

Variant changes are refused in production

Why: Changing a value or removing a variant needs production write access, which Developers and Product managers do not have.

Fix: Ask a Release manager or Admin to make the change.