---
sidebar_position: 20
description: What is a flag and how you can create them.
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

# How to configure a flag

**GO Feature Flag** core feature is to centralize all your feature flags in a source file, and to avoid hosting and maintaining a backend server to manage them.

Your file must be a valid `YAML`, `JSON` or `TOML` file with a list of flags
_(examples: [`YAML`](https://github.com/thomaspoignant/go-feature-flag/tree/main/testdata/flag-config.yaml),
[`JSON`](https://github.com/thomaspoignant/go-feature-flag/tree/main/testdata/flag-config.json),
[`TOML`](https://github.com/thomaspoignant/go-feature-flag/tree/main/testdata/flag-config.toml))_.

:::tip
The easiest way to create your configuration file is to used
[**GO Feature Flag Editor** available at [https://editor.gofeatureflag.org](https://editor.gofeatureflag.org).

If you prefer to do it manually please follow instruction bellow.
:::

## Editor

Creating the first version of the flag is not always pleasant, that's why we have created
[**GO Feature Flag Editor**](https://editor.gofeatureflag.org) a simple editor to create your files.

## Example

A flag configuration looks like:

<Tabs groupId="code">
  <TabItem value="yaml" label="YAML">

```yaml
# This is your configuration for your first flag
first-flag:
  variations: # All possible return value for your feature flag
    A: false
    B: true
  targeting: # If you want to target a subset of your users in particular
    - query: key eq "random-key"
      percentage:
        A: 0
        B: 100
  defaultRule: # When no targeting match we use the defaultRule
    variation: A
  metadata:
    issue_link: https://github.com/thomaspoignant/go-feature-flag/issues/XXX
    description: this is my first feature flag

# A second example of a flag configuration
second-flag:
  variations:
    A: "valueA"
    B: "valueB"
    defaultValue: "a default value"
  targeting:
    - name: rule1
      query: key eq "not-a-key"
      percentage:
        A: 10
        B: 90
  defaultRule:
    name: defaultRule
    variation: defaultValue
  version: "12"
  experimentation:
    start: 2021-03-20T00:00:00.1-05:00
    end: 2021-03-21T00:00:00.1-05:00
```

  </TabItem>
  <TabItem value="json" label="JSON">

```json
{
  "first-flag": {
    "variations": {
      "A": false,
      "B": true
    },
    "targeting": [
      {
        "query": "key eq \"random-key\"",
        "percentage": {
          "A": 0,
          "B": 100
        }
      }
    ],
    "defaultRule": {
      "variation": "A"
    },
    "metadata": {
      "issue_link": "https://github.com/thomaspoignant/go-feature-flag/issues/XXX",
      "description": "this is my first feature flag"
    }
  },

  "second-flag": {
    "variations": {
      "A": "valueA",
      "B": "valueB",
      "defaultValue": "a default value"
    },
    "targeting": [
      {
        "name": "rule1",
        "query": "key eq \"not-a-key\"",
        "percentage": {
          "A": 10,
          "B": 90
        }
      }
    ],
    "defaultRule": {
      "name": "defaultRule",
      "variation": "defaultValue"
    },
    "version": "12",
    "experimentation": {
      "start": "2021-03-20T05:00:00.100Z",
      "end": "2021-03-21T05:00:00.100Z"
    }
  }
}
```

  </TabItem>
  <TabItem value="toml" label="TOML">

```toml
[first-flag.variations]
A = false
B = true

[[first-flag.targeting]]
query = 'key eq "random-key"'

  [first-flag.targeting.percentage]
  A = 0
  B = 100

[first-flag.defaultRule]
variation = "A"

[first-flag.metadata]
issue_link = "https://github.com/thomaspoignant/go-feature-flag/issues/XXX"
description = "this is my first feature flag"

[second-flag]
version = "12"

  [second-flag.variations]
  A = "valueA"
  B = "valueB"
  defaultValue = "a default value"

  [[second-flag.targeting]]
  name = "rule1"
  query = 'key eq "not-a-key"'

    [second-flag.targeting.percentage]
    A = 10
    B = 90

  [second-flag.defaultRule]
  name = "defaultRule"
  variation = "defaultValue"

  [second-flag.experimentation]
  start = 2021-03-20T05:00:00.100Z
  end = 2021-03-21T05:00:00.100Z
```

  </TabItem>
</Tabs>

## Format details

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td width="20%">
        <strong>flag-key</strong>
      </td>
      <td>
        Name of your flag.
        <br />
        <i>
          It must be unique.
          <br />
          On the example the flag keys are <code>test-flag</code> and{" "}
          <code>test-flag2</code>.
        </i>
      </td>
    </tr>
    <tr>
      <td>
        <code>variations</code>
      </td>
      <td>
        <p>Variations are all the variations available for this flag.</p>
        <p>
          It is represented as a key/value element. The key is the name of the
          variation and the value could be of any types available (
          <code>string</code>, <code>float</code>, <code>int</code>,{" "}
          <code>map</code>, <code>array</code>, <code>bool</code>).
        </p>
        <p>You can have as many variations as needed.</p>
        <pre>
          <h2>Some examples:</h2>
          <br />
          variationString: test
          <br />
          variationBool: true
          <br />
          variationInt: 1000
          <br />
          variationFloat: 1000.23
          <br />
          variationArray: <br /> - item1
          <br /> - item2
          <br />
          variationObj:
          <br /> item1: 123
          <br /> item2: this is a string
          <br /> item3: false
          <br />
        </pre>
      </td>
    </tr>
    <tr>
      <td>
        <code>targeting</code>
        <br />
        <i>(optional)</i>
      </td>
      <td>
        <p>
          Targeting contains the list of rules you have to target a subset of
          your users.
          <br />
          You can have as many target as needed.
        </p>
        <p>
          This field is an <code>array</code> and contains a list of rules.
        </p>
        <p>
          <i>
            See <a href="./rule_format">rules format</a> to have more info on
            how to write a rule.
          </i>
        </p>
      </td>
    </tr>
    <tr>
      <td>
        <code>defaultRule</code>
      </td>
      <td>
        <p>
          DefaultRule is the rule that is applied if the user does not match in
          any targeting.
        </p>
        <p>
          <i>
            See <a href="./rule_format">rules format</a> to have more info on
            how to write a rule.
          </i>
        </p>
      </td>
    </tr>
    <tr>
      <td>
        <code>trackEvents</code>
        <br />
        <i>(optional)</i>
      </td>
      <td>
        <p>
          <code>false</code> if you don't want to export the data in your data
          exporter.
        </p>
        <p>
          <b>Default:</b> <code>true</code>
        </p>
      </td>
    </tr>
    <tr>
      <td>
        <code>disable</code>
        <br />
        <i>(optional)</i>
      </td>
      <td>
        <p>
          <code>true</code> if the flag is disabled.
        </p>
        <p>
          <b>Default:</b> <code>false</code>
        </p>
      </td>
    </tr>
    <tr>
      <td>
        <code>version</code>
        <br />
        <i>(optional)</i>
      </td>
      <td>
        <p>
          The `version` is the version of your flag.
          <br />
          This string is used to display the information in the notifiers and
          data collection, you have to update it yourself.
        </p>
        <p>
          <b>Default:</b> <code>""</code>
        </p>
      </td>
    </tr>
    <tr>
      <td>
        <code>metadata</code>
        <br />
        <i>(optional)</i>
      </td>
      <td>
        <p>
          This field allows adding a wealth of information about a particular
          feature flag, such as a configuration URL or the originating Jira
          issue.
        </p>
      </td>
    </tr>
    <tr>
      <td>
        <code>scheduledRollout</code>
        <br />
        <i>(optional)</i>
      </td>
      <td>
        <p>`scheduledRollout` allows to patch your flag over time.</p>
        <p>
          You can add several steps that update the flag, this is typically
          used if you want to gradually add more user in your flag.
        </p>
        <p>
          <i>
            See <a href="./rollout/scheduled/">Scheduled rollout</a> to have
            more info on how to use it.
          </i>
        </p>
      </td>
    </tr>
    <tr>
      <td>
        <code>experimentation</code>
        <br />
        <i>(optional)</i>
      </td>
      <td>
        <p>
          Experimentation allows you to configure a start date and an end date
          for your flag. When the experimentation is not running, the flag will
          serve the default value.
        </p>
        <p>
          <i>
            See <a href="./rollout/experimentation/">Experimentation rollout</a>{" "}
            to have more info on how to use it.
          </i>
        </p>
      </td>
    </tr>
  </tbody>
</table>

## Advanced configurations

You can have advanced configurations for your flag for them to have specific behavior, such as:

- [Specific rollout strategies](../category/rollout-strategies/)
- [Don't track a flag](../go_module/data_collection/index.md#dont-track-a-flag)
