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

# Overview

> Understanding the TurnWise data format

# Data Format Overview

TurnWise uses a hierarchical JSON format to represent AI agent conversations. This format captures the full context of conversations including messages, tool usage, and agent reasoning.

## Structure

```
Dataset (top level)
├── conversations[] (required)
│   ├── name (optional)
│   ├── description (optional)
│   ├── agents[] (optional)
│   │   ├── name
│   │   ├── description
│   │   └── tools{}
│   └── messages[] (required)
│       ├── role (required)
│       ├── content (optional)
│       └── steps[] (optional)
│           ├── model_name
│           ├── thinking
│           ├── tool_call
│           ├── tool_result
│           └── output_content
```

## Minimal Example

The simplest valid TurnWise file:

```json theme={null}
{
  "conversations": [
    {
      "messages": [
        {
          "role": "user",
          "content": "Hello"
        },
        {
          "role": "assistant",
          "content": "Hi there!"
        }
      ]
    }
  ]
}
```

**Note**: Message order (`sequence_number`) and step order (`step_order`) are automatically inferred from array positions.

## Required vs Optional Fields

### Required Fields

| Field           | Level        | Description                                   |
| --------------- | ------------ | --------------------------------------------- |
| `conversations` | Root         | Array of conversation objects                 |
| `messages`      | Conversation | Array of message objects                      |
| `role`          | Message      | One of: `user`, `assistant`, `system`, `tool` |

### Optional Fields

| Field            | Level        | Description          |
| ---------------- | ------------ | -------------------- |
| `name`           | Conversation | Human-readable name  |
| `description`    | Conversation | Description text     |
| `agents`         | Conversation | Agent definitions    |
| `content`        | Message      | Message text content |
| `steps`          | Message      | Processing steps     |
| `thinking`       | Step         | Model's reasoning    |
| `tool_call`      | Step         | Tool invocation      |
| `tool_result`    | Step         | Tool output          |
| `output_content` | Step         | Final output         |
| `meta`           | All levels   | Custom metadata      |

## The `meta` Field

Every level supports an optional `meta` field for storing custom data:

```json theme={null}
{
  "conversations": [
    {
      "name": "Support Chat",
      "meta": {
        "customer_id": "cust_123",
        "session_id": "sess_456",
        "channel": "web"
      },
      "messages": [...]
    }
  ]
}
```

This data is preserved but not used by TurnWise evaluations unless referenced in custom metrics.

## Next Steps

<CardGroup cols={2}>
  <Card title="Conversations" href="/data-format/conversations">
    Learn about conversation structure
  </Card>

  <Card title="Messages" href="/data-format/messages">
    Understand message roles and content
  </Card>

  <Card title="Steps" href="/data-format/steps">
    Capture reasoning and tool usage
  </Card>

  <Card title="Agents" href="/data-format/agents">
    Define agent capabilities
  </Card>
</CardGroup>