# Semantic Conventions

The semantic conventions define the keys and values that describe commonly observed concepts and operations in AI applications. They populate the attributes of spans and span events. This page lists every OpenInference attribute, grouped by namespace. All OpenInference tracing SDKs MUST support these attributes. The [span conventions](https://openinf.dev/spec/spans/llm.html.md) say which attributes a span of each kind carries, and [Attribute Conventions](https://openinf.dev/spec/attributes/conventions.html.md) explains how names, types, and lists are encoded.

Types marked “List of objects” are [flattened](https://openinf.dev/spec/attributes/conventions.html.md#flattening) with zero-based indices, e.g. `llm.input_messages.0.message.role`.

## OpenInference

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `openinference.span.kind` | String | Required for all OpenInference spans. Identifies the type of operation. See [Span Kinds](https://openinf.dev/spec/general/span-kinds.html.md). | `"LLM"`, `"EMBEDDING"`, `"CHAIN"`, `"RETRIEVER"`, `"RERANKER"`, `"TOOL"`, `"AGENT"`, `"GUARDRAIL"`, `"EVALUATOR"`, `"PROMPT"`, `"DECISION"` |

## Input and Output

Valid on spans of any kind.

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `input.value` | String | The input value to an operation | `"{'query': 'What is the weather today?'}"` |
| `input.mime_type` | String | MIME type representing the format of `input.value` | `"text/plain"`, `"application/json"` |
| `input.images` | List of objects | Image inputs to an operation, independent of span kind, e.g. `input.images.0.image.url`. See [Multimodal Content](https://openinf.dev/spec/content/multimodal.html.md#span-kind-independent-images) | `[{"image.url": "https://sample-link-to-image.jpg"}]` |
| `input.documents` | List of objects | File document (e.g. PDF) inputs to an operation, independent of span kind, e.g. `input.documents.0.document.url`. See [Multimodal Content](https://openinf.dev/spec/content/multimodal.html.md#span-kind-independent-documents) | `[{"document.url": "https://example.com/report.pdf", "document.mime_type": "application/pdf"}]` |
| `output.value` | String | The output value of an operation | `"Hello, World!"` |
| `output.mime_type` | String | MIME type representing the format of `output.value` | `"text/plain"`, `"application/json"` |
| `output.images` | List of objects | Image outputs of an operation, independent of span kind, e.g. `output.images.0.image.url`. See [Multimodal Content](https://openinf.dev/spec/content/multimodal.html.md#span-kind-independent-images) | `[{"image.url": "data:image/png;base64,iVBORw0KGgo..."}]` |
| `output.documents` | List of objects | File document (e.g. PDF) outputs of an operation, independent of span kind, e.g. `output.documents.0.document.url`. See [Multimodal Content](https://openinf.dev/spec/content/multimodal.html.md#span-kind-independent-documents) | `[{"document.url": "https://example.com/filled-form.pdf", "document.mime_type": "application/pdf"}]` |

## Context

Usually set through the instrumentation context API, which attaches them to every span in scope. See [Context Attributes](https://openinf.dev/spec/attributes/context.html.md).

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `session.id` | String | Unique identifier for a session | `"26bcd3d2-cad2-443d-a23c-625e47f3324a"` |
| `user.id` | String | Unique identifier for a user | `"9328ae73-7141-4f45-a044-8e06192aa465"` |
| `metadata` | JSON String | Metadata associated with a span | `"{'author': 'John Doe', 'date': '2023-09-09'}"` |
| `tag.tags` | List of strings | List of tags to give the span a category | `["shopping", "travel"]` |

## LLM

### Model Identification

See [LLM Spans](https://openinf.dev/spec/spans/llm.html.md#model-identification) for how these attributes relate.

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `llm.system` | String | The AI product as identified by the client or server instrumentation. See [well-known values](https://openinf.dev/spec/attributes/semantic-conventions.html.md#llm-system-values) | `"anthropic"`, `"openai"` |
| `llm.provider` | String | The hosting provider of the LLM, e.g. `azure`. See [well-known values](https://openinf.dev/spec/attributes/semantic-conventions.html.md#llm-provider-values) | `"openai"`, `"azure"` |
| `llm.model_name` | String | The name of the language model being utilized | `"gpt-3.5-turbo"` |
| `llm.request.model_name` | String | The model requested by the caller, as sent in the request. May differ from `llm.response.model_name` when the provider routes the request to a different model. | `"claude-opus-5"` |
| `llm.response.model_name` | String | The model that actually generated the response, as reported by the provider. May differ from `llm.request.model_name` when the provider routes the request to a different model. | `"claude-opus-4-8"` |

### Invocation

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `llm.invocation_parameters` | JSON String | Parameters used during the invocation of an LLM or API | `"{model_name: 'gpt-3', temperature: 0.7}"` |
| `llm.finish_reason` | String | The reason the model stopped generating tokens. | `"stop"`, `"length"` |
| `llm.function_call` | JSON String | Deprecated: use `message.tool_calls`. Object recording details of a function call in models or APIs | `"{function_name: 'add', args: [1, 2]}"` |

### Messages, Prompts, and Tools

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `llm.input_messages` | List of objects | List of messages sent to the LLM in a chat API request, e.g. `llm.input_messages.0.message.role`. See [Messages](https://openinf.dev/spec/content/messages.html.md) | `[{"message.role": "user", "message.content": "hello"}]` |
| `llm.output_messages` | List of objects | List of messages received from the LLM in a chat API response, e.g. `llm.output_messages.0.message.role`. See [Messages](https://openinf.dev/spec/content/messages.html.md) | `[{"message.role": "assistant", "message.content": "hello"}]` |
| `llm.prompts` | List of objects | Prompts provided to a completions API, e.g. `llm.prompts.0.prompt.text` | `[{"prompt.text": "def fib(n):..."}]` |
| `llm.choices` | List of objects | Text choices returned from a completions API, e.g. `llm.choices.0.completion.text` | `[{"completion.text": " + fib(n-3)..."}]` |
| `llm.tools` | List of objects | List of tools that are advertised to the LLM to be able to call, e.g. `llm.tools.0.tool.name`, `llm.tools.0.tool.description`, `llm.tools.0.tool.json_schema`. See [Tool Calling](https://openinf.dev/spec/content/tool-calling.html.md) | `[{"tool.name": "get_weather", "tool.json_schema": "{\"type\": \"function\", \"function\": {\"name\": \"get_weather\"}}"}]` |

### Prompt Template

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `llm.prompt_template.template` | String | Template used to generate prompts (e.g., using `{variable}` placeholder syntax) | `"Weather forecast for {city} on {date}"` |
| `llm.prompt_template.variables` | JSON String | JSON of key value pairs applied to the prompt template | `{ context: "<context from retrieval>", subject: "math" }` |
| `llm.prompt_template.version` | String | The version of the prompt template | `"v1.0"` |

### Token Counts

All token counts are integers. The `*_details.*` values are sub-counts of their parent count; see [LLM Spans](https://openinf.dev/spec/spans/llm.html.md#token-counts).

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `llm.token_count.prompt` | Integer | The number of tokens in the prompt | `10` |
| `llm.token_count.prompt_details.audio` | Integer | The number of audio input tokens presented in the prompt | `10` |
| `llm.token_count.prompt_details.cache_input` | Integer | The number of input tokens in the prompt that were cached | `5` |
| `llm.token_count.prompt_details.cache_read` | Integer | The number of prompt tokens successfully retrieved from cache (cache hits). Maps to `cached_tokens` in OpenAI responses | `5` |
| `llm.token_count.prompt_details.cache_write` | Integer | The number of prompt tokens not found in cache that were written to cache (cache misses). Maps to `cache_write_tokens` in OpenAI responses | `0` |
| `llm.token_count.completion` | Integer | The number of tokens in the completion | `15` |
| `llm.token_count.completion_details.audio` | Integer | The number of audio tokens generated by the model | `10` |
| `llm.token_count.completion_details.reasoning` | Integer | The number of tokens used for model reasoning | `10` |
| `llm.token_count.total` | Integer | Total number of tokens, including prompt and completion | `20` |

### Cost

All costs are floating point values in USD. See [LLM Spans](https://openinf.dev/spec/spans/llm.html.md#cost).

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `llm.cost.prompt` | Float | Total cost of all input tokens sent to the LLM in USD | `0.0021` |
| `llm.cost.prompt_details.input` | Float | Total cost of input tokens in USD | `0.0003` |
| `llm.cost.prompt_details.audio` | Float | Cost of audio tokens in the prompt in USD | `0.0003` |
| `llm.cost.prompt_details.cache_input` | Float | Cost of input tokens in the prompt that were cached in USD | `0.0006` |
| `llm.cost.prompt_details.cache_read` | Float | Cost of prompt tokens read from cache in USD | `0.0003` |
| `llm.cost.prompt_details.cache_write` | Float | Cost of prompt tokens written to cache in USD | `0.0006` |
| `llm.cost.completion` | Float | Total cost of all output tokens generated by the LLM in USD | `0.0045` |
| `llm.cost.completion_details.output` | Float | Total cost of output tokens in USD | `0.0009` |
| `llm.cost.completion_details.reasoning` | Float | Cost of reasoning steps in the completion in USD | `0.0024` |
| `llm.cost.completion_details.audio` | Float | Cost of audio tokens in the completion in USD | `0.0012` |
| `llm.cost.total` | Float | Total cost of the LLM call in USD (prompt + completion) | `0.0066` |

### LLM System Values

[Well-known values](https://openinf.dev/spec/attributes/conventions.html.md#well-known-values) for `llm.system`:

| Value | Description |
| - | - |
| `anthropic` | Anthropic |
| `openai` | OpenAI |
| `vertexai` | Vertex AI |
| `cohere` | Cohere |
| `mistralai` | Mistral AI |
| `xai` | xAI (Grok) |
| `deepseek` | DeepSeek |
| `amazon` | Amazon Bedrock native |
| `meta` | Meta (Llama) |
| `ai21` | AI21 Labs |
| `typesafe` | TypeSafe AI |

### LLM Provider Values

[Well-known values](https://openinf.dev/spec/attributes/conventions.html.md#well-known-values) for `llm.provider`:

| Value | Description |
| - | - |
| `anthropic` | Anthropic |
| `openai` | OpenAI |
| `cohere` | Cohere |
| `mistralai` | Mistral AI |
| `azure` | Azure |
| `google` | Google (Vertex) |
| `aws` | AWS Bedrock |
| `xai` | xAI |
| `deepseek` | DeepSeek |
| `groq` | Groq |
| `fireworks` | Fireworks AI |
| `moonshot` | Moonshot AI |
| `cerebras` | Cerebras |
| `perplexity` | Perplexity |
| `together` | Together AI |
| `ollama` | Ollama |
| `meta` | Meta AI |
| `zai` | Z.ai (GLM) |
| `minimax` | MiniMax |
| `typesafe` | TypeSafe AI |
| `oracle` | Oracle (OCI Generative AI) |
| `ibm` | IBM (watsonx.ai) |
| `doubleword` | Doubleword |

## Message

Items of `llm.input_messages` and `llm.output_messages`. See [Messages](https://openinf.dev/spec/content/messages.html.md).

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `message.role` | String | Role of the entity in a message (e.g., user, system) | `"user"`, `"system"` |
| `message.content` | String | The content of a message in a chat | `"What's the weather today?"` |
| `message.contents` | List of objects | The message contents to the LLM, an array of `message_content` objects. Use this form when a message has multiple content items or when item ordering matters. | `[{"message_content.type": "text", "message_content.text": "Hello"}]` |
| `message.name` | String | The name of the function or tool that produced a tool/function role message. Used when `message.role` is `"tool"` or `"function"` to identify the origin. | `"multiply"` |
| `message.tool_calls` | List of objects | List of tool calls (e.g. function calls) generated by the LLM, e.g. `llm.output_messages.0.message.tool_calls.0.tool_call.id` | `[{"tool_call.function.name": "get_current_weather"}]` |
| `message.tool_call_id` | String | Tool call result identifier corresponding to `tool_call.id` | `"call_62136355"` |
| `message.function_call_name` | String | Deprecated: use `message.tool_calls`. Function call function name | `"multiply"` |
| `message.function_call_arguments_json` | JSON String | Deprecated: use `message.tool_calls`. The arguments to the function call in JSON | `"{ 'x': 2 }"` |

## Message Content

Items of `message.contents`. See [Multimodal Content](https://openinf.dev/spec/content/multimodal.html.md) and [Reasoning Content](https://openinf.dev/spec/content/messages.html.md#reasoning-content).

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `message_content.type` | String | The type of the content. Use `"reasoning"` for reasoning/thinking content, including Anthropic `redacted_thinking` blocks. Use `"tool_use"` when a provider returns a tool call as an ordered content part. | `"text"`, `"image"`, `"audio"`, `"video"`, `"document"`, `"reasoning"`, `"tool_use"` |
| `message_content.text` | String | The text content of the message. Used when `message_content.type` is `"text"` or `"reasoning"` (visible reasoning or summary text). For OpenAI `summary_text` arrays, concatenate the array items into this single text value for now. | `"This is a sample text"` |
| `message_content.image` | Image Object | The image content of the message, if the type is `"image"`. | `{"image.url": "https://sample-link-to-image.jpg"}` |
| `message_content.audio` | Audio Object | The audio content of the message, if the type is `"audio"`. Nested leaves are `audio.url` and `audio.transcript`. | `{"audio.url": "https://example.com/audio.mp3"}` |
| `message_content.video` | Video Object | The video content of the message, if the type is `"video"`. The nested leaf is `video.url`. Consumers infer MIME type from the URL path extension or a data URI prefix. | `{"video.url": "gs://bucket/clip.mp4"}` |
| `message_content.document` | Document Object | The document content of the message (e.g. a PDF, an uploaded file, or inline text), if the type is `"document"`. Nested leaves are `document.url`, `document.content`, `document.mime_type`, `document.id`, and `document.name`. | `{"document.url": "data:application/pdf;base64,JVBERi0...", "document.mime_type": "application/pdf"}` |
| `message_content.id` | String | Provider-assigned identifier for this message content item. For OpenAI Responses reasoning items, this maps to `ResponseReasoningItem.id` and should be preserved for stateless replay. | `"rs_abc123"` |
| `message_content.signature` | String | Opaque vendor-issued signature captured verbatim. Maps to provider `signature` fields, and to Gemini `thoughtSignature` fields when the signature is attached to a non-tool content part such as text. | `"EuYBCkQYAiJA..."` |
| `message_content.data` | String | Opaque vendor-issued data captured verbatim. Maps to Anthropic `redacted_thinking.data`. | `"EmwKAhgBEgy3..."` |
| `message_content.encrypted_content` | String | OpenAI `encrypted_content` captured verbatim. | `"gAAAAA...=="` |

## Prompt

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `prompt.text` | String | The text of a prompt in a completions API request. Used under `llm.prompts`. | `"def fib(n):..."` |
| `prompt.vendor` | String | The vendor or origin of the prompt, e.g. `langsmith`, `portkey`, `arize-phoenix` | `"langchain"` |
| `prompt.id` | String | A vendor-specific id used to identify the prompt. | `"1234"` |
| `prompt.url` | String | A vendor-specific URL used to locate the prompt via the web | `"https://smith.langchain.com/prompts/naive-prompt"` |

## Completion

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `completion.text` | String | The text of a choice returned from a completions API. Used under `llm.choices`. | `" + fib(n-3)..."` |

## Tool

On a `TOOL` span, these attributes describe the tool being invoked; under `llm.tools.<index>`, an advertised tool definition. See [Tool Calling](https://openinf.dev/spec/content/tool-calling.html.md).

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `tool.name` | String | The name of the tool. On a `TOOL` span, the tool being invoked; under `llm.tools.<index>`, the name of an advertised tool definition | `"WeatherAPI"` |
| `tool.description` | String | Description of the tool’s purpose and functionality. On a `TOOL` span, the tool being invoked; under `llm.tools.<index>`, an advertised tool definition | `"An API to get weather data."` |
| `tool.json_schema` | JSON String | The JSON schema of a tool input | `"{'type': 'function', 'function': {'name': 'get_weather'}}"` |
| `tool.parameters` | JSON String | The parameters definition for invoking the tool | `"{ 'a': 'int' }"` |
| `tool.id` | String | The identifier for the result of the tool call (corresponding to `tool_call.id`) | `"call_62136355"` |

## Tool Call

Items of `message.tool_calls`, and of `message.contents` when `message_content.type` is `"tool_use"`. See [Tool Calling](https://openinf.dev/spec/content/tool-calling.html.md).

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `tool_call.id` | String | The id of a tool call (useful when there is more than one call at the same time) | `"call_62136355"` |
| `tool_call.function.name` | String | The name of the function being invoked by a tool call | `"get_current_weather"` |
| `tool_call.function.arguments` | JSON String | The arguments for the function being invoked by a tool call | `"{'city': 'London'}"` |
| `tool_call.reasoning_signature` | String | Opaque vendor-issued reasoning echo token attached to a tool call. Used by Gemini, which puts `thoughtSignature` on `functionCall` parts rather than on the reasoning summary. | `"CiQB..."` |

## Image

Composed under `message_content.image` and `<input|output>.images`. See [Multimodal Content](https://openinf.dev/spec/content/multimodal.html.md).

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `image.url` | String | The link to the image or its base64 encoding | `"https://sample-link-to-image.jpg"` |

## Audio

Composed under `message_content.audio`. See [Multimodal Content](https://openinf.dev/spec/content/multimodal.html.md#audio-content).

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `audio.url` | String | The URL of an audio file (e.g. cloud storage), or a base64 data URI | `"https://storage.com/buckets/1/file.wav"` |
| `audio.transcript` | String | The transcript of the audio file (e.g. a Whisper transcription) | `"Hello, how are you?"` |
| `audio.mime_type` | String | Legacy. Infer the type from `audio.url` instead; new instrumentors should not emit this. | `"audio/mpeg"` |

## Video

Composed under `message_content.video`. See [Multimodal Content](https://openinf.dev/spec/content/multimodal.html.md#video-content).

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `video.url` | String | The URL, object-store URI, or base64 data URI of a video. Consumers infer MIME type from the path extension (`.mp4` to `video/mp4`, `.webm` to `video/webm`, `.ogv` to `video/ogg`, `.avi` to `video/x-msvideo`) or from a data URI prefix. | `"gs://bucket/clip.mp4"` |

## Document

Items of `retrieval.documents`, `reranker.input_documents`, `reranker.output_documents`, and `<input|output>.documents`, and the leaves of `message_content.document`. See [Document Content](https://openinf.dev/spec/content/multimodal.html.md#document-content).

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `document.id` | String/Integer | Unique identifier for a document: a retrieved document or chunk in a retrieval system, or the provider file id (e.g. an OpenAI or Anthropic Files API id) for a document passed to a model | `"1234"`, `1`, `"file-abc123"` |
| `document.content` | String | The text content of a document: a retrieved passage, or an inline text document passed to a model (e.g. an Anthropic `text` source) | `"This is a sample document content."` |
| `document.score` | Float | Score representing the relevance of a document | `0.98` |
| `document.metadata` | JSON String | Metadata associated with a document | `"{'author': 'John Doe', 'date': '2023-09-09'}"` |
| `document.url` | String | The URL, object-store URI, or base64 data URI of a file document such as a PDF | `"https://example.com/report.pdf"` |
| `document.mime_type` | String | The MIME type of a file document such as a PDF | `"application/pdf"` |
| `document.name` | String | The name supplied with a document, copied verbatim: a file name (OpenAI `filename`) or a title (Anthropic `title`, Bedrock `name`, Gemini `display_name`); not a unique identifier | `"invoice.pdf"` |

## Retrieval

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `retrieval.documents` | List of objects | List of retrieved documents | `[{"document.id": "1", "document.score": 0.9, "document.content": "..."}]` |

## Reranker

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `reranker.query` | String | Query parameter of the reranker | `"How to format timestamp?"` |
| `reranker.model_name` | String | Model name of the reranker | `"cross-encoder/ms-marco-MiniLM-L-12-v2"` |
| `reranker.top_k` | Integer | Top K parameter of the reranker | `3` |
| `reranker.input_documents` | List of objects | List of documents as input to the reranker | `[{"document.id": "1", "document.score": 0.9, "document.content": "..."}]` |
| `reranker.output_documents` | List of objects | List of documents outputted by the reranker | `[{"document.id": "1", "document.score": 0.9, "document.content": "..."}]` |

## Embedding

See [Embedding Spans](https://openinf.dev/spec/spans/embedding.html.md).

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `embedding.model_name` | String | Name of the embedding model used | `"BERT-base"` |
| `embedding.invocation_parameters` | JSON String | Parameters used during the invocation of an embedding model or API (excluding input) | `"{\"model\": \"text-embedding-3-small\", \"encoding_format\": \"float\"}"` |
| `embedding.embeddings` | List of objects | List of embedding objects including text and vector data | `[{"embedding.vector": [...], "embedding.text": "hello"}]` |
| `embedding.text` | String | The text represented in the embedding | `"hello world"` |
| `embedding.vector` | List of floats | The embedding vector consisting of a list of floats | `[0.123, 0.456, ...]` |

## Decision

See [Decision Spans](https://openinf.dev/spec/spans/decision.html.md).

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `decision.system` | String | The decision API ecosystem the call conforms to, i.e. which request/response shape the client speaks, as identified by the client or server instrumentation: `typesafe` for the TypeSafe System One / Jev API, `openai` for the OpenAI Decisions API. A self-hosted vLLM server answering the Jev-compatible `/v1/systemone` shape is still `typesafe`. Distinct from `decision.provider`, which says who hosts the model. See the [well-known values](https://openinf.dev/spec/attributes/semantic-conventions.html.md#decision-system-and-provider-values), which alias the matching `llm.system` values. | `"typesafe"` |
| `decision.provider` | String | The hosting provider of the decision model: who runs the hardware that answered, e.g. `typesafe` when calling TypeSafe directly, `openai` for the OpenAI Decisions API, or the cloud or self-hosting provider for a model served elsewhere. Distinct from `decision.system`, which names the API shape. See the [well-known values](https://openinf.dev/spec/attributes/semantic-conventions.html.md#decision-system-and-provider-values), which alias the matching `llm.provider` values. | `"typesafe"` |
| `decision.model_name` | String | The name of the decision model being utilized. Mirrors `llm.model_name` for `DECISION` spans. | `"jev-1.13.0"` |
| `decision.request.model_name` | String | The decision model requested by the caller, as sent in the request. May differ from `decision.response.model_name` when the provider resolves an alias or routes the request. | `"jev-latest"` |
| `decision.response.model_name` | String | The decision model that actually produced the response, as reported by the provider. May differ from `decision.request.model_name`. | `"jev-1.13.0"` |
| `decision.token_count.input` | Integer | The number of input tokens consumed by a decision model call: the state, questions, and candidate options. Maps to `usage.input_tokens` in TypeSafe System One responses. | `412` |
| `decision.token_count.output` | Integer | The number of output tokens produced by a decision model call. Decision models emit typed answers rather than text, so this is typically small. Maps to `usage.output_tokens` in TypeSafe System One responses. | `2` |

### Decision System and Provider Values

`decision.system` and `decision.provider` draw from the same identifier space as `llm.system` and `llm.provider`: the same string names the same vendor in both attribute families, and the semantic convention packages expose the decision values as aliases of the matching LLM values (for example `OpenInferenceDecisionSystemValues.TYPESAFE` is `OpenInferenceLLMSystemValues.TYPESAFE`). The decision lists are the subset of vendors currently known to offer a decision API. They are [well-known values](https://openinf.dev/spec/attributes/conventions.html.md#well-known-values).

`decision.system`:

| Value | Description |
| - | - |
| `typesafe` | [TypeSafe AI System One / Jev API](https://typesafe.ai/blog/introducing-system-one-models-and-jev), including Jev-compatible servers such as vLLM’s `/v1/systemone` |
| `openai` | [OpenAI Decisions API](https://openai.com/index/devday-2026-recap/) |

`decision.provider`:

| Value | Description |
| - | - |
| `typesafe` | TypeSafe AI |
| `openai` | OpenAI |

vLLM’s native `/v1/decisions` API ([RFC](https://github.com/vllm-project/vllm/issues/59365)) does not yet have a well-known value; a custom value MAY be used until it is added.

## Agent

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `agent.name` | String | The name of the agent that this span represents. | `"researcher"` |

## Graph

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `graph.node.id` | String | The id of the node in the execution graph. This along with `graph.node.parent_id` are used to visualize the execution graph. | `"search_api_0"` |
| `graph.node.name` | String | The name of the node in the execution graph. Use this to present a human readable name for the node. Optional | `"Search API"` |
| `graph.node.parent_id` | String | This references the id of the parent node. Leaving this unset or set as empty string implies that the current span is the root node. | `"router_0"` |

## Annotation and Evaluation

Feedback from human, LLM, and code judges. The `annotation.*` and `evaluation.*` forms are equivalent; see [Annotations and Evaluations](https://openinf.dev/spec/feedback/annotations.html.md).

### Feedback Lists

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `annotations` | List of objects | Span-scoped feedback using annotation terminology, flattened as `annotations.0.annotation.*` | `[{"annotation.name": "hallucination", "annotation.label": "hallucinated"}]` |
| `trace.annotations` | List of objects | Trace-scoped feedback using annotation terminology, flattened as `trace.annotations.0.annotation.*` | `[{"annotation.name": "retrieval_quality", "annotation.score": 0.92}]` |
| `session.annotations` | List of objects | Session-scoped feedback using annotation terminology, flattened as `session.annotations.0.annotation.*`; requires `session.id` | `[{"annotation.name": "conversational_coherence", "annotation.label": "coherent"}]` |
| `evaluations` | List of objects | Span-scoped feedback using evaluation or eval terminology, flattened as `evaluations.0.evaluation.*` | `[{"evaluation.name": "relevance", "evaluation.score": 0.95}]` |
| `trace.evaluations` | List of objects | Trace-scoped feedback using evaluation terminology, flattened as `trace.evaluations.0.evaluation.*` | `[{"evaluation.name": "retrieval_quality", "evaluation.score": 0.92}]` |
| `session.evaluations` | List of objects | Session-scoped feedback using evaluation terminology, flattened as `session.evaluations.0.evaluation.*`; requires `session.id` | `[{"evaluation.name": "conversational_coherence", "evaluation.label": "coherent"}]` |

### Result Fields

Each item carries these fields, under `annotation.*` or `evaluation.*`.

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `annotation.name`, `evaluation.name` | String | Criterion or metric name | `"hallucination"`, `"relevance"` |
| `annotation.score`, `evaluation.score` | Integer/Float | Numeric result | `1`, `0.95` |
| `annotation.label`, `evaluation.label` | String | Categorical result | `"hallucinated"`, `"relevant"` |
| `annotation.explanation`, `evaluation.explanation` | String | Reason or evidence for the result | `"The claim is not supported by the context."` |
| `annotation.annotator_kind`, `evaluation.annotator_kind` | String | Judge kind: `HUMAN`, `LLM`, `CODE`, or custom. See [Annotator Kinds](https://openinf.dev/spec/feedback/annotations.html.md#annotator-kinds) | `"LLM"`, `"HUMAN"` |
| `annotation.identifier`, `evaluation.identifier` | String | Stable result ID for the same name and target | `"judge-v2"`, `"reviewer-42"` |
| `annotation.metadata`, `evaluation.metadata` | JSON String | Additional result or judge data | `"{\"evaluator\":\"judge-v2\"}"` |

## Exception

These attributes are defined by OpenTelemetry’s [exception semantic conventions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/) and recorded on an `exception` span event.

| Attribute | Type | Description | Examples |
| - | - | - | - |
| `exception.type` | String | The type of exception that was thrown | `"NullPointerException"` |
| `exception.message` | String | Detailed message describing the exception | `"Null value encountered"` |
| `exception.stacktrace` | String | The stack trace of the exception | `"at app.main(app.java:16)"` |
| `exception.escaped` | Boolean | Indicator if the exception has escaped the span’s scope | `true` |
