> For the complete documentation index, see [llms.txt](https://docs.layerlens.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.layerlens.ai/13.1-sdk-and-apis/trace-schema.md).

# Trace JSON Schema

Stratix Trace JSON Schema — formal specification of the trace payload.

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)