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

# Schema Reference

> Complete reference for enrichment namespaces, data types, and backend attributes

This page documents the enrichment schema - available namespaces, supported data types, and how they map to backend attributes.

For how to use enrichment functions, see [Enriching Traces](/v2/tracing/enrich-traces).

***

## Available Namespaces

Enrichments are key-value pairs that add context to your traces. Both `enrich_span()` and `enrich_session()` support these namespaces:

| Namespace         | Type   | Description                                            | `enrich_session` | `enrich_span` |
| ----------------- | ------ | ------------------------------------------------------ | :--------------: | :-----------: |
| `config`          | Object | Configuration details (model params, prompt templates) |         ✓        |       ✓       |
| `feedback`        | Object | User feedback or annotations                           |         ✓        |       ✓       |
| `metrics`         | Object | Scores, evaluations, numeric measurements              |         ✓        |       ✓       |
| `metadata`        | Object | Catch-all for arbitrary metadata or JSON               |         ✓        |       ✓       |
| `inputs`          | Object | Input data for the function or event                   |         ✓        |       ✓       |
| `outputs`         | Object | Output data from the function or event                 |         ✓        |       ✓       |
| `user_properties` | Object | User-specific attributes                               |         ✓        |       ✓       |
| `error`           | String | Error information if applicable                        |         ✗        |       ✓       |
| `event_id`        | String | Custom event ID (must be valid UUIDv4)                 |         ✗        |       ✓       |

<Note>
  **Setting event type:** To set the event type (chain, model, tool), use the `@trace` decorator's `event_type` parameter, not enrichment functions. Example: `@trace(event_type="model")`.
</Note>

***

## Backend Attributes

Each namespace maps to a specific backend attribute prefix:

| Namespace         | Purpose                    | Backend Attribute             |
| ----------------- | -------------------------- | ----------------------------- |
| `metadata`        | Custom business context    | `honeyhive_metadata.*`        |
| `metrics`         | Numeric measurements       | `honeyhive_metrics.*`         |
| `user_properties` | User-specific properties   | `honeyhive_user_properties.*` |
| `feedback`        | User or system feedback    | `honeyhive_feedback.*`        |
| `inputs`          | Input data                 | `honeyhive_inputs.*`          |
| `outputs`         | Output data                | `honeyhive_outputs.*`         |
| `config`          | Configuration parameters   | `honeyhive_config.*`          |
| `error`           | Error messages (string)    | `honeyhive_error`             |
| `event_id`        | Unique identifier (string) | `honeyhive_event_id`          |

<Note>
  **Additive behavior:** For Object-type enrichments (config, metadata, etc.), enrichments are *additive* for unique keys. Enriching the same field twice with different keys includes both. Enriching the same key twice overwrites the previous value.
</Note>

***

## Parameter Precedence

When using `enrich_span()` with mixed invocation patterns (dict, kwargs, namespaces), parameters are merged in this order:

1. **Reserved namespaces** (`metadata`, `metrics`, etc.) - Applied first
2. **`attributes` dict** (simple dict passed as first argument) - Applied second
3. **`**kwargs`** (keyword arguments) - Applied last, wins conflicts

```python theme={null}
# Example: mixing patterns
enrich_span(
    {"key": "from_dict"},        # attributes dict
    metadata={"key": "from_ns"}, # reserved namespace
    key="from_kwargs"            # kwargs
)
# Result: key="from_kwargs" (kwargs win)
```

<Note>
  Kwargs override dict values when the same key appears in both. Use explicit namespaces (`metadata=`, `metrics=`) for clarity.
</Note>

***

## Supported Data Types

You can enrich with these data types:

```python theme={null}
from honeyhive import enrich_span

enrich_span({
    # Strings
    "user_id": "user_12345",
    "feature": "chat",
    
    # Numbers (integers and floats)
    "priority_score": 8.5,
    "retry_count": 3,
    
    # Booleans
    "is_premium_user": True,
    "cache_hit": False,
    
    # Lists (serialized to JSON)
    "tags": ["support", "billing", "urgent"],
    "model_fallback_order": ["gpt-4", "gpt-4o-mini"],
    
    # Nested dicts (serialized to JSON)
    "user_metadata": {
        "tier": "pro",
        "region": "us-east"
    }
})
```

<Note>
  Complex objects (lists, nested dicts) are automatically serialized to JSON strings for storage.
</Note>

***

## Nesting Limits

For complex data types:

* **Objects:** Maximum 5 levels of nesting
* **Arrays:** Maximum 2 levels of nesting

When querying nested data in the dashboard, use dot notation:

```json theme={null}
{
  "step_evals": [
    { "invalid_grammar": true, "user_intervened": true },
    { "invalid_grammar": false }
  ],
  "trajectory_eval": {
    "overall": 5,
    "clarified_user_intent": "yes"
  }
}
```

You can chart:

* `metrics.step_evals.0.user_intervened` (boolean)
* `metrics.trajectory_eval.overall` (number)

***

## Best Practices

**DO:**

* Use consistent key names across your application
* Add user/session IDs for debugging
* Include feature/endpoint identifiers
* Use descriptive key names (`user_id` not `uid`)
* Keep values under 1KB per field

**DON'T:**

* Include sensitive data (passwords, API keys, PII)
* Use random or generated key names
* Duplicate data already captured by auto-instrumentors
* Exceed nesting limits (5 objects, 2 arrays)

***

## Task-Specific Guides

Each namespace has a dedicated guide with detailed examples:

<CardGroup cols={2}>
  <Card title="Metrics & Evaluations" icon="chart-line" href="/v2/tracing/client-side-evals">
    The `metrics` namespace for scores and evaluations
  </Card>

  <Card title="User Feedback" icon="comment" href="/v2/tracing/setting-user-feedback">
    The `feedback` namespace for ratings and comments
  </Card>

  <Card title="Prompts" icon="gear" href="/v2/prompts/overview">
    Manage prompt templates and model configs
  </Card>

  <Card title="User Properties" icon="user" href="/v2/tracing/setting-user-properties">
    The `user_properties` namespace for user context
  </Card>

  <Card title="Custom Metadata" icon="tags" href="/v2/tracing/enrich-traces">
    The `metadata` namespace for arbitrary data
  </Card>
</CardGroup>

***

## SDK Reference

* [Python SDK Reference](https://honeyhiveai.github.io/python-sdk/) - `enrich_session()`, `enrich_span()`