Skip to content

WIP | Add input and output versioning schema docs #225

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nikhilNava wants to merge 1 commit into
base: main
Choose a base branch
from
Open

WIP | Add input and output versioning schema docs #225

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
306 changes: 306 additions & 0 deletions src/Observability/Runtime/docs/schemas/EXAMPLES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,306 @@
# A365 Input/Output Message Schema Examples

> **A365 Schema Version:** 1.0.0 | **Based on OTel Semconv:** v1.40.0

---

## Input Message Examples (`gen_ai.input.messages`)

### Simple — Text Chat

```json
[
{
"role": "system",
"parts": [
{ "type": "text", "content": "You are a helpful assistant." }
]
},
{
"role": "user",
"parts": [
{ "type": "text", "content": "What meetings do I have today?" }
]
}
]
```

### Complex — All Input Part Types

A multi-turn conversation demonstrating every input part type: text, tool_call (from prior assistant turn), tool_call_response, server_tool_call, server_tool_call_response, blob, file, uri, reasoning, and a custom generic part.

```json
[
{
"role": "system",
"parts": [
{ "type": "text", "content": "You are a project assistant with access to tools, files, and images." }
],
"name": "OrchestratorAgent"
},
{
"role": "user",
"parts": [
{ "type": "text", "content": "Summarize the attached document, check the weather in Seattle, and describe the whiteboard photo." },
{
"type": "file",
"modality": "image",
Copy link

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This example sets modality to image while mime_type is application/pdf. That combination is confusing for readers and doesn’t match the modality meaning in the schema description; consider changing modality to a more appropriate value (or update the example to use an actual image MIME type).

Suggested change
"modality": "image",
"modality": "document",

Copilot uses AI. Check for mistakes.
"mime_type": "application/pdf",
"file_id": "file-report-q1-2026"
},
{
"type": "uri",
"modality": "image",
"mime_type": "image/png",
"uri": "https://sharepoint.com/sites/team/whiteboard-photo.png"
},
{
"type": "blob",
"modality": "audio",
"mime_type": "audio/wav",
"content": "/9j/4AAQSkZJRg..."
Copy link

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The blob example declares mime_type: audio/wav and modality: audio, but the base64 prefix /9j/ is commonly associated with JPEG data. Consider updating either the MIME/modality or the sample base64 so the example is internally consistent.

Suggested change
"content": "/9j/4AAQSkZJRg..."
"content": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAIlYAAESsAAACABAAZGF0YQAA..."

Copilot uses AI. Check for mistakes.
}
],
"name": "UserJohnDoe"
},
{
"role": "assistant",
"parts": [
{ "type": "text", "content": "Let me look up the weather and analyze your files." },
{
"type": "tool_call",
"id": "call_weather_001",
"name": "get_weather",
"arguments": { "city": "Seattle", "units": "fahrenheit" }
},
{
"type": "reasoning",
"content": "User attached a PDF, an image URI, and an audio blob. I should process the weather tool call first, then analyze the attachments."
}
]
},
{
"role": "tool",
"parts": [
{
"type": "tool_call_response",
"id": "call_weather_001",
"response": { "temperature": 57, "condition": "rainy", "humidity": 82 }
}
]
},
{
"role": "assistant",
"parts": [
{
"type": "server_tool_call",
"id": "stc_code_001",
"name": "code_interpreter",
"server_tool_call": {
"type": "code_interpreter",
"code": "import pandas as pd\ndf = pd.read_csv('sales.csv')\nprint(df.describe())"
}
},
{
"type": "server_tool_call_response",
"id": "stc_code_001",
"server_tool_call_response": {
"type": "code_interpreter",
"output": "count: 1200, mean: 45000, max: 120000"
}
}
]
},
{
"role": "user",
"parts": [
{
"type": "microsoft.a365.adaptive_card",
"card_id": "ac-approval-001",
"action": "approved"
}
],
"name": "UserJohnDoe"
}
]
```

**Part types demonstrated:**

| Part Type | Where Used | Description |
|---|---|---|
| `text` | system, user, assistant | Plain text messages |
| `tool_call` | assistant (prior turn) | Model requested a client-side tool |
| `tool_call_response` | tool | Client-side tool result sent back |
| `server_tool_call` | assistant (prior turn) | Server-side tool invocation |
| `server_tool_call_response` | assistant (prior turn) | Server-side tool result |
| `blob` | user | Inline binary data (base64) |
| `file` | user | Pre-uploaded file reference |
| `uri` | user | External file by URL |
| `reasoning` | assistant (prior turn) | Chain-of-thought from model |
| `microsoft.a365.adaptive_card` | user | Custom A365 GenericPart |

---

## Output Message Examples (`gen_ai.output.messages`)

### Simple — Text Response

```json
[
{
"role": "assistant",
"finish_reason": "stop",
"parts": [
{ "type": "text", "content": "You have 3 meetings today: standup at 9 AM, design review at 11 AM, and a 1:1 at 3 PM." }
]
}
]
```

### Complex — All Output Part Types

A response demonstrating every output part type: reasoning, text, tool_call, server_tool_call with response, and a custom generic part. Also shows multiple finish reasons.
Comment on lines +161 to +163
Copy link

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section claims the JSON demonstrates “every output part type” and includes “a custom generic part”, but the example shown does not include tool_call_response, file, or any custom GenericPart instance. Either adjust the claim/header, or extend the example to actually include the missing part types.

Suggested change
### Complex — All Output Part Types
A response demonstrating every output part type: reasoning, text, tool_call, server_tool_call with response, and a custom generic part. Also shows multiple finish reasons.
### Complex — Multiple Output Part Types
A response demonstrating several output part types: reasoning, text, server_tool_call with response, and image content as both blob and URI.

Copilot uses AI. Check for mistakes.

```json
[
{
"role": "assistant",
"finish_reason": "stop",
"parts": [
{
"type": "reasoning",
"content": "The user asked for a document summary, weather, and whiteboard analysis. I have the weather data from the tool call. The code_interpreter analyzed the sales data. I should compile all results into a structured response."
},
{
"type": "text",
"content": "Here's your summary:\n\n**Weather:** Seattle is currently rainy at 57°F with 82% humidity.\n\n**Q1 Report:** Revenue averaged $45K per deal across 1,200 transactions, with a max deal of $120K.\n\n**Whiteboard:** The whiteboard shows a system architecture diagram with three microservices connected via an API gateway."
},
{
"type": "server_tool_call",
"id": "stc_search_001",
"name": "web_search",
"server_tool_call": {
"type": "web_search",
"query": "Seattle weather forecast March 2026"
}
},
{
"type": "server_tool_call_response",
"id": "stc_search_001",
"server_tool_call_response": {
"type": "web_search",
"results": [
{ "title": "Seattle Weather - March 2026", "url": "https://weather.com/seattle", "snippet": "Expect rain through the week..." }
]
}
},
{
"type": "blob",
"modality": "image",
"mime_type": "image/png",
"content": "iVBORw0KGgoAAAANSUhEUg..."
},
{
"type": "uri",
"modality": "image",
"mime_type": "image/png",
"uri": "https://ai-generated.example.com/chart-q1-revenue.png"
}
],
"name": "ProjectAssistant"
}
]
```

**Additional output examples by finish reason:**

#### Tool Call Request

```json
[
{
"role": "assistant",
"finish_reason": "tool_call",
"parts": [
{ "type": "text", "content": "Let me check that for you." },
{
"type": "tool_call",
"id": "call_sales_q1",
"name": "query_sales_data",
"arguments": { "quarter": "Q1", "year": 2026 }
},
{
"type": "tool_call",
"id": "call_calendar",
"name": "get_calendar",
"arguments": { "date": "2026-03-25" }
}
]
}
]
```

#### Content Filter

```json
[
{
"role": "assistant",
"finish_reason": "content_filter",
"parts": [
{ "type": "text", "content": "I'm unable to provide that information due to content policy restrictions." }
]
}
]
```

#### Token Limit

```json
[
{
"role": "assistant",
"finish_reason": "length",
"parts": [
{ "type": "text", "content": "Here is the beginning of the report: Q1 revenue increased by 15% year-over-year driven by strong adoption of..." }
]
}
]
```

#### Error

```json
[
{
"role": "assistant",
"finish_reason": "error",
"parts": [
{ "type": "text", "content": "An error occurred while processing your request. Please try again." }
]
}
]
```

**Part types demonstrated in output:**

| Part Type | Description |
|---|---|
| `text` | Direct text response from model |
| `reasoning` | Chain-of-thought / thinking content |
| `tool_call` | Model requesting client-side tool execution |
| `server_tool_call` | Server-side tool invocation details |
| `server_tool_call_response` | Server-side tool result |
| `blob` | Generated binary content (e.g., chart image) |
| `uri` | Reference to generated content |

**Finish reasons demonstrated:**

| Finish Reason | Meaning |
|---|---|
| `stop` | Model completed naturally |
| `tool_call` | Model is requesting tool execution |
| `content_filter` | Blocked by content policy |
| `length` | Token limit exceeded |
| `error` | Generation encountered an error |
51 changes: 51 additions & 0 deletions src/Observability/Runtime/docs/schemas/SCHEMA-VERSION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# A365 Observability Input/Output Message Schema Versions

## Current Version

| Field | Value |
|---|---|
| **A365 Schema Version** | 1.0.0 |
| **OTel Semconv Baseline** | [v1.40.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.40.0) |
| **OTel Semconv Commit** | [`30003a993`](https://github.com/open-telemetry/semantic-conventions/commit/30003a9937eb7bcde6984877149055278405e03c) |

## Schema Files

| File | Span Attribute | Description |
|---|---|---|
| [a365-input-messages.json](a365-input-messages.json) | `gen_ai.input.messages` | Chat history sent to the model |
| [a365-output-messages.json](a365-output-messages.json) | `gen_ai.output.messages` | Model response (choices/candidates) |

## OTel Semconv Compatibility Matrix

| A365 Schema Version | Based on OTel Semconv | Part Types | Notes |
|---|---|---|---|
| 1.0.0 | v1.40.0 | 10 (all OTel types) | Initial release. Includes ServerToolCall parts added in v1.40.0 |

### OTel Input/Output Schema Change History (for reference)

| OTel Semconv | File SHA (input) | Changes from Previous |
|---|---|---|
| v1.36.0 | — | Schema files did not exist |
| v1.37.0 | `22910f30` | **Schema introduced.** 4 part types: Text, ToolCallRequest, ToolCallResponse, Generic. No `name` field. |
| v1.38.0 | `5fbd431f` | **Major expansion.** Added Blob, File, Uri, Reasoning parts. Added Modality enum. Added `name` field to ChatMessage. |
| v1.39.0 | `5fbd431f` | No changes (identical to v1.38.0) |
| v1.40.0 | `5585531c` | Added ServerToolCallPart, ServerToolCallResponsePart. Minor wording fix. |

## Applicable Scopes

| A365 Scope | Uses This Schema? | Notes |
|---|---|---|
| `InvokeAgentScope` | ✅ | Full conversation context |
| `InferenceScope` | ✅ | Chat history + model response |
| `OutputScope` | ✅ | Outgoing messages to user |
| `ExecuteToolScope` | ❌ | Uses `gen_ai.tool.*` attributes instead |
Comment on lines +36 to +41
Copy link

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The schema describes gen_ai.input.messages as a JSON array of structured message objects, but the current runtime scopes (e.g., InferenceScope/InvokeAgentScope/OutputScope) set this tag to a comma-separated string via string.Join. Either update this doc to clarify it’s a JSON-encoded value produced by specific instrumentations (and not by the built-in scopes today), or update the scopes/tests to emit JSON conforming to this schema.

Copilot uses AI. Check for mistakes.

## Changelog

### 1.0.0

- Initial A365 input/output message schema
- Profiles OTel GenAI semconv v1.40.0 input/output messages format
- Supports all OTel part types: TextPart, ToolCallRequestPart, ToolCallResponsePart, ServerToolCallPart, ServerToolCallResponsePart, BlobPart, FilePart, UriPart, ReasoningPart, GenericPart
- All objects allow `additionalProperties` for future A365-specific extensions
- Custom A365 part types can be added via `GenericPart` using `microsoft.a365.*` type prefix
Loading
Loading