> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/setup-and-monitor/extend-the-platform/build-a-custom-feed-plugin/layouts-for-feeds.md).

# Layouts for feeds

Shape the form your users fill in when they add your feed to a segment.

## Your goal

Give your users a clear form when they add your feed to a segment: properties grouped into sections, each shown with the right type of field, and labelled in their language.

## Expected outcome

A plugin version carrying a layout JSON file and its translation files, so the feed form shows your sections, fields and labels instead of a plain list of properties.

## What a layout is made of

A [layout](https://docs.mediarithmics.io/setup-and-monitor/extend-the-platform/plugin-architecture.md#layouts) is bound to a plugin version. It is optional for other plugin types, which then show every property in a default layout, but **mandatory for audience segment feeds**.

It is made of:

1. A layout JSON file.
2. A non-empty list of translation CSV files.

## The layout JSON file

The layout JSON file declares the elements of the form: the layout version, the [sections](#sections) to display, and the [metadata](#metadata).

```json
{
  "version": "V202005",
  "sections": [
    {
      "title": "{{section_title}}",
      "sub_title": "{{section_subtitle}}",
      "fields": [
        {
          "property_technical_name": "property_1",
          "field_type": "INPUT",
          "label": "{{property_1_label}}",
          "tooltip": "{{property_1_tooltip}}",
          "placeholder": "{{property_1_placeholder}}",
          "required": true
        },
        {
          "property_technical_name": "property_2",
          "field_type": "DYNAMIC_SELECT",
          "label": "{{property_2_label}}",
          "tooltip": "{{property_2_tooltip}}",
          "placeholder": "{{property_2_placeholder}}",
          "enum": null,
          "required": true
        },
        {
          "property_technical_name": "property_3",
          "field_type": "MULTI_SELECT",
          "label": "{{property_3_label}}",
          "tooltip": "{{property_3_tooltip}}",
          "placeholder": "{{property_3_placeholder}}",
          "enum": [
            {
              "value": "category_1",
              "label": "{{CAT_1_label}}"
            },
            {
              "value": "category_2",
              "label": "{{CAT_2_label}}"
            },
            {
              "value": "category_3",
              "label": "{{CAT_3_label}}"
            }
          ],
          "required": true
        }
      ],
      "advanced_fields": [
        {
          "property_technical_name": "segment_name",
          "field_type": "INPUT",
          "label": "{{segment_name_label}}",
          "tooltip": "{{segment_name_tooltip}}",
          "placeholder": "{{segment_name_placeholder}}",
          "required": false
        },
        {
          "property_technical_name": "segment_description",
          "field_type": "INPUT",
          "label": "{{segment_description_label}}",
          "tooltip": "{{segment_description_tooltip}}",
          "required": false
        },
        {
          "property_technical_name": "customer_user_identifier",
          "field_type": "INPUT",
          "label": "{{customer_user_identifier_label}}",
          "tooltip": "{{customer_user_identifier_tooltip}}",
          "required": false
        },
        {
          "property_technical_name": "continent",
          "field_type": "SELECT",
          "label": "{{continent_label}}",
          "tooltip": "{{continent_tooltip}}",
          "enum": [
            {
              "value": "NAM",
              "label": "NAM"
            },
            {
              "value": "EMEA",
              "label": "EMEA"
            },
            {
              "value": "APAC",
              "label": "APAC"
            }
          ],
          "required": false
        }
      ]
    }
  ],
  "metadata": {
    "large_icon_asset_id": "13636",
    "small_icon_asset_id": "13636",
    "display_name": "{{section_title}}",
    "description": "{{section_subtitle}}"
  }
}
```

### Root

| Attribute        | Type                                                  | Description                                                                         |
| ---------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `version`        | String                                                | The version of the layout.                                                          |
| `sections`       | A list of [sections](#sections)                       | The sections of the form.                                                           |
| `metadata`       | A [metadata](#metadata) object                        | Metadata about the form.                                                            |
| `authentication` | An [authentication](#authentication) object, optional | The wording of the form a user fills in to authenticate a destination on your feed. |

### Sections

A form can display several sections, each made of fields and of an advanced fields part.

| Attribute         | Type                        | Description                                                                   |
| ----------------- | --------------------------- | ----------------------------------------------------------------------------- |
| `title`           | String                      | The section title.                                                            |
| `sub_title`       | String                      | The section subtitle.                                                         |
| `fields`          | A list of [fields](#fields) | The fields of the section.                                                    |
| `advanced_fields` | A list of [fields](#fields) | The advanced fields of the section, which can be expanded or not in the form. |

### Fields

| Attribute                 | Type                                      | Description                                                                                                                                                                                           |
| ------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `property_technical_name` | String                                    | The technical name of the property the field represents.                                                                                                                                              |
| `field_type`              | A [field type](#field-types)              | The type of form field.                                                                                                                                                                               |
| `label`                   | String                                    | The label shown on the left of the field in the form.                                                                                                                                                 |
| `placeholder`             | String                                    | The text shown in an empty field, hinting at the expected format or an example value. Displayed only for `TEXTAREA` and every `*SELECT` type. Without one, the technical name is shown in PascalCase. |
| `tooltip`                 | String, optional                          | The help text shown in the tooltip on the right of the field.                                                                                                                                         |
| `enum`                    | A list of [enum](#enum) objects, optional | The possible values of the field, used by `SELECT`, `MULTI_SELECT`, `SWITCH`, `RADIO` and `CHECKBOX`.                                                                                                 |
| `max_length`              | Integer, optional                         | The maximum length of the text, used only by `TEXTAREA`.                                                                                                                                              |
| `required`                | Boolean, optional                         | Whether the field is mandatory. Defaults to `false`.                                                                                                                                                  |

### Field types

* `TEXTAREA`
* `URL`
* `DATA_FILE`
* `HTML`
* `NUMBER`
* `SELECT`
* `MULTI_SELECT`
* `DYNAMIC_SELECT` - requires the [`onDynamicPropertyValuesQuery`](https://docs.mediarithmics.io/setup-and-monitor/extend-the-platform/build-a-custom-feed-plugin.md#the-methods-to-implement) method in the plugin code.
* `IMAGE`
* `INPUT`
* `INPUT_NUMBER`
* `SWITCH`
* `RADIO`
* `CHECKBOX`
* `DATE`
* `DATE_RANGE`

### Enum

| Attribute | Type   | Description                       |
| --------- | ------ | --------------------------------- |
| `value`   | String | The value given to the property.  |
| `label`   | String | The label displayed in the field. |

### Metadata

| Attribute             | Type     | Description                                                                              |
| --------------------- | -------- | ---------------------------------------------------------------------------------------- |
| `large_icon_asset_id` | Asset ID | The asset of the large icon representing the plugin layout.                              |
| `small_icon_asset_id` | Asset ID | The asset of the small icon representing the plugin layout.                              |
| `display_name`        | String   | The plugin version's name, visible in the plugin listing and on the form page.           |
| `description`         | String   | A description of the plugin version, visible in the plugin listing and on the form page. |

The icon assets must belong to the same organisation as the plugin.

### Authentication

The `authentication` object sets the wording of the form a user fills in to authenticate a [destination](https://docs.mediarithmics.io/audience-and-activation/activate-your-audiences/set-up-a-connection-to-a-partner-platform/connect-your-partner-account.md#your-goal) on your feed. Which fields the form shows is decided by the plugin version's [authentication type](https://docs.mediarithmics.io/setup-and-monitor/extend-the-platform/build-a-custom-feed-plugin/authentication-for-feeds.md#choose-the-authentication-type), not by the layout: the layout only sets their labels, their help texts and the OAuth 2.0 button. Every attribute is optional, and an attribute left out keeps its default wording.

| Attribute              | Type                                                               | Authentication type | Description                                                                                                                                                            |
| ---------------------- | ------------------------------------------------------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `button_label`         | String, optional                                                   | `OAUTH2`            | The label of the button that starts the OAuth 2.0 flow. Defaults to **Connect**.                                                                                       |
| `button_icon_asset_id` | Asset ID, optional                                                 | `OAUTH2`            | The asset of the icon shown on the button.                                                                                                                             |
| `oauth2`               | An object with `button_label` and `button_icon_asset_id`, optional | `OAUTH2`            | The same attributes, grouped under the authentication type they apply to. When set, they take precedence over the top-level `button_label` and `button_icon_asset_id`. |
| `token`                | An [authentication field](#authentication-fields), optional        | `API_TOKEN`         | The token field. Its label defaults to **Token**.                                                                                                                      |
| `login`                | An [authentication field](#authentication-fields), optional        | `LOGIN_PASSWORD`    | The login field. Its label defaults to **Login / Email**.                                                                                                              |
| `password`             | An [authentication field](#authentication-fields), optional        | `LOGIN_PASSWORD`    | The password field. Its label defaults to **Password**.                                                                                                                |

You only set the asset IDs: the platform fills in the matching `button_icon_asset_url` attributes when it serves the layout.

```json
{
  "authentication": {
    "oauth2": {
      "button_label": "Connect with Partner",
      "button_icon_asset_id": "13636"
    },
    "token": {
      "label": "{{auth_token_label}}",
      "tooltip": "{{auth_token_tooltip}}"
    },
    "login": { "label": "Login", "tooltip": "The email of your partner account." },
    "password": { "label": "Password" }
  }
}
```

Labels and help texts accept [translation](#translation-files) references, like any other value of the layout.

### Authentication fields

| Attribute | Type             | Description                         |
| --------- | ---------------- | ----------------------------------- |
| `label`   | String, optional | The label of the field.             |
| `tooltip` | String, optional | The help text shown with the field. |

### The JSON schema

<details>

<summary>The JSON schema of a layout file, to validate your files in any JSON schema validator</summary>

```json
{
  "$schema": "http://json-schema.org/schema#",
  "definitions": {
    "PluginLayoutMetadataResource": {
      "type": "object",
      "properties": {
        "large_icon_asset_id": {"type": "string"},
        "small_icon_asset_id": {"type": "string"},
        "large_icon_asset_url": {"type": ["string", "null"]},
        "small_icon_asset_url": {"type": ["string", "null"]},
        "tooltip": {"type": ["string", "null"]},
        "display_name": {"type": "string"},
        "description": {"type": "string"}
      },
      "required": ["large_icon_asset_id", "small_icon_asset_id", "display_name", "description"]
    },
    "PluginLayoutEnumResource": {
      "type": "object",
      "properties": {
        "value": {"type": "string"},
        "label": {"type": "string"}
      },
      "required": ["value", "label"]
    },
    "PluginLayoutFieldResource": {
      "type": "object",
      "properties": {
        "property_technical_name": {"type": "string"},
        "field_type": {"type": "string"},
        "label": {"type": "string"},
        "tooltip": {"type": ["string", "null"]},
        "enum": {"type": ["array", "null"],
          "items": {
            "$ref": "#/definitions/PluginLayoutEnumResource"
          }
        },
        "max_length": {"type": ["integer", "null"]},
        "required": {"type": ["boolean", "null"]}
      },
      "required": ["property_technical_name", "field_type", "label"]
    },
    "PluginLayoutSectionResource": {
      "type": "object",
      "properties": {
        "title": {"type": "string"},
        "sub_title": {"type": "string"},
        "fields": {"type": "array",
          "items": {
            "$ref": "#/definitions/PluginLayoutFieldResource"
          }
        },
        "advanced_fields": {"type": "array",
          "items": {
            "$ref": "#/definitions/PluginLayoutFieldResource"
          }
        }
      },
      "required": ["title", "sub_title", "fields", "advanced_fields"]
    },
    "PluginLayoutAuthInputResource": {
      "type": "object",
      "properties": {
        "label": {"type": ["string", "null"]},
        "tooltip": {"type": ["string", "null"]}
      }
    },
    "PluginLayoutAuthOAuth2Resource": {
      "type": "object",
      "properties": {
        "button_label": {"type": ["string", "null"]},
        "button_icon_asset_id": {"type": ["string", "null"]},
        "button_icon_asset_url": {"type": ["string", "null"]}
      }
    },
    "PluginLayoutAuthenticationResource": {
      "type": "object",
      "properties": {
        "button_label": {"type": ["string", "null"]},
        "button_icon_asset_id": {"type": ["string", "null"]},
        "button_icon_asset_url": {"type": ["string", "null"]},
        "oauth2": {"$ref": "#/definitions/PluginLayoutAuthOAuth2Resource"},
        "token": {"$ref": "#/definitions/PluginLayoutAuthInputResource"},
        "login": {"$ref": "#/definitions/PluginLayoutAuthInputResource"},
        "password": {"$ref": "#/definitions/PluginLayoutAuthInputResource"}
      }
    }
  },
  "type": "object",
  "properties": {
    "version": {"type": "string"},
    "sections": {"type": "array",
      "items": {
        "$ref": "#/definitions/PluginLayoutSectionResource"
      }
    },
    "metadata": {"$ref": "#/definitions/PluginLayoutMetadataResource"},
    "authentication": {"$ref": "#/definitions/PluginLayoutAuthenticationResource"}
  },
  "required": ["version", "sections", "metadata"]
}
```

</details>

## Translation files

Translation files localise the form: for a given layout JSON file, you provide one translation CSV file per locale.

In the layout JSON file, refer to a value by surrounding its name with double curly brackets: the value `val` is written `{{val}}`. These references can appear anywhere in the layout JSON file, for instance in a field label:

```json
{
  "property_technical_name": "name",
  "field_type": "TEXTAREA",
  "label": "{{val}}"
}
```

A translation CSV file has two comma-separated columns, under the header `KEY,VALUE`. The first column holds the keys, the names of the values (`val` above). The second holds what replaces each key when the form is displayed. The matching US English (`en-US`) file for the excerpt above:

```
KEY,VALUE
val,"Hello World!"
```

## Manage layouts

{% tabs %}
{% tab title="In the interface" %}

1. In Computing Console, choose your plugin, select a plugin version, and open **Layout** in the menu.
2. You should see at least two files: the properties layout and the `en-US` translation. Open a file's options and select **Edit** to display and change its content.
3. If these files are missing, create them with **Add a properties layout**, and **Add a local** for a translation.
   {% endtab %}

{% tab title="By API" %}
Get the layout JSON file of a plugin version, with its translation tokens, or with the values of a locale when you add the `locale` query parameter, for example `locale=en-US`:

```
GET https://api.mediarithmics.com/v1/plugins/:pluginId/versions/:versionId/properties_layout
```

Upload the layout JSON file, sent as the request body:

```
PUT https://api.mediarithmics.com/v1/plugins/:pluginId/versions/:versionId/properties_layout
```

Get or upload the translation file of a locale:

```
GET https://api.mediarithmics.com/v1/plugins/:pluginId/versions/:versionId/properties_layout/localizations/locale=:locale
PUT https://api.mediarithmics.com/v1/plugins/:pluginId/versions/:versionId/properties_layout/localizations/locale=:locale
```

If an upload fails with `JSON not structured as expected`, validate your file against [the JSON schema](#the-json-schema).
{% endtab %}
{% endtabs %}

## Verify

* The layout JSON file validates against the JSON schema, and its upload is accepted.
* A translation file exists for every locale you support, and every `{{key}}` in the layout has a line in it.
* The feed form shows your sections, fields and labels when a user adds the feed to a segment.

## Related pages

<table data-view="cards" data-search="false"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Build a custom feed plugin</strong></td><td>Creating and deploying the feed.</td><td><a href="https://docs.mediarithmics.io/setup-and-monitor/extend-the-platform/build-a-custom-feed-plugin.md">Build a custom feed plugin</a></td></tr><tr><td><strong>Authentication for feeds</strong></td><td>The authentication part of the layout.</td><td><a href="https://docs.mediarithmics.io/setup-and-monitor/extend-the-platform/build-a-custom-feed-plugin/authentication-for-feeds.md">Authentication for feeds</a></td></tr><tr><td><strong>Plugin architecture</strong></td><td>Versions, properties and layouts.</td><td><a href="https://docs.mediarithmics.io/setup-and-monitor/extend-the-platform/plugin-architecture.md">Plugin architecture</a></td></tr></tbody></table>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mediarithmics.io/setup-and-monitor/extend-the-platform/build-a-custom-feed-plugin/layouts-for-feeds.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
