> ## Documentation Index
> Fetch the complete documentation index at: https://confidence-auth-testing.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Define a Flag Schema

> Learn how to define the schema for a flag.

**Define a Flag Schema**

Learn how to define the schema for a flag.

[Do this in the app →](/docs/capabilities/flags/edit-flag-schema.md)

After creating a flag, define its schema to specify what fields the flag value can contain.

## Define the Schema

Set the schema on your flag:

```bash theme={null}
curl -X PATCH "https://flags.confidence.dev/v1/flags/example-flag?updateMask=schema" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": {
      "schema": {
        "enabled": {
          "boolSchema": {}
        },
        "color": {
          "stringSchema": {}
        },
        "size": {
          "intSchema": {}
        }
      }
    }
  }'
```

> [!TIP]
>
> Available schema types: `boolSchema`, `stringSchema`, `intSchema`, `doubleSchema`, `listSchema`, `structSchema`. See [Variants](/docs/reference/api/flags/concepts.md#variants) for details on how schemas work.

## Add Fields to an Existing Schema

To add new fields, include them in the schema:

```bash theme={null}
curl -X PATCH "https://flags.confidence.dev/v1/flags/example-flag?updateMask=schema" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": {
      "schema": {
        "enabled": {
          "boolSchema": {}
        },
        "color": {
          "stringSchema": {}
        },
        "size": {
          "intSchema": {}
        },
        "opacity": {
          "doubleSchema": {}
        }
      }
    }
  }'
```

## Define a Nested Schema

Use `structSchema` for nested fields:

```bash theme={null}
curl -X PATCH "https://flags.confidence.dev/v1/flags/example-flag?updateMask=schema" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": {
      "schema": {
        "button": {
          "structSchema": {
            "schema": {
              "color": {
                "stringSchema": {}
              },
              "size": {
                "intSchema": {}
              }
            }
          }
        }
      }
    }
  }'
```

## Define a List Schema

Use `listSchema` for array fields:

```bash theme={null}
curl -X PATCH "https://flags.confidence.dev/v1/flags/example-flag?updateMask=schema" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": {
      "schema": {
        "colors": {
          "listSchema": {
            "elementSchema": {
              "stringSchema": {}
            }
          }
        }
      }
    }
  }'
```

## Remove a Field

To remove a field, first update all variants to remove that field, then update the schema:

```bash theme={null}
curl -X PATCH "https://flags.confidence.dev/v1/flags/example-flag?updateMask=schema" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": {
      "schema": {
        "enabled": {
          "boolSchema": {}
        },
        "color": {
          "stringSchema": {}
        }
      }
    }
  }'
```

> [!NOTE]
>
> The request will fail if any variant still uses the field you're trying to remove.

## Next Steps

After defining your schema:

1. [Create variants](/docs/reference/api/how-to-guides/flags/create-flag-variants.md) with values matching the schema
2. [Create segments](/docs/reference/api/how-to-guides/flags/create-segment.md) to target audiences
3. [Create rules](/docs/reference/api/how-to-guides/flags/create-flag-rule.md) to assign variants