@ancplua/qyl-api-schema 0.2.3 → 0.3.0

package/README.md

@@ -14,7 +14,7 @@ open-telemetry/semantic-conventions @ v1.43.0  +  semantic-conventions-genai (de
         | Weaver (Qyl.OpenTelemetry.SemanticConventions repo:
         |   generate.sh -> resolved-registry.json -> emit_typespec_keys.py)
         v
-generated/otel-keys.gen.tsp  (+ generated/otel-keys-legacy.tsp, hand-frozen wire keys)
+generated/otel-keys.gen.tsp
         |
         | TypeSpec import / lockstep key projection
         v
@@ -31,8 +31,7 @@ qyl services, dashboard, tools, and generated clients
 The generic OpenTelemetry key projection is the checked-in
 `generated/otel-keys.gen.tsp` under
 `ANcpLua.OpenTelemetry.SemanticConventions.Keys.*`, regenerated by the
-`Qyl.OpenTelemetry.SemanticConventions` repo's Weaver pipeline (the retired
-`@ancplua/typespec-otel-semconv@1.41.0-2` package was its frozen predecessor).
+`Qyl.OpenTelemetry.SemanticConventions` repo's Weaver pipeline.
 This repo defines qyl domain models, routes, and response contracts under
 `Qyl.Api.Contracts.*`.
 

package/VERSIONING.md

@@ -40,14 +40,6 @@ enum GenAiVersions {
 }
 
 model GenAiSpanAttributes {
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.System)
-  @removed(GenAiVersions.v1_37)
-  system?: string;
-
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.UsagePromptTokens)
-  @removed(GenAiVersions.v1_28)
-  usagePromptTokens?: TokenCount;
-
   @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.UsageInputTokens)
   usageInputTokens?: TokenCount;
 
@@ -57,6 +49,14 @@ model GenAiSpanAttributes {
 }
 ```
 
+Note (v0.3.0): the pre-migration `gen_ai.*` fields that carried upstream-deleted
+wire keys (`gen_ai.system`, `gen_ai.prompt`, `gen_ai.completion`,
+`gen_ai.usage.prompt_tokens` / `.completion_tokens`, and the
+`gen_ai.openai.*` vendor keys) were **removed from the contract surface**
+when the OTel 1.42 GenAI-registry split was adopted. Old-key telemetry is a
+collector *ingestion normalization* concern (mapping below), not a contract
+field.
+
 ## Ingestion mapping (deprecated -> current)
 
 Consumers can keep ingestion backward-compatible by normalizing deprecated attribute keys. Keep any downstream mapping aligned with the TypeSpec history.

package/common/types.tsp

@@ -2,7 +2,8 @@
 // qyl common types and scalars
 // =============================================================================
 // Foundational types used across qyl API contracts and OTel-compatible models.
-// OpenTelemetry semantic-convention references are pinned to v1.41.0.
+// OpenTelemetry semantic-convention references are pinned to core v1.43.0
+// (GenAI keys come from the dedicated GenAI registry since the 1.42 split).
 // =============================================================================
 
 import "@typespec/versioning";
@@ -42,8 +43,14 @@ enum OTelVersion {
   @doc("OTel Semconv v1.40 - Oracle DB split, RPC cleanup, GenAI cache tokens")
   v1_40: "1.40.0",
 
-  @doc("OTel Semconv v1.41 - Current compatibility pin")
+  @doc("OTel Semconv v1.41 - GraphQL doc opt-in, RPC server client.* removal")
   v1_41: "1.41.0",
+
+  @doc("OTel Semconv v1.42 - GenAI conventions moved to the dedicated GenAI registry; k8s/container registry attrs stable")
+  v1_42: "1.42.0",
+
+  @doc("OTel Semconv v1.43 - Current compatibility pin (core; GenAI keys from the GenAI dev registry)")
+  v1_43: "1.43.0",
 }
 
 // =============================================================================

package/generated/README.md

@@ -2,31 +2,23 @@
 
 This directory holds the semconv TypeSpec key projection and the emitter
 outputs. `otel-keys.gen.tsp` is Weaver-generated — **do not edit by hand**.
-`otel-keys-legacy.tsp` is the one deliberate exception: hand-maintained,
-see below.
 
 ## Files
 
 | File | Source | Regenerate via |
 | --- | --- | --- |
 | `otel-keys.gen.tsp` | OpenTelemetry semantic-conventions core **v1.43.0** + the GenAI dev registry (`open-telemetry/semantic-conventions-genai`, pinned commit), merged and projected by the `Qyl.OpenTelemetry.SemanticConventions` repo's Weaver pipeline | In that repo: `src/…SourceGeneration/scripts/generate.sh` (refresh `Resources/resolved-registry.json`), then `src/…SourceGeneration/scripts/emit_typespec_keys.py --write <path-to-this-file>` |
-| `otel-keys-legacy.tsp` | Hand-maintained. Frozen legacy wire keys (10 `gen_ai.*` consts) that upstream deleted at the 1.41→1.43 bump but that qyl's published contracts still carry on deprecated migration fields. Values are verbatim from the last registry that defined them (v1.41.0). | Never regenerated. Delete a const here only if upstream re-introduces the same name (the `VerifyKeysLockstep` Nuke target and the TypeSpec duplicate-declaration error both catch that). |
-
-The predecessor projection was the npm package
-[`@ancplua/typespec-otel-semconv@1.41.0-2`](https://github.com/ANcpLua/typespec-otel-semconv)
-— its source repo is archived/deleted, so 1.41.0-2 was its last possible
-release; it is no longer a dependency of this repo.
 
 ## What the key files provide
 
 One TypeSpec namespace per OpenTelemetry root group, each declaring `const <Name>: string = "<dotted.key>"`. Extracted `.tsp` models reference these consts inside `@encodedName(...)` instead of hand-typing dotted attribute keys.
 
 ```tsp
-@encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.System)
-system?: string;
+@encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.ProviderName)
+providerName?: string;
 ```
 
-Deprecated upstream attributes are emitted with `#deprecated "..."` so models that reference them produce a TypeSpec compiler warning matching upstream's own deprecation notes. The legacy file's consts are all `#deprecated` by construction.
+Deprecated upstream attributes are emitted with `#deprecated "..."` so models that reference them produce a TypeSpec compiler warning matching upstream's own deprecation notes.
 
 ## Pin
 

package/index.tsp

@@ -19,7 +19,6 @@ import "@typespec/sse";
 import "@typespec/events";
 
 import "./generated/otel-keys.gen.tsp";
-import "./generated/otel-keys-legacy.tsp";
 
 import "./common/types.tsp";
 import "./common/errors.tsp";

package/models/genai.tsp

@@ -60,11 +60,6 @@ model GenAiSpanAttributes {
   @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.ProviderName)
   providerName: GenAiProvider;
 
-  @doc("The name of the GenAI system/product (e.g., 'ChatGPT', 'Claude', 'Gemini')")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.System)
-  @removed(GenAiVersions.v1_37)
-  system?: string;
-
   // ---------------------------------------------------------------------------
   // Operation Details
   // ---------------------------------------------------------------------------
@@ -184,20 +179,6 @@ model GenAiSpanAttributes {
   @added(GenAiVersions.v1_40)
   usageCacheCreationInputTokens?: TokenCount;
 
-  // ---------------------------------------------------------------------------
-  // Deprecated Attributes (for migration)
-  // ---------------------------------------------------------------------------
-
-  @doc("Prompt tokens (deprecated - use gen_ai.usage.input_tokens)")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.UsagePromptTokens)
-  @removed(GenAiVersions.v1_28)
-  usagePromptTokens?: TokenCount;
-
-  @doc("Completion tokens (deprecated - use gen_ai.usage.output_tokens)")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.UsageCompletionTokens)
-  @removed(GenAiVersions.v1_28)
-  usageCompletionTokens?: TokenCount;
-
   // ---------------------------------------------------------------------------
   // Agent Attributes (v1.38+)
   // ---------------------------------------------------------------------------
@@ -294,10 +275,6 @@ model GenAiSpanAttributes {
   @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.OutputType)
   outputType?: GenAiOutputType;
 
-  @doc("Prompt content (may be redacted)")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.Prompt)
-  prompt?: string;
-
   @doc("Name of the prompt template being used")
   @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.PromptName)
   promptName?: string;
@@ -306,10 +283,6 @@ model GenAiSpanAttributes {
   @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.SystemInstructions)
   systemInstructions?: string;
 
-  @doc("Completion content (may be redacted)")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.Completion)
-  completion?: string;
-
   // ---------------------------------------------------------------------------
   // Extended Request Attributes
   // ---------------------------------------------------------------------------
@@ -1329,40 +1302,21 @@ model LatencyPercentiles {
 // Vendor-Specific Extensions (OTel 1.40)
 // =============================================================================
 
-@doc("OpenAI-specific request attributes")
+@doc("OpenAI-specific request attributes (OTel 1.42 moved these to the openai.* namespace; response_format and seed graduated to the generic gen_ai.output.type / gen_ai.request.seed)")
 model OpenAiRequestAttributes {
-  @doc("Response format requested (text, json_object, json_schema)")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.OpenaiRequestResponseFormat)
-  responseFormat?: OpenAiResponseFormat;
-
-  @doc("Random seed for deterministic generation")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.OpenaiRequestSeed)
-  seed?: int64;
-
   @doc("Service tier for the request (auto, default, etc.)")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.OpenaiRequestServiceTier)
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Openai.RequestServiceTier)
   serviceTier?: string;
 }
 
 @doc("OpenAI-specific response attributes")
 model OpenAiResponseAttributes {
   @doc("Service tier used for the response")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.OpenaiResponseServiceTier)
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Openai.ResponseServiceTier)
   serviceTier?: string;
 
   @doc("System fingerprint for reproducibility")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.OpenaiResponseSystemFingerprint)
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Openai.ResponseSystemFingerprint)
   systemFingerprint?: string;
 }
 
-@doc("OpenAI response format types")
-enum OpenAiResponseFormat {
-  @doc("Plain text response")
-  text: "text",
-
-  @doc("JSON object response")
-  jsonObject: "json_object",
-
-  @doc("JSON schema-constrained response")
-  jsonSchema: "json_schema",
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancplua/qyl-api-schema",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "TypeSpec source of truth for qyl API contracts. Emits OpenAPI, JSON Schema, Qyl.Api.Contracts DTOs, and TypeScript contract types; not an OpenTelemetry package, storage schema, or server implementation.",
   "license": "Apache-2.0",
   "repository": {

package/generated/otel-keys-legacy.tsp

@@ -1,51 +0,0 @@
-// Hand-maintained companion to otel-keys.gen.tsp — NOT generated. Frozen legacy
-// wire keys that upstream removed from the registries at the 1.41→1.43 bump
-// (the GenAI split: gen_ai.system/prompt/completion/usage.{prompt,completion}_tokens
-// were dropped outright; of the gen_ai.openai.* vendor keys, service_tier ×2 and
-// response.system_fingerprint were renamed to openai.*, seed and
-// request.response_format were removed with no successor).
-//
-// qyl's public contracts still carry these dotted keys on deliberately-deprecated
-// migration fields (`@removed(GenAiVersions.…)` in models/genai.tsp). A wire name
-// is a published contract: it stays frozen even after upstream deletes the key.
-// The values below are verbatim from the last registry that defined them
-// (open-telemetry/semantic-conventions v1.41.0, via the retired
-// @ancplua/typespec-otel-semconv@1.41.0-2 projection).
-//
-// TypeSpec merges namespaces across files, so these consts land in the same
-// Keys.GenAi namespace the generated file populates — consuming models did not
-// change. If a future regeneration re-introduces one of these names, the
-// compiler will error on the duplicate: resolve by deleting it HERE.
-
-namespace ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi {
-  /** Frozen legacy wire key; removed from semconv (replaced by gen_ai.output.messages). */
-  #deprecated "Removed upstream; frozen for contract compatibility."
-  const Completion: string = "gen_ai.completion";
-  /** Frozen legacy wire key; removed from semconv (no openai.* successor at 1.43). */
-  #deprecated "Removed upstream; frozen for contract compatibility."
-  const OpenaiRequestResponseFormat: string = "gen_ai.openai.request.response_format";
-  /** Frozen legacy wire key; removed from semconv (no openai.* successor at 1.43). */
-  #deprecated "Removed upstream; frozen for contract compatibility."
-  const OpenaiRequestSeed: string = "gen_ai.openai.request.seed";
-  /** Frozen legacy wire key; renamed upstream to openai.request.service_tier. */
-  #deprecated "Renamed upstream to openai.request.service_tier; frozen for contract compatibility."
-  const OpenaiRequestServiceTier: string = "gen_ai.openai.request.service_tier";
-  /** Frozen legacy wire key; renamed upstream to openai.response.service_tier. */
-  #deprecated "Renamed upstream to openai.response.service_tier; frozen for contract compatibility."
-  const OpenaiResponseServiceTier: string = "gen_ai.openai.response.service_tier";
-  /** Frozen legacy wire key; renamed upstream to openai.response.system_fingerprint. */
-  #deprecated "Renamed upstream to openai.response.system_fingerprint; frozen for contract compatibility."
-  const OpenaiResponseSystemFingerprint: string = "gen_ai.openai.response.system_fingerprint";
-  /** Frozen legacy wire key; removed from semconv (replaced by gen_ai.input.messages). */
-  #deprecated "Removed upstream; frozen for contract compatibility."
-  const Prompt: string = "gen_ai.prompt";
-  /** Frozen legacy wire key; removed from semconv (replaced by gen_ai.provider.name). */
-  #deprecated "Replaced by gen_ai.provider.name; frozen for contract compatibility."
-  const System: string = "gen_ai.system";
-  /** Frozen legacy wire key; removed from semconv (replaced by gen_ai.usage.output_tokens). */
-  #deprecated "Replaced by gen_ai.usage.output_tokens; frozen for contract compatibility."
-  const UsageCompletionTokens: string = "gen_ai.usage.completion_tokens";
-  /** Frozen legacy wire key; removed from semconv (replaced by gen_ai.usage.input_tokens). */
-  #deprecated "Replaced by gen_ai.usage.input_tokens; frozen for contract compatibility."
-  const UsagePromptTokens: string = "gen_ai.usage.prompt_tokens";
-}