Skip to content

Latest commit

 

History

History
306 lines (249 loc) · 15 KB

flag-definitions.md

File metadata and controls

306 lines (249 loc) · 15 KB
description
flagd flag definition

Flag Definitions

Flags

flags is a required property. The flags property is a top level property that contains a collection of individual flags and their corresponding flag configurations.

{
  "flags": {
    ...
  }
}

Flag Definition

flag key is a required property. The flag key must uniquely identify a flag so that it can be used during flag evaluation. The flag key should convey the intent of the flag.

{
  "flags": {
    "new-welcome-banner": {
      ...
    }
  }
}

Flag properties

A fully configured flag may look like this.

{
  "flags": {
    "new-welcome-banner": {
      "state": "ENABLED",
      "variants": {
        "true": true,
        "false": false
      },
      "defaultVariant": "false",
      "targeting": { "in": ["@example.com", { "var": "email" }] }
    }
  }
}

See below for a detailed description of each property.

State

state is a required property. Validate states are "ENABLED" or "DISABLED". When the state is set to "DISABLED", flagd will behave like the flag doesn't exist.

Example:

"state": "ENABLED"

Variants

variants is a required property. It is an object containing the possible variations supported by the flag. All the values of the object must be the same type (e.g. boolean, numbers, string, JSON). The type used as the variant value will correspond directly affects how the flag is accessed. For example, to use a flag configured with boolean values the /schema.v1.Service/ResolveBoolean path should be used. If another path such as /schema.v1.Service/ResolveString is called, a type mismatch occurred and an error is returned.

Example:

"variants": {
  "red": "c05543",
  "green": "2f5230",
  "blue": "0d507b"
}

Example:

"variants": {
  "on": true,
  "off": false
}

Example of an invalid configuration:

"variants": {
  "on": true,
  "off": "false"
}

Default Variant

defaultVariant is a required property. The value must match the name of one of the variants defined above. The default variant is always used unless a targeting rule explicitly overrides it.

Example:

"variants": {
  "on": true,
  "off": false
},
"defaultVariant": "off"

Example:

"variants": {
  "red": "c05543",
  "green": "2f5230",
  "blue": "0d507b"
},
"defaultVariant": "red"

Example of an invalid configuration:

"variants": {
  "red": "c05543",
  "green": "2f5230",
  "blue": "0d507b"
},
"defaultVariant": "purple"

Targeting Rules

targeting is an optional property. A targeting rule must be valid JSON. Flagd uses a modified version of JsonLogic, as well as some custom pre-processing, to evaluate these rules. The output of the targeting rule must match the name of one of the variants defined above. If an invalid or null value is returned by the targeting rule, the defaultVariant value is used. If no targeting rules are defined, the response reason will always be STATIC, this allows for the flag values to be cached, this behavior is described here.

Evaluation Context

Evaluation context is included as part of the evaluation request. For example, when accessing flagd via HTTP, the POST body may look like this:

{
  "flagKey": "booleanFlagKey",
  "context": {
    "email": "[email protected]"
  }
}

The evaluation context can be accessed in targeting rules using the var operation followed the evaluation context property name.

Description Example
Retrieve property from the evaluation context #!json { "var": "email" }
Retrieve property from the evaluation context or use a default #!json { "var": ["email", "[email protected]"] }
Retrieve a nested property from the evaluation context #!json { "var": "user.email" }

For more information, see the var section in the JsonLogic documentation.

Conditions

Conditions can be used to control the logical flow and grouping of targeting rules.

Conditional Example
If Logic: #!json {"if" : [ true, "yes", "no" ]}
Result: "yes"

Logic: #!json {"if" : [ false, "yes", "no" ]}
Result: "no"
If else Logic: #!json {"if" : [ false, "yes", false, "no", "maybe" ]}
Result: "maybe"

Logic: #!json {"if" : [ false, "yes", false, "no", false, "maybe", "who knows" ]}
Result: "who knows"
Or Logic: #!json {"or" : [ true, false ]}
Result: true

Logic: #!json {"or" : [ false, false ]}
Result: false
And Logic: #!json {"and" : [ true, false ]}
Result: false

Logic: #!json {"and" : [ true, true ]}
Result: true

Operations

Operations are used to take action on, or compare properties retrieved from the context. These are provided out-of-the-box by JsonLogic.

Operator Description Context type Example
Equals Attribute equals the specified value, with type coercion. any Logic: #!json { "==" : [1, 1] }
Result: true

Logic: #!json { "==" : [1, "1"] }
Result: true
Strict equals Attribute equals the specified value, with strict comparison. any Logic: #!json { "===" : [1, 1] }
Result: true

Logic: #!json { "===" : [1, "1"] }
Result: false
Not equals Attribute doesn't equal the specified value, with type coercion. any Logic: #!json { "!=" : [1, 2] }
Result: true

Logic: #!json { "!=" : [1, "1"] }
Result: false
Strict not equal Attribute doesn't equal the specified value, with strict comparison. any Logic: #!json { "!==" : [1, 2] }
Result: true

Logic: #!json { "!==" : [1, "1"] }
Result: true
Exists Attribute is defined any Logic: #!json { "!!": [ "mike" ] }
Result: true

Logic: #!json { "!!": [ "" ] }
Result: false
Not exists Attribute is not defined any Logic: #!json {"!": [ "mike" ] }
Result: false

Logic: #!json {"!": [ "" ] }
Result: true
Greater than Attribute is greater than the specified value number Logic: #!json { ">" : [2, 1] }
Result: true

Logic: #!json { ">" : [1, 2] }
Result: false
Greater than or equals Attribute is greater or equal to the specified value number Logic: #!json { ">=" : [2, 1] }
Result: true

Logic: #!json { ">=" : [1, 1] }
Result: true
Less than Attribute is less than the specified value number Logic: #!json { "<" : [1, 2] }
Result: true

Logic: #!json { "<" : [2, 1] }
Result: false
Less than or equals Attribute is less or equal to the specified value number Logic: #!json { "<=" : [1, 1] }
Result: true

Logic: #!json { "<=" : [2, 1] }
Result: false
Between Attribute between the specified values number Logic: #!json { "<" : [1, 5, 10]}
Result: true

Logic: #!json { "<" : [1, 11, 10] }
Result: false
Between inclusive Attribute between or equal to the specified values number Logic: #!json {"<=" : [1, 1, 10] }
Result: true

Logic: #!json {"<=" : [1, 11, 10] }
Result: false
Contains Contains string string Logic: #!json { "in": ["Spring", "Springfield"] }
Result: true

Logic: #!json { "in":["Illinois", "Springfield"] }
Result: false
Not contains Does not contain a string string Logic: #!json { "!": { "in":["Spring", "Springfield"] } }
Result: false

Logic: #!json { "!": { "in":["Illinois", "Springfield"] } }
Result: true
In Attribute is in an array of strings string Logic: #!json { "in" : [ "Mike", ["Bob", "Mike"]] }
Result: true

Logic: #!json { "in":["Todd", ["Bob", "Mike"]] }
Result: false
Not it Attribute is not in an array of strings string Logic: #!json { "!": { "in" : [ "Mike", ["Bob", "Mike"]] } }
Result: false

Logic: #!json { "!": { "in":["Todd", ["Bob", "Mike"]] } }
Result: true

Custom Operations

These are custom operations specific to flagd and flagd providers. They are purpose built extensions to JsonLogic in order to support common feature flag use cases.

Function Description Example
fractional (available v0.6.4+) Deterministic, pseudorandom fractional distribution Logic: #!json { "fractional" : [ { "var": "email" }, [ "red" , 50], [ "green" , 50 ] ] }
Result: Pseudo randomly red or green based on the evaluation context property email.

Additional documentation can be found here.
starts_with Attribute starts with the specified value Logic: #!json { "starts_with" : [ "192.168.0.1", "192.168"] }
Result: true

Logic: #!json { "starts_with" : [ "10.0.0.1", "192.168"] }
Result: false
Additional documentation can be found here.
ends_with Attribute ends with the specified value Logic: #!json { "ends_with" : [ "[email protected]", "@example.com"] }
Result: true

Logic: #!json { ends_with" : [ "[email protected]", "@test.com"] }
Result: false
Additional documentation can be found here.
sem_ver Attribute matches a semantic versioning condition Logic: #!json {"sem_ver": ["1.1.2", ">=", "1.0.0"]}
Result: true

Additional documentation can be found here.

$flagd properties in the evaluation context

Flagd adds the following properties to the evaluation context that can be used in the targeting rules.

Property Description From version
$flagd.flagKey the identifier for the flag being evaluated v0.6.4
$flagd.timestamp a unix timestamp (in seconds) of the time of evaluation v0.6.7

Shared evaluators

$evaluators is an optional property. It's a collection of shared targeting configurations used to reduce the number of duplicated targeting rules.

Example:

{
  "flags": {
    "fibAlgo": {
      "variants": {
        "recursive": "recursive",
        "memo": "memo",
        "loop": "loop",
        "binet": "binet"
      },
      "defaultVariant": "recursive",
      "state": "ENABLED",
      "targeting": {
        "if": [
          {
            "$ref": "emailWithFaas"
          },
          "binet",
          null
        ]
      }
    },
    "headerColor": {
      "variants": {
        "red": "#FF0000",
        "blue": "#0000FF",
        "green": "#00FF00",
        "yellow": "#FFFF00"
      },
      "defaultVariant": "red",
      "state": "ENABLED",
      "targeting": {
        "if": [
          {
            "$ref": "emailWithFaas"
          },
          {
            "fractional": [
              { "var": "email" },
              ["red", 25],
              ["blue", 25],
              ["green", 25],
              ["yellow", 25]
            ]
          },
          null
        ]
      }
    }
  },
  "$evaluators": {
    "emailWithFaas": {
      "in": [
        "@faas.com",
        {
          "var": ["email"]
        }
      ]
    }
  }
}

Examples

Sample configurations can be found at https://github.com/open-feature/flagd/tree/main/config/samples.