dataSourceConfigVar()

The dataSourceConfigVar() function defines a config variable whose values are dynamically populated by a data source — either an inline data source function or a reference to a data source in a registered component. This is useful for config variables whose valid values depend on the customer’s account data (e.g., a list of available projects, channels, or mailboxes). A data source config var can be defined in two ways:

Data source definition — an inline function with a perform handler that fetches and returns values dynamically.
Data source reference — a reference to a data source action defined in a component from the componentRegistry.

Function signature

export const dataSourceConfigVar = <TDataSourceConfigVar extends DataSourceConfigVar>(
  definition: TDataSourceConfigVar,
): TDataSourceConfigVar

Parameters

definition

DataSourceConfigVar

required

An object describing the data source config variable.

Hide Common fields

stableKey

string

required

A unique, unchanging identifier for this config variable.

dataSourceType

DataSourceType

required

The type of data returned by the data source. This determines the UI control rendered for the config variable.

Value	Description
`"picklist"`	Returns a list of selectable string values
`"objectSelection"`	Returns a list of selectable objects
`"objectFieldMap"`	Returns a field mapping structure
`"jsonForm"`	Returns a JSON Form schema and UI schema
`"string"`	Returns a single string value

description

string

Human-readable description for this config variable.

collectionType

'valuelist' | 'keyvaluelist'

When set, the data source returns a collection of values. Available only for collection-compatible data source types.

permissionAndVisibilityType

'customer' | 'embedded' | 'organization'

default:"customer"

Controls who can view and edit this config variable.

visibleToOrgDeployer

boolean

default:"true"

Whether this config variable is visible to an organization deployer.

Show Data source definition fields (inline function)

perform

DataSourcePerformFunction

required

An async function that fetches and returns data for this config variable. Called whenever the config wizard loads or refreshes this variable.The function receives (context, params) and must return an object matching the dataSourceType:

picklist → { result: PickList }
objectSelection → { result: ObjectSelection }
objectFieldMap → { result: ObjectFieldMap }
jsonForm → { result: JSONForm }

inputs

Record<string, InputFieldDefinition>

Input fields for the data source function, similar to action inputs.

validationMode

ValidationMode

Validation mode for dataSourceType: "jsonForm" data source config variables.

dataSourceReset

DataSourceReset

Determines when the data source should reset when dependent config variables change.

Show DataSourceReset fields

mode

'prompt' | 'always'

required

"prompt" — Ask the user to reset when a dependency changes.
"always" — Automatically reset when a dependency changes.

dependencies

string[]

Names of config variables that should trigger a reset when changed.

Show Data source reference fields (component data source)

dataSource

ComponentReference

required

A reference to a data source defined in a component from the componentRegistry. Includes the component key, data source key, and input values.

Show dataSource fields

component

string

required

The key of the component.

key

string

required

The key of the data source within the component.

values

object

Input values for the data source, each as a ValueExpression, ConfigVarExpression, or TemplateExpression.

validationMode

ValidationMode

Validation mode for JSON Form data sources.

dataSourceReset

Omit<DataSourceReset, 'dependencies'>

Reset configuration for this data source reference. Only mode is available (no dependencies).

Return type

dataSourceConfigVar

TDataSourceConfigVar

The same data source config variable definition object passed in, unchanged. Used for type inference.

When using a data source reference backed by a component connection, the data source can automatically use a connection config variable from the same config page by passing a ConfigVarExpression as an input value.

Examples

import {
  configPage,
  connectionConfigVar,
  dataSourceConfigVar,
} from "@prismatic-io/spectral";

const settingsPage = configPage({
  tagline: "Configure sync settings",
  elements: {
    "Acme Connection": connectionConfigVar({
      stableKey: "acme-connection",
      dataType: "connection",
      inputs: {
        apiKey: {
          label: "API Key",
          type: "password",
          required: true,
          clean: (v) => String(v),
        },
      },
    }),
    "Target Project": dataSourceConfigVar({
      stableKey: "target-project",
      dataSourceType: "picklist",
      description: "Select the project to sync to.",
      perform: async (context, params) => {
        const connection = context.configVars["Acme Connection"];
        const apiKey = connection.fields["apiKey"];
        const response = await fetch("https://api.acme.com/projects", {
          headers: { Authorization: `Bearer ${apiKey}` },
        });
        const projects = await response.json();
        return {
          result: projects.map((p: { id: string; name: string }) => ({
            label: p.name,
            value: p.id,
          })),
        };
      },
    }),
  },
});

configPage() — The page that contains this data source config variable.
configVar() — For static config variables that don’t require a data source.
connectionConfigVar() — For connection config variables.
componentManifest() — Register components whose data sources can be referenced.

Core Functions

Code-Native Integration Functions

Testing Utilities

Utility Module

dataSourceConfigVar()

Function signature

Parameters

Return type

Examples

Build docs developers (and LLMs) love

Core Functions

Code-Native Integration Functions

Testing Utilities

Utility Module

Documentation Index

​Function signature

​Parameters

​Return type

​Examples

​Related

Build docs developers (and LLMs) love

Function signature

Parameters

Return type

Examples

Related