--- title: "Site settings definitions" manual: "TYPO3 Explained" version: "main" permalink: "https://docs.typo3.org/permalink/t3coreapi:site-settings-definition@main" source: "ApiOverview/SiteHandling/SiteSettingDefinitions.rst" rendered: "2026-09-21T11:24:09+00:00" --- # Site settings definitions {#site-settings-definition} Site settings definitions define the public configuration contract for site settings: their identifier, type and guaranteed default value. They are defined in [site sets](https://docs.typo3.org/permalink/t3coreapi:site-sets@main), in a file called `settings.definitions.yaml`. > [!IMPORTANT] > An extension that introduces a setting **MUST** also own and provide its > definition. This keeps the description, validation rules and fallback value > available wherever the feature is used. Integrating sets and individual > sites can then override the value without copying the contract. A value in `settings.yaml` does not create a definition. Define a setting before reading or overriding it; see [site settings](https://docs.typo3.org/permalink/t3coreapi:sitehandling-settings@main). All defined settings from the active sets are displayed in the [site settings editor](https://docs.typo3.org/permalink/t3coreapi:site-settings-editor@main). Categories, labels and descriptions mainly describe how a setting appears to an integrator. The setting identifier, type and default define the runtime contract used by application code. The site settings provided by an extension can be automatically documented in the extensions manual, see [site settings documentation](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/SiteSettings.html#reference-site-settings). **On this page** - [Site setting definition example](https://docs.typo3.org/permalink/t3coreapi:site-setting-definition-example@main) - [Site setting definition properties](https://docs.typo3.org/permalink/t3coreapi:site-setting-definition-properties@main) - [Setting types](https://docs.typo3.org/permalink/t3coreapi:setting-types@main) - [Translating labels and descriptions for settings](https://docs.typo3.org/permalink/t3coreapi:translating-labels-and-descriptions-for-settings@main) ## Site setting definition example {#site-settings-definition-example} The top-level `settings` section contains the contracts, keyed by setting identifier. Each definition provides at least a type and a default value; labels and descriptions make it understandable in the editor. **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml** ```yaml settings: myExtension.categoryPid: label: 'Category storage page' description: 'Page that stores the category records.' type: page default: 0 ``` Categories are optional and do not change how a setting is read. See [Configuring the site settings editor](https://docs.typo3.org/permalink/t3coreapi:sitehandling-settings-editor-configuration@main) for a complete annotated example with categories and the resulting editor fields. ## Site setting definition properties {#site-settings-definition-properties} - **categories** - *Type:* array Defines groups used to organize settings in the editor. - **label** - *Type:* string Human-readable category label. - **parent** - *Type:* [categories](https://docs.typo3.org/permalink/t3coreapi:confval-site-settings-definition-categories@main) key Places the category below another category. - **settings** - *Type:* array Defines the settings provided by the set. Each array key is the setting identifier. - **label** - *Type:* string Required unless TYPO3 can derive the label from a `labels.xlf` file in the set directory. See [Translating labels and descriptions for settings](https://docs.typo3.org/permalink/t3coreapi:site-settings-definition-translation@main). - **description** - *Type:* string - *Example:* 'Configure `baz` to be used in `bar`.' While Markdown syntax can be used in YAML to provide rich text formatting, there are a few gotchas. Because YAML is sensitive to special characters and indentation, you might need to wrap your Markdown text in single quotes (') to prevent it from breaking the YAML syntax. - **category** - *Type:* [categories](https://docs.typo3.org/permalink/t3coreapi:confval-site-settings-definition-categories@main) key - **type** - *Type:* a [definition type](https://docs.typo3.org/permalink/t3coreapi:definition-types@main) - *Required:* true - **default** - *Type:* mixed - *Required:* true The default value must have the same type as defined in [type](https://docs.typo3.org/permalink/t3coreapi:confval-site-settings-definition-settings-type@main). - **readonly** - *Type:* bool If a site setting is marked as readonly, it can be overridden only by editing the [`config/sites/my-site/settings.yaml`](../../Administration/DirectoryStructure/SiteFolder.md#file-site-config-sites-my-site-settings-yaml) directly, but not from within the editor. - **enum** - *Type:* array - *types:* [string](https://docs.typo3.org/permalink/t3coreapi:confval-site-setting-type-string@main) Enum labels can be localized, see Feature: #106640 - Localize enum labels in site settings definitions.Site settings can provide possible options via the `enum` specifier, which are selectable in the editor. `enum` is not a separate definition type; combine it with a compatible type such as [string](https://docs.typo3.org/permalink/t3coreapi:confval-site-setting-type-string@main). List-style enum declarations (a plain array of values) derive a translation key using `settings..enum.`, see [Translating enum labels](https://docs.typo3.org/permalink/t3coreapi:site-settings-definition-translation-enum@main). Map-style enum declarations (`value: label`) use the given label directly: it can be a literal string, an explicit `LLL:` reference, or omitted to fall back to the enum value itself. **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml** ```yaml settings: my.enumSetting: label: 'My setting with options' type: string default: 'valueA' enum: valueA: 'Label of value A' valueB: 'Label of value B' ``` ![Screenshot of a site setting with selectable enum values](../../Images/ManualScreenshots/SiteHandling/SiteSettingsTypeEnum.png) - **tags** - *Type:* array Optional metadata tags for the setting definition. - **options** - *Type:* array Type-specific options. For example, the [url](https://docs.typo3.org/permalink/t3coreapi:confval-site-setting-type-url@main) type accepts a `pattern` option for an additional regular expression check. > [!NOTE] > The `settings.definitions.yaml` does not allow any kind of imports. All > settings must be defined in a single file. ## Setting types {#definition-types} - **int** - *Type:* string - *Path:* settings.\[my_val\].type = int ![Screenshot of a site setting field of type int](../../Images/ManualScreenshots/SiteHandling/SiteSettingsTypeInt.png) Checks whether the value is already an integer or can be interpreted as an integer. If yes, the string is converted into an integer. **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml** ```yaml settings: example.types.int: type: int default: 42 category: Example.types label: 'Type int' description: 'Checks whether the value is already an integer or can be interpreted as an integer. If yes, the string is converted into an integer.' ``` - **number** - *Type:* string - *Path:* settings.\[my_val\].type = number Checks whether the value is already an integer or float or whether the string can be interpreted as an integer or float. If yes, the string is converted to an integer or float. **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml** ```yaml settings: example.types.number: type: number default: 3.16 category: Example.types label: 'Type number' description: 'Checks whether the value is already an integer or float or whether the string can be interpreted as an integer or float. If yes, the string is converted to an integer or float.' ``` - **bool** - *Type:* string - *Path:* settings.\[my_val\].type = bool ![Screenshot of a site setting field of type bool](../../Images/ManualScreenshots/SiteHandling/SiteSettingsTypeBool.png) If the value is already a boolean, it is returned directly 1 to 1. If the value is an integer, then `false` is returned for 0 and `true` for 1. If the value is a string, the corresponding Boolean value is returned for `true`, `false`, `yes`, `no`, `on`, `off`, `0` and `1`. **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml** ```yaml settings: example.types.bool: type: bool default: true category: Example.types label: 'Type bool' description: 'Casts the value to a boolean.' example.types.bool-false: type: bool default: false category: Example.types label: 'Type bool' description: 'Casts the value to a boolean.' ``` - **string** - *Type:* string - *Path:* settings.\[my_val\].type = string ![Screenshot of a site setting field of type string](../../Images/ManualScreenshots/SiteHandling/SiteSettingsTypeString.png) Converts almost all data types into a string. If an object has been specified, it must be `stringable`, otherwise no conversion takes place. Boolean values are converted to `true` and `false`. **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml** ```yaml settings: example.types.string: type: string default: 'EXT:example/Resources/Private/Templates/' category: Example.types label: 'Type string' description: 'Converts almost all data types into a string. If an object has been specified, it must be stringable, otherwise no conversion takes place. Boolean values are converted to "true" and "false".' ``` - **text** - *Type:* string - *Path:* settings.\[my_val\].type = text Uses the same validation and conversion as the `string` type, but identifies the setting as longer text in the editor. **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml** ```yaml settings: example.types.text: type: text default: 'EXT:example/Resources/Private/Templates/' category: Example.types label: 'Type text' description: 'Uses the same validation and conversion as the `string` type, but identifies the setting as longer text in the editor.' ``` - **stringlist** - *Type:* string - *Path:* settings.\[my_val\].type = stringlist ![Screenshot of a site setting field of type stringlist](../../Images/ManualScreenshots/SiteHandling/SiteSettingsTypeStringlist.png) The value must be an array whose array key starts at 0 and increases by 1 per element. This sequence is checked using the internal PHP method array_is_list in order to prevent named array keys from the outset. This also means that comma-separated lists cannot be converted here. The `string` type is executed for each array entry. **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml** ```yaml settings: example.types.stringlist: type: stringlist default: ['Dog', 'Cat', 'Bird', 'Spider'] category: Example.types label: 'Type stringlist' description: 'The value must be an array whose array keys start at 0 and increase by 1 per element. The list in this type is derived from the internal PHP method array_is_list() and has nothing to do with the fact that comma-separated lists can also be converted here. The `string` type is executed for each array entry.' ``` - **color** - *Type:* string - *Path:* settings.\[my_val\].type = color ![Screenshot of a site setting field of type color](../../Images/ManualScreenshots/SiteHandling/SiteSettingsTypeColor.png) Checks whether the specified string can be interpreted as a color code. Entries starting with `rgb`, `rgba` and `#` are permitted here. For `#` color codes, for example, the system checks whether they have 3, 6 or 8 digits. **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml** ```yaml settings: example.types.color: type: color default: '#FF8700' category: Example.types label: 'Type color' description: 'Checks whether the specified string can be interpreted as a color code. Entries starting with `rgb`, `rgba` and `#` are permitted here. For `#` color codes, for example, the system checks whether they have 3, 6 or 8 digits.' ``` - **page** - *Type:* string - *Path:* settings.\[my_val\].type = page ![Screenshot of a site setting field of type page](../../Images/ManualScreenshots/SiteHandling/SiteSettingsTypePage.png) Checks whether the value is already an integer or can be interpreted as an integer. If yes, the string is converted into an integer. Additionally renders a page browser in the settings editor to allow the user to select a page for a specific setting, while still displaying the UID in the field. **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml** ```yaml settings: example.types.page: type: page default: 0 category: Example.types label: 'Example page' description: 'Page id which can be supplied as an integer or a string.' ``` - **url** - *Type:* string - *Path:* settings.\[my_val\].type = url Validates that the value is a URL. An empty value is accepted. Use the type-specific `options.pattern` property to require an additional regular expression match. **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml** ```yaml settings: example.types.url: type: url default: 'https://example.com/' category: Example.types label: 'Type URL' description: 'Validates that the value is a URL.' ``` ## Translating labels and descriptions for settings {#site-settings-definition-translation} To translate labels and descriptions, create a `labels.xlf` file next to the set's `config.yaml` and `settings.definitions.yaml`. TYPO3 uses different translation unit identifiers for the set, categories, settings and enum values. When a matching translation exists, you can omit the corresponding literal label or description from the YAML file. The set label uses the translation unit identifier `label`: **Example** **Example label definition in labels.xlf** ```xml My Custom Set ``` > [!IMPORTANT] > To translate the labels of your settings using Crowdin, you need to adjust > your extension's > [Crowdin configuration file](https://docs.typo3.org/permalink/t3coreapi:crowdin-extension-integration-github-configure@main). ### Translating category labels {#site-settings-definition-translation-category} To translate category labels and descriptions, use the following format: **Example category label definitions** ```xml My Custom Category Description of My Custom Category ``` ### Translating settings labels and descriptions {#site-settings-definition-translation-labels} To translate the label and description of a specific setting, use this structure: **Example setting label definitions** ```xml My Custom Setting My Custom Setting description ``` ### Translating enum labels {#site-settings-definition-translation-enum} To translate the labels of [enum](https://docs.typo3.org/permalink/t3coreapi:confval-site-settings-definition-settings-enum@main) options for list-style enum declarations (a plain array of values), use this structure: **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml** ```yaml settings: mycustomsetting: label: 'My custom setting' type: string enum: - optionA - optionB ``` **Matching labels in labels.xlf** ```xml Option A Option B ``` Map-style enum declarations (`value: label`) are independent of this key schema: the given label is used as-is, unless it is an explicit `LLL:` reference. **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml** ```yaml settings: mycustomsetting: label: 'My custom setting' type: string enum: optionA: 'LLL:EXT:my_extension/Configuration/Sets/MySet/labels.xlf:settings.custom.optionA' optionB: 'Literal Option B' optionC: ``` **Referenced label in labels.xlf** ```xml Option A (localized) ``` In this example, `optionA` resolves the referenced `LLL:` label, `optionB` keeps its literal label as-is, and `optionC` has no label and falls back to the enum value `optionC` itself. ### Translations for other languages {#site-settings-definition-translation-languages} To provide translations in another language, use the two-letter language prefix in the filename. For example: `de.labels.xlf`