---
name: kimaai_settings_schema_files
type: filter
since: 1.2.2
tier: free
feature: none
area: settings-admin
summary: Adds an add-on's own settings files to the KimaAI settings, each with its pages and fields, stored and saved like KimaAI's own.
parameters:
  - name: files
    type: string[]
    description: The paths of the settings files, KimaAI's own (app/Admin/config/*.php) first.
returns:
  type: string[]
  description: The files. KimaAI adds its own back if a callback removed them, and ignores what is not a path.
---

# kimaai_settings_schema_files

## When it fires

Whenever KimaAI builds its settings schema: on `init`, when it registers its settings with WordPress, and again when the settings app, the settings export and import, the admin assistant or the MCP tools read the schema. So add the filter when your plugin loads, not on `init`, or your settings cannot be saved.

Each file returns an array with the `schema` of one settings group. The file's name is the group's key: `myAddon.php` is stored under `myAddon` in the option `kimaai_options`, and the REST route `/wp/v2/settings` reads and saves it with KimaAI's settings. A group holds pages (`link`, `pageTitle`, `pageDescription`, `sections`) and a page holds fields (`type`, `default`, `component`, `props`, `section`). A page shows in the KimaAI menu at the end, under the group's title. A field's `component` is a key of the field components (`TextField`, `TextareaField`, `ToggleField`, `SelectField` and others, or your own through `kimaai.admin.fieldComponents`); a field with an unknown component is not shown. A section's `icon` is one of the Lucide names KimaAI bundles (`src/admin/app/sectionIcons.js`); any other name shows the default icon.

A string is saved through `sanitize_text_field()` unless the field names a `sanitize_callback`. A field with `'isSensitive' => true` is a secret: the settings app gets "saved" instead of its value, and the settings export leaves it blank.

Callbacks add files, they cannot remove any: KimaAI adds its own files back after the filter, so their settings are never dropped, and a key stays secret when any file marks it. Give your file a name of its own: a file with the name of a KimaAI group (`chatbot.php`, `tools.php`) defines that group a second time, and only one of the two definitions is used.

Stored values whose keys leave the schema are removed the next time the schema changes. When your add-on is deactivated, its group leaves the schema and its values in `kimaai_options` are removed on the next request; they are not there when it is activated again.

## Example

```php
add_filter(
  'kimaai_settings_schema_files',
  function (array $files): array {
    $files[] = __DIR__ . '/settings/myAddon.php';
    return $files;
  }
);
```

The file `settings/myAddon.php` of the add-on, one page with one setting:

```php
<?php
return [
  'schema' => [
    'type' => 'object',
    'title' => __('My add-on', 'my-addon'),
    'properties' => [
      'general' => [
        'type' => 'object',
        'title' => __('My add-on', 'my-addon'),
        'link' => 'my-addon',
        'pageTitle' => __('My add-on', 'my-addon'),
        'pageDescription' => __('Where my add-on sends its weekly report.', 'my-addon'),
        'sections' => [
          'report' => [
            'icon' => 'Send',
            'title' => __('Weekly report', 'my-addon'),
          ],
        ],
        'properties' => [
          'reportEmail' => [
            'section' => 'report',
            'type' => 'string',
            'default' => '',
            'component' => 'TextField',
            'sanitize_callback' => 'sanitize_email',
            'props' => [
              'type' => 'email',
              'label' => __('Report address', 'my-addon'),
              'description' => __('Leave it empty for no report.', 'my-addon'),
            ],
          ],
        ],
      ],
    ],
  ],
];
```

The page opens at `admin.php?page=kimaai&tab=my-addon`. Your code reads the value from the option:

```php
$options = get_option('kimaai_options', []);
$report_email = $options['myAddon']['general']['reportEmail'] ?? '';
```

## Related

- `kimaai.admin.fieldComponents`: draws a field with your own component.
- `kimaai_trigger_button_click`: reacts to a button on your settings page.
