> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alumio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Configuration Object

> Step by step: pick a top-level type, choose a prototype, fill in its parameters, and nest or reference other configurations.

The `object` field is the heart of every line in an import file. It holds the actual configuration and
is where most of the work goes. This page walks through building it from scratch.

## Object structure

The `object` takes one of two shapes, depending on whether the type uses named prototypes or a single default prototype:

```json theme={null}
{
  "prototype": "http-subscriber",
  "parameters": {
    "uri": "https://api.example.org"
  }
}
```

```json theme={null}
{
  "parameters": {
    "uri": "https://api.example.org"
  }
}
```

The first form names a prototype explicitly. The second is for types with a single default prototype, so no `prototype` key is needed.

## Step by step

<Steps>
  <Step title="Pick a top-level type">
    The `type` at the top level of the line decides what you are building. Only the types below are allowed at the top level of an import line.

    **The main types you start from:**

    | Type                     | What it is                                                     |
    | ------------------------ | -------------------------------------------------------------- |
    | `route-configuration`    | Connects one incoming to one outgoing and applies transformers |
    | `incoming-configuration` | Pulls data in and creates tasks                                |
    | `outgoing-configuration` | Pushes data out to a destination                               |
    | `scheduler-entry`        | Runs an incoming or a route's outgoing on a cron schedule      |
    | `list-transformer`       | A reusable, named data-processing pipeline                     |

    **Connection types**, referenced by the ones above:

    | Type                  | What it is                               |
    | --------------------- | ---------------------------------------- |
    | `http-client`         | A reusable HTTP connection               |
    | `http-authentication` | Reusable authentication for HTTP clients |
    | `soap-client`         | A SOAP connection                        |
    | `database-connection` | A database connection                    |
    | `email-server`        | An email server (SMTP or SendGrid)       |
    | `filesystem`          | Remote or local file storage             |

    **Helper types:**

    | Type      | What it is                                                      |
    | --------- | --------------------------------------------------------------- |
    | `entity`  | Defines how items are identified, for deduplication and display |
    | `storage` | An internal key-value store                                     |
  </Step>

  <Step title="Find the prototypes for that type">
    Each type offers a set of **prototypes** or a **default prototype**: templates with a
    JSON schema that lists the fields you fill in. Fetch the supported prototypes for a
    type from the Alumio API:

    ```http theme={null}
    GET /api/v1/di/list/{type}/prototypes
    ```

    See [Finding configuration types and schemas](#finding-configuration-types-and-schemas)
    below for more information.
  </Step>

  <Step title="Set the prototype and its parameters">
    Put the chosen prototype identifier in `prototype`, and fill the fields from its schema into `parameters`:

    ```json theme={null}
    {
      "prototype": "pattern-move",
      "parameters": {
        "pattern": "sku",
        "replacement": "product_code"
      }
    }
    ```

    For a type that uses its default prototype, omit the `prototype` key and provide only `parameters`.
  </Step>

  <Step title="Reference or inline a nested configuration">
    Some fields hold another prototype or configuration rather than a plain value. The field's schema
    tells you which through its `di:type` and `di:allow` properties
    (see [Common schema properties](#common-schema-properties) below). When a reference is allowed,
    you have two options.

    **Inline** as its own prototype and parameters:

    ```json theme={null}
    {
      "serializer": {
        "prototype": "json",
        "parameters": {
          "flags": [128]
        }
      }
    }
    ```

    Or **reference** a configuration that is already saved in the environment
    (or defined on another line in the same file), by its identifier:

    ```json theme={null}
    {
      "client": {
        "identifier":"webshop-http-client"
      }
    }
    ```

    To see what already exists to reference, list the saved configurations of that type:

    ```http theme={null}
    GET /api/v1/di/list/{type}/configurations
    ```
  </Step>

  <Step title="Nest as deep as you need">
    Prototypes can hold other prototypes, so the structure nests. In the example below, a `list-transformer` (prototype `data`) contains an `http-transformer`, whose `client` is a **reference** to a saved `http-client` (`webshop`) and whose `request.serializer` is an **inline** `json` prototype:

    ```json theme={null}
    {
      "$schema": "https://di.schema.alumio.com/register.configuration.json",
      "type": "list-transformer",
      "identifier": "transformer-example",
      "name": "Transformer Example",
      "description": "",
      "object": {
        "prototype": "data",
        "parameters": {
          "transformers": [
            {
              "prototype": "http-transformer",
              "parameters": {
                "client": {
                  "identifier": "webshop"
                },
                "request": {
                  "uri": "/api/v1/orders",
                  "method": "GET",
                  "payload": "&{@}",
                  "serializer": {
                    "prototype": "json",
                    "parameters": { "flags": [128] }
                  },
                  "payloadType": "data"
                }
              }
            }
          ]
        }
      }
    }
    ```
  </Step>
</Steps>

## ULIDs

Alumio stamps a `ulid` on every prototype object during import validation. Do not generate them yourself.

* **When creating**: omit `ulid` everywhere. The server injects them.
* **When updating**: start from the exported or fetched JSON and keep the `ulid` fields it already contains, so embedded objects keep their identity.

## Finding configuration types and schemas

Use the Alumio API to find prototypes and configurations.

### Search for prototypes of a type

To list all available prototypes for a type use the following API call.

```http theme={null}
GET /api/v1/di/list/{type}/prototypes
```

### List saved configurations

To see what is already configured in the environment (so you reuse instead of duplicate), list the saved configurations of a type.

```http theme={null}
GET /api/v1/di/list/{type}/configurations
```

## Common schema properties

When you read a prototype's schema, a handful of properties tell you how to fill in a field. They live under a field's `ui` object.

### di:type

Marks a field that holds a **nested configuration** of a given type, rather than a plain value. For example, a field with `di:type: subscriber` expects a subscriber prototype (inline) or a reference to a saved subscriber. The value is either an inline prototype object or a reference object, as shown in the steps above.

### di:allow and di:force

These say whether a `di:type` field may point at a **saved configuration**.

* `di:allow: configuration` means a reference to a saved configuration is allowed. Use a reference object `{ "identifier": "..." }`, or inline the prototype if you prefer. The route's `incoming` and `outgoing` fields work this way.
* `di:force: configuration` means the value must be its own saved configuration, referenced by identifier. Every `transformers` array uses this: create a standalone `list-transformer` line and reference it. Inline objects are accepted by the importer but render poorly in the dashboard.

### ui:supportsPlaceholders

Marks a field that accepts a **placeholder**. For example `&{id}`. See [Placeholders](/documentation/placeholders-and-patterns/placeholders).

### ui:patterns

Marks a field that uses **path patterns** to select or write data. For example `products.*.sku`. See [Patterns](/documentation/placeholders-and-patterns/patterns).