SettingsSchema

The install and settings forms as data — when the manifest binds the port for you, when to write your own, and how the Field objects reach the dashboard, the API and the apps.

Subscriby\Connector\Contracts\Ports\SettingsSchema. Required of every connector, and usually bound for you.

The dashboard, the REST API and the creator apps all render a connector's forms from these fields, so a connector needs no Blade to be installable. A UiSlots contribution may dress the same fields up on the web (a walkthrough video, a screenshot) but never replaces them.

Methods

Method	Called when	Returns
`installFields()`	The Connect dialog opens; `GET /connectors` and the MCP catalogue describe the connector; the kit.	`list<Field>`
`settingsFields(?InstallationRef)`	The installation's Configuration tab opens (with the installation) or the catalogue describes the defaults (with null).	`list<Field>`

The manifest binds it for you

A connector whose forms are plain fields declares them in connector.json under install.fields and install.settings_fields and binds nothing. When the registry sees a connector that declared fields and bound no SettingsSchema, it binds the SDK's ManifestSettingsSchema over the file. That class also translates every label, help text, step and select option through the package's lang/*.json files, so the dashboard, the API and the apps show the creator's language.

Every field is a Subscriby\Connector\Data\Field:

new Field(
    name: 'token',
    type: FieldType::Secret,
    label: 'Bot token',
    help: 'Keep it secret: anyone who has it controls the bot.',
    required: true,
    rules: ['string', 'min:20'],
    options: [],          // for a select: value => label
    value: null,          // the current value, on a settings form
    steps: [],            // for instructions: numbered steps with :app and :button
    links: [],            // text => https or mailto URL
);

The constructor enforces three rules itself and throws InvalidManifest otherwise: the name is a lower-case identifier, a select has options, every link target is https:// or mailto:.

When to write your own

Bind your own implementation when the fields depend on the installation: a select over the channels the connected server has, a toggle whose default the platform dictates, a link field pointing at the installation's own page on the platform. Then declare no fields in the manifest, because the registry binds ManifestSettingsSchema only when the file declares fields and the class binds nothing, and the kit's manifest.file_is_the_source compares field counts between the two.

settingsFields($installation) receives the installation being edited, so it can fill each field's value from your own row or from the platform. With null it returns the defaults, which is what the catalogue publishes.

How the values come back

The core validates every field's rules, then hands the values to you: every install value arrives in InstallationRequest::$fields and in the CredentialBag (the bag holds all submitted install fields and is what the core stores encrypted); settings values are written to the installation's settings by the core's UpdateInstallationSettings action (dashboard, PATCH …/installation/settings, MCP) after the same validation, and your ports read them from the InstallationRef's installation row through Core\Installations or from your own table if you mirror them.

How Telegram does it

Telegram declares its two install fields (the BotFather walkthrough and the token) in connector.json and binds no schema of its own; the video beside the form is its install slot.

What the kit checks

settings.install_fields: every entry is a Field, names are unique, every field has a label, and a paste_credential connector declares an input and a secret. settings.settings_fields: the same shape rules for settingsFields(null).

Secrets are secret twice

A secret field's value goes into the encrypted CredentialBag and is never returned by settingsFields(), GET /connectors or any resource. Do not put a token in a text field to make it editable; make the creator paste a new one through a reconnect.