dotnet · jeffhandley · May 8, 2026 · May 8, 2026
@@ -1,6 +1,21 @@
 # Change Classification
 
-Taxonomy for classifying gen-ai changes from semantic-conventions releases. Use this to assess each change's impact on dotnet/extensions.
+Taxonomy for classifying GenAI semantic-conventions changes from PRs, CHANGELOG snapshots, date ranges, or releases (when they exist) in [`open-telemetry/semantic-conventions-genai`](https://github.com/open-telemetry/semantic-conventions-genai). Old-repo `area:gen-ai` PRs (pre-migration) classify the same way. Use this to assess each change's impact on dotnet/extensions.
+
+## Areas
+
+The new repo hosts conventions for several areas. Identify the **area** of each change from its path under `model/<area>/` or `docs/<area>/` in the new repo:
+
+| Area | dotnet/extensions location |
+|---|---|
+| `gen-ai`, `gen-ai/agent` | `Microsoft.Extensions.AI` core (e.g. `OpenTelemetryChatClient`) |
+| `mcp` | No instrumentation today — classify all `mcp` changes as 🟢 *No client exists* unless and until an MCP client is added |
+| `openai` | `Microsoft.Extensions.AI.OpenAI` (provider package) |
+| `anthropic` | Out of scope for `dotnet/extensions` (no provider package). Classify as 🟢 *No client exists* **from the perspective of this repo**. The compensating change actually lands in [`anthropics/anthropic-sdk-csharp`](https://github.com/anthropics/anthropic-sdk-csharp) — see [SKILL.md §Cross-repo applicability](../SKILL.md#cross-repo-applicability). |
+| `aws-bedrock` | Out of scope for `dotnet/extensions` (no provider package). Classify as 🟢 *No client exists* **from the perspective of this repo**. The compensating change actually lands in the `BedrockRuntime` service library of [`aws/aws-sdk-net`](https://github.com/aws/aws-sdk-net) — see [SKILL.md §Cross-repo applicability](../SKILL.md#cross-repo-applicability). |
+| `azure-ai-inference` | Corresponding provider package if/when one exists in this repo; otherwise classify as 🟢 *No client exists* |
+
+When the area is provider-specific (`openai`, `anthropic`, `aws-bedrock`, `azure-ai-inference`), the compensating change usually belongs in the corresponding provider package, **not** in `Microsoft.Extensions.AI`. For `anthropic` ([`anthropics/anthropic-sdk-csharp`](https://github.com/anthropics/anthropic-sdk-csharp)) and `aws-bedrock` (the `BedrockRuntime` service library of [`aws/aws-sdk-net`](https://github.com/aws/aws-sdk-net)) this provider package lives in another SDK repo entirely; when running this skill in `dotnet/extensions`, audit-flag the change but classify it as out-of-scope and link the upstream change so a follow-up can be opened in the right SDK repo. When running this skill **in** that SDK repo, treat the area as in-scope and route the change to that repo's own constants/instrumentation files.
 
 ## Classification Categories
 
@@ -63,28 +78,32 @@ For each gen-ai change in a release:
 
 ## Audit Table Format
 
-When presenting the analysis, use this table format:
+When presenting the analysis, use this table format. The **Area** column lets reviewers see at a glance which dotnet/extensions package each change targets:
 
 ```markdown
-| Semantic Convention Change | Upstream PR | Classification | Action Required | Complexity |
-|---|---|---|---|---|
-| `gen_ai.new.attribute` | [#1234](link) | New required attribute | Add constant + emission + test | Low |
-| `gen_ai.deferred.attribute` | [#2345](link) | Constant not yet emitted | Defer — no client populates this attribute in this PR | — |
-| `retrieval` operation | [#5678](link) | N/A — No client | None | — |
-| Version reference | — | Version bump | Update doc comments | Low |
+| Area | Semantic Convention Change | Upstream PR | Classification | Action Required | Complexity |
+|---|---|---|---|---|---|
+| `gen-ai` | `gen_ai.new.attribute` | [open-telemetry/semantic-conventions-genai#1234](link) | New required attribute | Add constant + emission + test in `Microsoft.Extensions.AI` | Low |
+| `gen-ai` | `gen_ai.deferred.attribute` | [open-telemetry/semantic-conventions-genai#2345](link) | Constant not yet emitted | Defer — no client populates this attribute in this PR | — |
+| `mcp` | `mcp.tool.approval` | [open-telemetry/semantic-conventions-genai#3456](link) | N/A — No client | None — no MCP instrumentation today | — |
+| `openai` | `openai.new.attribute` | [open-telemetry/semantic-conventions-genai#4567](link) | New required attribute | Add to `Microsoft.Extensions.AI.OpenAI` provider package | Low |
+| `anthropic` | `anthropic.new.attribute` | [open-telemetry/semantic-conventions-genai#5678](link) | N/A — No client (in this repo) | Out of scope here — [`anthropics/anthropic-sdk-csharp`](https://github.com/anthropics/anthropic-sdk-csharp) is the actual target. Open a follow-up there. | — |
+| `gen-ai` | Version reference | — | Version bump | Update doc comments to new wording | Low |
 ```
 
 ## PR Description Table Format
 
-When preparing a PR description, adapt the audit table into a concise reviewer-facing table grouped or sorted by semantic-conventions version. Include every analyzed gen-ai change, not just changes that required code edits.
+When preparing a PR description, adapt the audit table into a concise reviewer-facing table grouped or sorted by GenAI version (the version from the schema URL or CHANGELOG release header — independent of core semconv). Include every analyzed change, not just changes that required code edits.
 
 ```markdown
-| Version | Indicator | Semantic-conventions change | Classification | Compensating change / rationale |
-|---|:---:|---|---|---|
-| v1.XX | 🔴 | `gen_ai.new.attribute` added | New required attribute | Added constant, emission, and tests in `{files}`. |
-| v1.XX | 🟡 | Version reference update | Version bump | Updated OpenTelemetry* doc comments to v1.XX. |
-| v1.XX | 🟢 | Provider server span clarified | Server-side only | No client-side instrumentation change needed. |
-| v1.XX | 🟢 | `gen_ai.deferred.attribute` added upstream | Constant not yet emitted | No client populates this attribute today; constant will be added in the PR that adds emission. |
+| Version | Area | Indicator | Semantic-conventions change | Classification | Compensating change / rationale |
+|---|---|:---:|---|---|---|
+| vX.Y.Z | `gen-ai` | 🔴 | `gen_ai.new.attribute` added | New required attribute | Added constant, emission, and tests in `{files}`. |
+| vX.Y.Z | `gen-ai` | 🟡 | Version reference update | Version bump | Updated OpenTelemetry* doc comments to the new wording. |
+| vX.Y.Z | `gen-ai` | 🟢 | Provider server span clarified | Server-side only | No client-side instrumentation change needed. |
+| vX.Y.Z | `gen-ai` | 🟢 | `gen_ai.deferred.attribute` added upstream | Constant not yet emitted | No client populates this attribute today; constant will be added in the PR that adds emission. |
+| vX.Y.Z | `openai` | 🔴 | `openai.new.attribute` added | New required attribute | Added to `Microsoft.Extensions.AI.OpenAI` provider package. |
+| vX.Y.Z | `mcp` | 🟢 | `mcp.tool.approval` added | N/A — No client | No MCP instrumentation in this repo today. |
 ```
 
-The final column should either describe the compensating change made or explain why no code change was made, such as "already implemented", "no local source exists", "no client exists", "server-side only", "documentation-only clarification", or "no client populates this attribute today; constant deferred until a PR adds emission".
+The final column should either describe the compensating change made or explain why no code change was made, such as "already implemented", "no local source exists", "no client exists", "server-side only", "documentation-only clarification", "no client populates this attribute today; constant deferred until a PR adds emission", "provider-specific area not instrumented in this repo", or "out of scope here — implications land in `anthropics/anthropic-sdk-csharp` (anthropic) or the `BedrockRuntime` library of `aws/aws-sdk-net` (aws-bedrock); follow-up opened in that repo".
@@ -60,14 +60,61 @@ To discover any additional test files: `dir test\Libraries\Microsoft.Extensions.
 
 The semantic conventions version is referenced in a doc comment in specific OpenTelemetry* instrumentation client files. When bumping the version, update all files that match the grep below — not all OpenTelemetry* files contain the version reference.
 
-The reference looks like:
+### Current wording (pre-migration)
+
+The reference today still reads (carried over from when conventions lived in the core `open-telemetry/semantic-conventions` repo):
 
 ```csharp
 /// This class provides an implementation of the Semantic Conventions for Generative AI systems v1.XX,
 /// defined at <see href="https://opentelemetry.io/docs/specs/semconv/gen-ai/" />.
 ```
 
-Find all occurrences with:
+### Target wording (post-migration)
+
+After the GenAI conventions moved to [`open-telemetry/semantic-conventions-genai`](https://github.com/open-telemetry/semantic-conventions-genai), the doc comment should call out the standalone repo and use the GenAI-namespaced version (matching the schema URL `opentelemetry.io/schemas/gen-ai/X.Y.Z`):
+
+```csharp
+/// This class provides an implementation of the GenAI Semantic Conventions vX.Y.Z,
+/// defined at <see href="https://opentelemetry.io/docs/specs/semconv/gen-ai/" />.
+```
+
+The `<see href>` URL is unchanged — the published spec page still resolves and renders the gen-ai spec from the new repo.
+
+### Wording migration
+
+This wording change is a **one-time edit** that should ride along with the
+**next convention-update PR** (not a separate cosmetic PR). Until that
+update lands, both wordings may coexist transiently in the codebase.
+
+### Finding occurrences during the transition
+
+Use a regex that matches both wordings:
+
+```bash
+grep -rEn "Semantic Conventions for Generative AI systems v|GenAI Semantic Conventions v" src/Libraries/Microsoft.Extensions.AI/
 ```
-grep -rn "Semantic Conventions for Generative AI systems v" src/Libraries/Microsoft.Extensions.AI/
+
+Once every file has been migrated to the target wording, the regex can be
+simplified back to a single literal:
+
+```bash
+grep -rn "GenAI Semantic Conventions v" src/Libraries/Microsoft.Extensions.AI/
 ```
+
+## Provider-specific instrumentation
+
+The new conventions repo also covers provider-specific areas (`openai`,
+`anthropic`, `aws-bedrock`, `azure-ai-inference`). Provider-specific
+attributes like `openai.*` belong in the **provider package**, not in
+`Microsoft.Extensions.AI`:
+
+| Upstream area | dotnet/extensions location |
+|---|---|
+| `openai` | `src/Libraries/Microsoft.Extensions.AI.OpenAI/` (e.g. `OpenAIClientExtensions.cs` for `openai.api.type` mapping) |
+| `anthropic` | Out of scope for `dotnet/extensions` today — implications land in [`anthropics/anthropic-sdk-csharp`](https://github.com/anthropics/anthropic-sdk-csharp). See [SKILL.md §Cross-repo applicability](../SKILL.md#cross-repo-applicability). |
+| `aws-bedrock` | Out of scope for `dotnet/extensions` today — implications land in the `BedrockRuntime` service library of [`aws/aws-sdk-net`](https://github.com/aws/aws-sdk-net). See [SKILL.md §Cross-repo applicability](../SKILL.md#cross-repo-applicability). |
+| `azure-ai-inference` | Corresponding provider package, if/when one exists in this repo; otherwise out of scope |
+| `mcp` | No instrumentation today — flag as a watch-list item if MCP changes appear |
+
+Tests for provider-specific attributes live alongside the provider package
+(e.g. `test/Libraries/Microsoft.Extensions.AI.OpenAI.Tests/`).
@@ -1,8 +1,15 @@
 # Historical Releases
 
-Mapping of OpenTelemetry semantic-conventions releases with gen-ai changes to dotnet/extensions PRs.
+Mapping of OpenTelemetry GenAI semantic-conventions releases to dotnet/extensions PRs.
 
-> **Note**: This file is a point-in-time reference and is not intended to be kept up to date with every new release. It provides context for how past convention updates were handled. For the latest release history, consult the [semantic-conventions releases page](https://github.com/open-telemetry/semantic-conventions/releases) and search the dotnet/extensions PR history.
+> **Migration Note**: Every entry in the tables below is from the **old** [`open-telemetry/semantic-conventions`](https://github.com/open-telemetry/semantic-conventions) repo (pre-migration era), where GenAI conventions were tagged with `area:gen-ai`. GenAI conventions have since moved to a dedicated repo: [`open-telemetry/semantic-conventions-genai`](https://github.com/open-telemetry/semantic-conventions-genai). See [SKILL.md §Migration Note](../SKILL.md#migration-note) for the full picture.
+>
+> **Point-in-time reference**: This file is not intended to be kept up to date with every new release. It provides context for how past convention updates were handled. For current activity, consult:
+>
+> - The new repo's [`CHANGELOG.md`](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/CHANGELOG.md) (`Unreleased` section is the live "what's new" view until releases land).
+> - The new repo's [releases page](https://github.com/open-telemetry/semantic-conventions-genai/releases) (empty as of this writing).
+> - The new repo's [pull request history](https://github.com/open-telemetry/semantic-conventions-genai/pulls?q=is%3Apr).
+> - The dotnet/extensions PR history.
 
 ## Release History
 

@@ -4,6 +4,19 @@ Code patterns for common convention update change types. Use these as templates
 
 > **Reuse before adding.** Before applying any of the patterns below, search the touched libraries (`Common/`, `TelemetryHelpers.cs`, `OpenTelemetryLog.cs`, and sibling OpenTelemetry* client files) for an existing helper, method, or internal type that already does the same thing. Reuse or extend it instead of adding a parallel implementation. If the same logic will be needed in two or more places, factor it into `Common/` from the start rather than duplicating it per file. The same rule applies to parallel internal types — when a sibling client already defines a type with the same shape, unify under a single shared definition. See [review-checklist.md §3](review-checklist.md#3-code-deduplication) for what reviewers look for.
 
+## Area placement guidance
+
+The new conventions repo ([`open-telemetry/semantic-conventions-genai`](https://github.com/open-telemetry/semantic-conventions-genai)) hosts multiple areas. Pick the right dotnet/extensions location based on the upstream `model/<area>/` path of the change:
+
+| Upstream area | dotnet/extensions location | Notes |
+|---|---|---|
+| `gen-ai`, `gen-ai/agent` | `src/Libraries/Microsoft.Extensions.AI/` (e.g. `OpenTelemetryChatClient.cs`, `OpenTelemetryConsts.cs` under `GenAI.*`) | Generic gen-ai instrumentation — the bulk of historical work. |
+| `mcp` | No instrumentation today — forward-looking | If MCP changes appear, classify as 🟢 *No client exists* and flag for follow-up. Do not add `MCP.*` constants speculatively. |
+| `openai` | `src/Libraries/Microsoft.Extensions.AI.OpenAI/` (e.g. `OpenAIClientExtensions.cs` for `openai.api.type` mapping). Tests in `test/Libraries/Microsoft.Extensions.AI.OpenAI.Tests/`. | Keep `OpenTelemetryChatClient` provider-agnostic; provider-specific attributes belong in the provider package. |
+| `anthropic` | Out of scope for `dotnet/extensions` today. Implications land in [`anthropics/anthropic-sdk-csharp`](https://github.com/anthropics/anthropic-sdk-csharp). | If you're using this skill in that repo, follow the target repo's own constants/file layout. See [SKILL.md §Cross-repo applicability](../SKILL.md#cross-repo-applicability). |
+| `aws-bedrock` | Out of scope for `dotnet/extensions` today. Implications land in the `BedrockRuntime` service library of [`aws/aws-sdk-net`](https://github.com/aws/aws-sdk-net). | If you're using this skill in that repo, follow the target repo's own constants/file layout. See [SKILL.md §Cross-repo applicability](../SKILL.md#cross-repo-applicability). |
+| `azure-ai-inference` | Corresponding provider package, if/when one exists in this repo | Currently no provider package for this in this repo — classify as 🟢 *No client exists* until one is added. |
+
 ## Pattern 1: Adding a New Constant
 
 Location: `src/Libraries/Microsoft.Extensions.AI/OpenTelemetryConsts.cs`
@@ -129,18 +142,32 @@ if (_logger is not null)
 
 ## Pattern 6: Updating Version References
 
-When bumping the convention version (e.g. v1.39 → v1.40), update the doc comment in all matched OpenTelemetry* client files:
+When bumping the convention version (e.g. an upcoming GenAI version bump), update the doc comment in all matched OpenTelemetry* client files. The wording is in the middle of a one-time migration to reflect the standalone GenAI repo — see [file-inventory.md §Version References](file-inventory.md#version-references) for full guidance.
+
+**Pre-migration wording** (carried over from when conventions lived in core `semantic-conventions`):
 
 ```csharp
-// Before:
 /// Semantic Conventions for Generative AI systems v1.39,
-// After:
-/// Semantic Conventions for Generative AI systems v1.40,
 ```
 
-Find all occurrences:
+**Target wording** (after migration to the standalone repo, with GenAI-namespaced version matching the schema URL `opentelemetry.io/schemas/gen-ai/X.Y.Z`):
+
+```csharp
+/// GenAI Semantic Conventions v1.42.0,
+```
+
+The next convention-update PR should migrate every matched file from the pre-migration wording to the target wording in one shot. Do not leave files in a half-migrated state.
+
+Find all occurrences using a regex that matches both wordings during the transition:
+
+```bash
+grep -rEn "Semantic Conventions for Generative AI systems v|GenAI Semantic Conventions v" src/Libraries/Microsoft.Extensions.AI/
+```
+
+After the migration is complete, simplify to:
+
 ```bash
-grep -rn "Semantic Conventions for Generative AI systems v" src/Libraries/Microsoft.Extensions.AI/
+grep -rn "GenAI Semantic Conventions v" src/Libraries/Microsoft.Extensions.AI/
 ```
 
 ## Pattern 7: Modifying Message Serialization