> For the complete documentation index, see [llms.txt](https://docs.pandium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pandium.com/getting-started/anatomy-of-an-integration/pandium.yaml-spec/dependent-selector-configurations.md).

# Dependent Selector Configurations

Create dependent selector configs in PANDIUM.yaml where dynamic dropdown options update based on a parent field’s value, sourced from tenant metadata.

The last article explained how to make a dynamic configuration, a setting where the options are fetched from an API or database so they change from tenant to tenant

This article will explain how to make a dependent selector configuration, a setting where the options are fetched from an API or data base *and* vary based on the user's selection of an earlier config (which can also be dynamic)

### Here is an example of a dependent selector configuration:

A tenant settings page that allows the the user select their favorite food.

The options for the favorite food will be fetched from an API or database, so they will be different from tenant to tenant.

There will also be a food type configuration.

* The user's selection for food type will also affect what options are presented to the user when they are selecting their favorite food.
* The food type config is also dynamic, so the food type options will vary from tenant to tenant.

#### Here are what the options could look like to different users:

* Tenant A: food type options will be **Sweet** and **Savory**.

  <figure><img src="https://4017407078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfJn-9R_dn6dvcGNcdk%2Fuploads%2FYS45ITFW5sXamvPodqTb%2FScreenshot%202024-06-12%20at%203.56.17%20PM.png?alt=media&amp;token=c939afbc-c62f-4a66-93d3-61b3cc4cbd7f" alt=""><figcaption><p>The only food type option for Tenant A are "Sweet" and "Savory"</p></figcaption></figure>

  * If the user chooses food type **Sweet** then the favorite food options will be: **Chocolate**, **Caramel**, **Jello**

  <figure><img src="https://4017407078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfJn-9R_dn6dvcGNcdk%2Fuploads%2FH5Zh2pT51r0ETOoRzVvn%2FScreenshot%202024-06-12%20at%203.50.28%20PM.png?alt=media&amp;token=c6042170-079b-4136-a78c-4d40faf27cf5" alt=""><figcaption><p>When the user selects the "Sweet: food type, the options for favorite food are only sweet foods.</p></figcaption></figure>

  * If the user chooses food type **Savory** then the favorite food options will be: **Chips**, **Pizza**, **Bread**

  <figure><img src="https://4017407078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfJn-9R_dn6dvcGNcdk%2Fuploads%2FkKAgLD4sivAmCGpKZOy4%2FScreenshot%202024-06-12%20at%203.50.12%20PM.png?alt=media&amp;token=689de25d-407f-44d6-8ecc-dc13761741c2" alt=""><figcaption><p>When the user selects the "Savory" food type, the options for favorite food are only savory foods.</p></figcaption></figure>
* Tenant B: food type options will be **Fruits** and **Veggies**.

  <div align="center" data-full-width="false"><figure><img src="https://4017407078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfJn-9R_dn6dvcGNcdk%2Fuploads%2FCO0FgKt3Xd0Vluzeu9vx%2FScreenshot%202024-06-12%20at%204.03.02%20PM.png?alt=media&amp;token=f97e8386-72b6-4569-9a1d-e9e916bb36de" alt=""><figcaption><p>The only food type option for Tenant B are "Fruits" and "Veggies"</p></figcaption></figure></div>
* If the user chooses food type **Fruits** then the favorite food options will be: **Strawberry**, **Banana**, **Kiwi**

  <figure><img src="https://4017407078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfJn-9R_dn6dvcGNcdk%2Fuploads%2FfAsDjh4nKbGDvMnlB6fk%2FScreenshot%202024-06-12%20at%204.03.20%20PM.png?alt=media&amp;token=821ff93a-b070-4355-b099-116cac3d9b8f" alt=""><figcaption><p>When the user selects the "Fruits" food type, the options for favorite food are only fruits.</p></figcaption></figure>
* If the user chooses food type **Veggies** then the favorite food options will be: **Carrot**, **Broccoli**, **Pepper**

  <figure><img src="https://4017407078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfJn-9R_dn6dvcGNcdk%2Fuploads%2FKA5oqCEDGnziGYdXRRXt%2FScreenshot%202024-06-12%20at%204.03.11%20PM.png?alt=media&amp;token=47bc9f05-8bfa-4eb0-a597-65f022a0bb6c" alt=""><figcaption><p>When the user selects the "Veggies" food type, the options for favorite food are only vegetables.</p></figcaption></figure>

The option lists come from [tenant metadata](/getting-started/anatomy-of-an-integration/pandium.yaml-spec/tenant-metadata.md), written from a run's stdout.

{% hint style="warning" %}
Manifest versions below 1.0 read them from `definitions` entries filled from the saved stdout of the tenant's last init sync instead. Those versions are deprecated. See [Migrating to Manifest Version 1.0](/getting-started/anatomy-of-an-integration/pandium.yaml-spec/migrating-to-manifest-version-1.0.md) to move an existing integration over.
{% endhint %}

## Building a Dependent Selector

A dependent selector is made of two config properties and two metadata properties:

* The **parent selector** is an ordinary [dynamic config](/getting-started/anatomy-of-an-integration/pandium.yaml-spec/dynamic-configurations.md): a property that references its options with `$ref: '#/metadata/<key>'`. It can also be static, with its options listed inline or in a `definitions` entry.
* The **dependent selector** is a `string` property with two extra props:
  * `optionsMapPath`, pointing at the metadata key that holds the parent-to-children map: `'#/metadata/<key>'`.
  * `parentField`, pointing at the parent config property: `'#/properties/<parent>'`. This still references a config property, not a metadata key.

Both metadata keys must be declared in `metadata_schema.schema.properties`, since stdout is validated against that schema and undeclared keys are rejected. The parent's key is an array; the map is an object.

### Putting it All Together

Taking the food example above, where the user picks a food type and then a food of that type:

```yaml
configs:
  schema:
    type: object
    properties:
      food_type:
        $ref: '#/metadata/food_types'
      favorite_food:
        type: string
        optionsMapPath: '#/metadata/food_options'
        parentField: '#/properties/food_type'

  uischema:
    type: VerticalLayout
    elements:
      # Parent
      - label: Food Type
        scope: '#/properties/food_type'
        type: Control
      # Dependent
      - label: Favorite Food
        scope: '#/properties/favorite_food'
        type: Control

metadata_schema:
  schema:
    type: object
    properties:
      food_types:
        type: array
        items:
          type: object
      food_options:
        type: object
```

The run that populates them prints both keys in one JSON object:

```javascript
if (pandium.context.runMode === 'init') {
    const foods = await foodClient.getMany('food');

    // Each food type becomes an option for the parent selector.
    const foodTypes = [
      { const: 1, title: 'Sweet' },
      { const: 2, title: 'Savory' },
    ];

    // Each parent option's const maps to the list of options for that type.
    const foodOptions = {
      1: ['Chocolate', 'Caramel', 'Jello'],
      2: ['Chips', 'Pizza', 'Bread'],
    };

    const stdout = {
      food_types: foodTypes,
      food_options: foodOptions,
    };
    console.log(JSON.stringify(stdout));
    return
}
```

The rules for the values:

* The parent's options are an array of `{const, title}` objects, or an array of strings.
* The map's keys are the parent options' `const` values, and each value is that parent's list of options.
* Every list in the map must be entirely strings or entirely `{const, title}` objects, not a mix.

Until a run has written metadata for a referenced key, the field renders in an unsynced state with its options disabled. Dependent selectors also work inside arrays, under the same parent lookup rules described in [Dependent Selectors in Arrays](#dependent-selectors-in-arrays) below.

## Dependent Selectors in Arrays

Dependent selectors can be used in arrays. The selector will look first for its parent in its own object, and if it doesn't find it there it will look up the next level in the schema. Consider the following setup:

```yaml
configs:
  schema:
    type: object
    definitions:
      pokemon_types:
        enum:
          - Fire
          - Water
          - Rock
          - Flying
    properties:
      food_type:
        enum:
          - fruit
          - Vegetable
      pokemon_list:
        type: array
        items:
          type: object
          properties:
            p_type:
              $ref: '#/definitions/pokemon_types'
              type: string
              title: Pokemon Type
            pokemon_name:
              type: string
              title: Pokemon
              parentField: '#/properties/p_type'
              optionsMapPath: '#/metadata/pokemon_options'
            food_for_pokemon:
              type: string
              title: Food
              parentField: '#/properties/food_type'
              optionsMapPath: '#/metadata/food_options'
  uischema:
    type: Section
    label: Fun with Dependent Configs
    subtitle: This is a test of dependent configs
    elements:
      - type: Control
        label: Food Type
        scope: '#/properties/food_type'
      - type: Control
        label: Pokemon List
        scope: '#/properties/pokemon_list'

metadata_schema:
  schema:
    type: object
    properties:
      food_options:
        type: object
      pokemon_options:
        type: object
```

With `food_options` and `pokemon_options` in metadata, this renders the following form:

<figure><img src="https://4017407078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfJn-9R_dn6dvcGNcdk%2Fuploads%2F4w9SIzyE2Nrbz80AJbKe%2FScreenshot%202025-07-02%20at%2010.48.08%E2%80%AFAM.png?alt=media&amp;token=9de12d15-b87f-416d-8021-198223a63ad1" alt=""><figcaption></figcaption></figure>

Note that the second column in the table depends on the first, but the third column depends on the "food type" selector above.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.pandium.com/getting-started/anatomy-of-an-integration/pandium.yaml-spec/dependent-selector-configurations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.