> ## Documentation Index
> Fetch the complete documentation index at: https://confidence.spotify.com/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.

export const HowToSchema = ({name, description, steps = []}) => {
  const schema = {
    "@context": "https://schema.org",
    "@type": "HowTo",
    name,
    description
  };
  if (steps.length > 0) {
    schema.step = steps.map((s, i) => ({
      "@type": "HowToStep",
      position: i + 1,
      name: typeof s === "string" ? s : s.name,
      text: typeof s === "string" ? s : s.text || s.name
    }));
  }
  return <script type="application/ld+json" dangerouslySetInnerHTML={{
    __html: JSON.stringify(schema)
  }} />;
};

<HowToSchema
  name="Define a Flag Schema"
  description="Learn how to define the schema for a flag."
  steps={[
{
  name: "Define the Schema",
  text: "Set the schema on your flag: Available schema types: boolSchema, stringSchema, intSchema, doubleSchema, listSchema, structSchema. See Variants for details on how schemas work.",
},
{
  name: "Add Fields to an Existing Schema",
  text: "To add new fields, include them in the schema:",
},
{
  name: "Define a Nested Schema",
  text: "Use structSchema for nested fields:",
},
{ name: "Define a List Schema", text: "Use listSchema for array fields:" },
{
  name: "Remove a Field",
  text: "To remove a field, first update all variants to remove that field, then update the schema: The request will fail if any variant still uses the field you're trying to remove.",
},
]}
/>

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](../../flags/concepts#variants) for details on how schemas work.
</Tip>

## 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.
</Note>

## Next Steps

After defining your schema:

1. [Create variants](./create-flag-variants) with values matching the schema
2. [Create segments](./create-segment) to target audiences
3. [Create rules](./create-flag-rule) to assign variants