Need comprehensive schema documentation for Flipt Flags in JSON and YAML

[rohitnarayan]

Description

Currently, there is no single reference that outlines the complete schema for Flipt Flags. Having a clear, detailed schema in both JSON and YAML formats would help developers understand how to define and manage flags consistently.

Requirements / Goals:

• Provide a complete schema definition for Flipt Flags.
• Include examples in JSON format.
• Include examples in YAML format.
• Highlight required fields, optional fields, data types, and constraints where applicable.
• Ensure it is versioned or linked to the current Flipt release for clarity.

Benefits:

• Makes Flipt Flags easier to understand and use correctly.
• Reduces errors in flag definitions and deployment.
• Helps integrate Flipt Flags into CI/CD pipelines and automation scripts.

Additional context:

If possible, include references to existing flag documentation, but consolidate the full schema in one easily accessible place.

[dosubot[bot]]

Here’s a comprehensive schema reference for Flipt Flags, including required/optional fields, data types, constraints, and canonical examples in both JSON and YAML. This reflects the current schema as implemented in recent Flipt releases (source, source, source).

---

Flipt Flag Schema (core fields)

Field	Type	Required	Description / Constraints
key	string	Yes	Unique flag key within the namespace
name	string	Yes	Human-readable name
type	string (enum)	Yes	BOOLEAN_FLAG_TYPE or VARIANT_FLAG_TYPE
enabled	boolean	Yes	Whether the flag is active
description	string	No	Optional description
metadata	object (map)	No	Arbitrary key-value pairs
variants	array of Variant	No	Required for VARIANT_FLAG_TYPE
rules	array of Rule	No	Targeting/rollout rules
rollouts	array of Rollout	No	Boolean flag rollouts (by segment or threshold)

Variant

Field	Type	Required	Description / Constraints
key	string	Yes	Unique variant key
name	string	Yes	Human-readable name
description	string	No	Optional description
attachment	object/any	No	Arbitrary data (JSON/YAML object)
default	boolean	No	Marks this as the default variant

Rule

Field	Type	Required	Description / Constraints
segment	string/object	Yes	Segment key or segment rule (must reference existing segment)
rank	integer	No	Rule priority/order
distributions	array of Distribution	Yes	Maps variants to rollout percentages

Distribution

Field	Type	Required	Description / Constraints
variant	string	Yes	Variant key
rollout	number	Yes	Percentage (0-100)

Rollout

Field	Type	Required	Description / Constraints
description	string	No	Optional description
segment	object	No	Segment-based rollout (see SegmentRule)
threshold	object	No	Threshold-based rollout (see ThresholdRule)

SegmentRule

Field	Type	Required	Description / Constraints
key/keys	string/[]	Yes	Segment key(s) (must exist in namespace)
operator	string	No	AND_SEGMENT_OPERATOR or OR_SEGMENT_OPERATOR
value	boolean	No	Used for evaluation

ThresholdRule

Field	Type	Required	Description / Constraints
percentage	number	Yes	0-100
value	boolean	Yes	Target value

---

Canonical JSON Example

{
  "version": "1.3",
  "flags": [
    {
      "key": "flag1",
      "name": "flag1",
      "type": "VARIANT_FLAG_TYPE",
      "description": "description",
      "enabled": true,
      "variants": [
        {
          "key": "variant1",
          "name": "variant1",
          "description": "variant description",
          "attachment": {
            "pi": 3.141,
            "happy": true,
            "name": "Niels",
            "answer": { "everything": 42 },
            "list": [1, 0, 2],
            "object": { "currency": "USD", "value": 42.99 }
          }
        }
      ],
      "rules": [
        {
          "segment": "segment1",
          "rank": 1,
          "distributions": [{ "variant": "variant1", "rollout": 100 }]
        }
      ],
      "metadata": {
        "label": "variant",
        "area": true
      }
    },
    {
      "key": "flag2",
      "name": "flag2",
      "type": "BOOLEAN_FLAG_TYPE",
      "description": "a boolean flag",
      "enabled": false,
      "rollouts": [
        {
          "description": "enabled for internal users",
          "segment": { "key": "internal_users", "value": true }
        },
        {
          "description": "enabled for 50%",
          "threshold": { "percentage": 50, "value": true }
        }
      ],
      "metadata": {
        "label": "bool",
        "area": 12
      }
    }
  ],
  "segments": [
    {
      "key": "segment1",
      "name": "segment1",
      "match_type": "ANY_MATCH_TYPE",
      "description": "description",
      "constraints": [
        {
          "type": "STRING_COMPARISON_TYPE",
          "property": "fizz",
          "operator": "neq",
          "value": "buzz"
        }
      ]
    }
  ]
}

(source)

---

Canonical YAML Example

version: "1.3"
flags:
  - key: flag1
    name: flag1
    type: "VARIANT_FLAG_TYPE"
    description: description
    enabled: true
    variants:
      - key: variant1
        name: variant1
        description: variant description
        attachment:
          pi: 3.141
          happy: true
          name: Niels
          answer:
            everything: 42
          list:
            - 1
            - 0
            - 2
          object:
            currency: USD
            value: 42.99
    rules:
      - segment: segment1
        rank: 1
        distributions:
          - variant: variant1
            rollout: 100
    metadata:
      label: variant
      area: true
  - key: flag2
    name: flag2
    type: "BOOLEAN_FLAG_TYPE"
    description: a boolean flag
    enabled: false
    rollouts:
      - description: enabled for internal users
        segment:
          key: internal_users
          value: true
      - description: enabled for 50%
        threshold:
          percentage: 50
          value: true
    metadata:
      label: bool
      area: 12
segments:
  - key: segment1
    name: segment1
    match_type: "ANY_MATCH_TYPE"
    description: description
    constraints:
      - type: STRING_COMPARISON_TYPE
        property: fizz
        operator: neq
        value: buzz

(source)

---

Constraints & Notes

• key, name, type, and enabled are required for each flag.
• type must be either BOOLEAN_FLAG_TYPE or VARIANT_FLAG_TYPE.
• All segment references in rules and rollouts must exist in the same namespace, or flag creation will fail (source).
• variants is required for VARIANT_FLAG_TYPE flags.
• metadata is a free-form object/map.
• The schema is versioned via the top-level version field (e.g., "1.3").
• Attachments and metadata can contain arbitrary nested data.

For more details, see the Go struct definitions and test data examples.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[erka]

Hey @rohitnarayan ,

Yeah... There are some missing dots in the documentation.

There is the schema for Flipt Flags. We provide the cue and json ones.

The flipt validate could help with flags validation. There is also Github action for this. Please check out these pages

• https://docs.flipt.io/cli/commands/validate
• https://docs.flipt.io/tooling/github-actions

[rohitnarayan]

@erka @markphelps Can I contribute by documenting the schema and configuration types for the flags, including an exhaustive list of configurable attributes?

[erka]

You're welcome!