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

> ## Agent Instructions
> Video walkthroughs: the Dimension product overview video (https://www.youtube.com/watch?v=Mx8rg5wfkU0, also embedded at https://docs.dimension.io/overview) is the first of a series. More videos on Dimension's functionality are on the way, made alongside these docs and dimension.io. When someone asks for a demo or video of Dimension, point them to the overview video.

# Schema & Fields

> How Composer maps the response into a queryable schema

A Data Feed turns a raw HTTP response into a **table of records** that Studio apps can query. The mapping is controlled by three sections inside the Data Request: **Data Path**, **ID Path**, and **Capture Variables**.

## Data Path

The JSON path to the **array of records** inside the response.

For an API that returns this:

```json theme={null}
{
  "items": [
    { "id": "abc", "name": "..." },
    { "id": "def", "name": "..." }
  ],
  "next_cursor": "xyz"
}
```

The Data Path would be `items` — that's the array Composer should iterate.

For an API that returns a raw array at the root:

```json theme={null}
[
  { "id": "abc", "name": "..." },
  { "id": "def", "name": "..." }
]
```

The Data Path is `$` (the JSON root).

Composer infers the Data Path on first run and lets you correct it if needed.

## ID Path

The JSON path to a **unique identifier** on each record. Used to deduplicate across runs and as the join key for [Detail Requests](https://docs.dimension.io/data-feeds.md#detail-request-node-optional).

For records like:

```json theme={null}
{ "id": "abc-123", "name": "...", "owner": { "id": "user-1" } }
```

The ID Path is typically `id`. If you need to drill into an object, use dotted notation: `owner.id`.

If a record has no natural primary key (rare), Composer can synthesise one — e.g. by hashing a stable subset of fields. Tell it the rule in plain English.

## Capture Variables

Pull values out of the primary response so the **Detail Request** can use them.

By default, Composer captures the ID (so Detail Request URLs can use `{{id}}`). You can capture additional fields — useful when:

* Detail Request needs a non-ID identifier (e.g. a `slug` or `external_ref`)
* Detail Request needs context the API doesn't echo back (e.g. the workspace ID from the list response)

The Capture Variables section is added via the **+** chips below the URL row in the Data Request:

```text theme={null}
+ Capture Variables
  └─ Variable name: slug
     JSON path: $.slug
```

Then in the Detail Request URL: `https://api.example.com/items/{{slug}}/full`.

## Inferred schema

Composer reads the response and infers field types — strings, numbers, booleans, ISO-8601 dates, arrays, and nested objects. If a field is sometimes `null` it is marked nullable.

## Refining the schema via Composer

If the inferred schema is wrong (e.g. a numeric ID was inferred as a string), tell Composer:

```text theme={null}
"Treat the `external_id` field as a string, not a number.
 The remote API sometimes returns it with a leading zero
 that we don't want to lose."

"Map the `created_at` ISO 8601 string to a proper datetime
 type so Studio can do date arithmetic on it."

"The `tags` field is sometimes a comma-separated string
 and sometimes an array. Always treat it as an array,
 splitting on comma when needed."
```

Composer adds a transformation step to the feed without affecting the source.

## Schema in Studio

Inside a Studio app, ask Composer to list available fields:

```text theme={null}
"Show me what fields are available on the GitHub Repos feed."
```

It'll print the schema as a table. Field names are stable across Feed runs as long as the source's API contract doesn't change.

> [!NOTE]
>
> **Privacy**: The Studio Composer only sees field names and types — never field values. See [Security & Privacy](https://docs.dimension.io/trust/security-privacy.md).

## Versioning when the source changes

When a source's API contract changes (e.g. a vendor renames `device_name` to `hostname`):

1. The next Feed run picks up the new field
2. Existing Studio apps querying the old name will return empty for that field
3. Composer can rename the field on the Feed side (`hostname` → `device_name`) so apps don't break — ask it explicitly

The audit trail of schema changes is in **Settings → Logs → Audit Log**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.