# Trace JSON Schema

The trace payload Stratix accepts on `POST /api/v1/traces` (and via the SDK and CLI) is formally specified by a JSON Schema document.

## Download

[`assets/schemas/trace.schema.json`](https://github.com/LayerLens/gitbook-full/blob/main/assets/schemas/trace.schema.json) — JSON Schema draft 2020-12.

## Required fields

| Field  | Type   | Notes                                |
| ------ | ------ | ------------------------------------ |
| `id`   | string | Stable identifier (UUID recommended) |
| `name` | string | Human-readable name                  |

Everything else (`inputs`, `outputs`, `spans`, `tags`, `started_at`, `duration_ms`, etc.) is optional but strongly recommended.

## Span kinds

`llm`, `tool`, `retrieval`, `chain`, `other`. Spans are recursive — a `chain` span can contain other spans.

## Validating client-side

Any JSON Schema validator works. Examples:

Download `trace.schema.json` (linked above) and load it locally:

**Python (jsonschema):**

```python
import json, jsonschema

with open("trace.schema.json") as f:
    schema = json.load(f)
jsonschema.validate(instance=my_trace, schema=schema)
```

**Node (ajv):**

```javascript
import Ajv from "ajv";
import schema from "./trace.schema.json" assert { type: "json" };
const ajv = new Ajv();
const validate = ajv.compile(schema);
if (!validate(myTrace)) console.error(validate.errors);
```

## Versioning

Breaking schema changes ship as a new version of `trace.schema.json` in the documentation. Stratix accepts traces validating against any current-or-prior schema version for one major release.

## See also

* [Concept: Traces and spans](/6.-build-wire-your-code/traces-and-spans.md)
* [Premium UI: Traces](https://github.com/LayerLens/gitbook-full/blob/main/13-reference/api/traces.md)
* [SDK: traces](https://github.com/LayerLens/gitbook-full/blob/main/13-reference/sdk-python/traces.md)
* [REST: traces](https://github.com/LayerLens/gitbook-full/blob/main/13-reference/api/traces.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.layerlens.ai/13.1-sdk-and-apis/trace-schema.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.