Upgrade Weaver to v0.22.1 and migrate schemas to v2 format

- Bump otel/weaver Docker image from v0.21.2 to v0.22.1
- Rename registry_manifest.yaml to manifest.yaml (v0.22 deprecation)
- Migrate attribute files to v2 schema (file_format: definition/2)
- Migrate service files to v2 attribute_groups with visibility
- Update jq filters in weaver.yaml for new resolved registry ID format
- Fix readme.md.j2 to reflect actual schema file structure
- Add TELEMETRY_DOCS_HOST/PORT env vars to docker-compose.minimal.yml
- Update mkdocs site_url to localhost:8080/telemetry/

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: martinjt

docker-compose.minimal.yml

@@ -290,6 +290,8 @@ services:
       - FLAGD_PORT
       - FLAGD_UI_HOST
       - FLAGD_UI_PORT
+      - TELEMETRY_DOCS_HOST
+      - TELEMETRY_DOCS_PORT
     depends_on:
       frontend:
         condition: service_started

src/telemetry-docs/Dockerfile

@@ -4,7 +4,7 @@
 # Two-stage build: Generate service-centric Markdown with Weaver, then serve with mkdocs
 
 # Stage 1: Generate Markdown files from telemetry schema using Weaver
-FROM docker.io/otel/weaver:v0.21.2 AS registry-builder
+FROM docker.io/otel/weaver:v0.22.1 AS registry-builder
 
 WORKDIR /workspace
 

src/telemetry-docs/mkdocs.yml

@@ -4,7 +4,7 @@
 site_name: OpenTelemetry Demo Telemetry Schema
 site_description: Semantic conventions and telemetry schema for the OpenTelemetry Demo application
 site_author: OpenTelemetry Demo Contributors
-site_url: https://opentelemetry-demo.example.com/telemetry/
+site_url: http://localhost:8080/telemetry/
 
 theme:
   name: material

src/telemetry-docs/templates/markdown/readme.md.j2

@@ -20,17 +20,17 @@ The demo application consists of multiple microservices, each with its own telem
 
 The telemetry schema is organized by:
 
-1. **Logical Attribute Groups** - Semantic domain-focused attribute definitions in `common.yaml`
-2. **Service Registries** - Service-specific attribute and metric definitions
+1. **Logical Attribute Groups** - Semantic domain-focused attribute definitions (product, user, order, shipping, misc)
+2. **Service Definitions** - Service-specific attribute references and metric definitions
 
 Each service references logical attribute groups using the `ref` syntax, creating a separation between logical groupings and service-specific usage patterns.
 
 ## Schema Files
 
-- `telemetry-schema/registry_manifest.yaml` - Registry metadata
-- `telemetry-schema/attributes/common.yaml` - Logical attribute group definitions
-- `telemetry-schema/attributes/{service}.yaml` - Service-specific attribute registries
-- `telemetry-schema/metrics/{service}.yaml` - Service-specific metric definitions
+- `telemetry-schema/manifest.yaml` - Registry metadata
+- `telemetry-schema/attributes/*.yaml` - Logical attribute group definitions by domain
+- `telemetry-schema/services/*.yaml` - Service-specific attribute references
+- `telemetry-schema/metrics/*.yaml` - Service-specific metric definitions
 
 ## Getting Started
 

src/telemetry-docs/templates/markdown/registry.md.j2

@@ -11,7 +11,9 @@
 # {{ ctx.id | replace("_", " ") | title }} Attributes
 
 {% for group in ctx.groups | sort(attribute="id") %}
+{%- if group.brief and not group.brief.startswith("<synthetic") %}
 {{ group.brief }}
+{%- endif %}
 
 ## Quick Reference
 

src/telemetry-docs/templates/markdown/weaver.yaml

@@ -23,7 +23,7 @@ templates:
   - pattern: mkdocs_nav.yml.j2
     filter: >
       {
-        registries: [.groups[] | select(.type == "attribute_group" and (.id | startswith("registry."))) | {name: (.id | split(".") | .[1]), id: .id}] | unique_by(.name) | sort_by(.name),
+        registries: [.groups[] | select(.type == "attribute_group" and (.id | startswith("registry."))) | {name: (.id | split(".") | last), id: .id}] | unique_by(.name) | sort_by(.name),
         services: ([.groups[] | select(.type == "attribute_group" and (.id | startswith("service."))) | {name: (.id | split(".")| .[1])}] + [.groups[] |
           select(.type == "metric" and (.id | startswith("metric."))) | {name: (.id | split(".")[1])}]) | unique_by(.name) | sort_by(.name)
       }
@@ -61,8 +61,8 @@ templates:
       .groups
       | map(select(.type == "attribute_group"))
       | map(select(.id | startswith("registry.")))
-      | group_by(.id | split(".") | .[1])
-      | map({id: .[0].id | split(".") | .[1], groups: .})
+      | group_by(.id | split(".") | last)
+      | map({id: .[0].id | split(".") | last, groups: .})
     application_mode: each
     file_name: attributes/{{ ctx.id | snake_case }}.md
 

telemetry-schema/attributes/misc.yaml

@@ -1,46 +1,42 @@
 # Copyright The OpenTelemetry Authors
 # SPDX-License-Identifier: Apache-2.0
 
-groups:
-  - id: registry.misc
-    type: attribute_group
-    brief: Miscellaneous cross-cutting attributes
+file_format: definition/2
+attributes:
+  - key: app.synthetic_request
+    type: string
+    brief: Whether the request is synthetic/test traffic
     stability: stable
-    attributes:
-      - id: app.synthetic_request
-        type: string
-        brief: Whether the request is synthetic/test traffic
-        stability: stable
-        note: >
-          Indicates whether the request is synthetic traffic generated for testing or monitoring purposes ("true") or real user traffic.
-          This helps distinguish production traffic from test traffic in observability systems.
-          Also propagated as synthetic_request baggage.
-        examples: ["true", "false"]
-      - id: app.recommendation.cache_enabled
-        type: boolean
-        brief: Whether recommendation caching is enabled
-        stability: stable
-        note: Indicates whether the recommendation service has caching enabled for this request (feature flag)
-      - id: app.cache_hit
-        type: boolean
-        brief: Whether the recommendation cache was hit
-        stability: stable
-        note: Indicates whether the recommendation was served from cache (true) or computed fresh (false)
-      - id: app.email.recipient
-        type: string
-        brief: Email recipient address
-        stability: stable
-        note: The email address of the recipient for whom the email is being sent. This is typically used for order confirmation emails and other transactional communications.
-        examples: ["customer@example.com", "user@domain.org"]
-      - id: app.currency.conversion.from
-        type: string
-        brief: Source currency code
-        stability: stable
-        note: The currency code being converted from
-        examples: ["USD", "EUR", "GBP"]
-      - id: app.currency.conversion.to
-        type: string
-        brief: Target currency code
-        stability: stable
-        note: The currency code being converted to
-        examples: ["USD", "EUR", "JPY"]
+    note: >
+      Indicates whether the request is synthetic traffic generated for testing or monitoring purposes ("true") or real user traffic.
+      This helps distinguish production traffic from test traffic in observability systems.
+      Also propagated as synthetic_request baggage.
+    examples: ["true", "false"]
+  - key: app.recommendation.cache_enabled
+    type: boolean
+    brief: Whether recommendation caching is enabled
+    stability: stable
+    note: Indicates whether the recommendation service has caching enabled for this request (feature flag)
+  - key: app.cache_hit
+    type: boolean
+    brief: Whether the recommendation cache was hit
+    stability: stable
+    note: Indicates whether the recommendation was served from cache (true) or computed fresh (false)
+  - key: app.email.recipient
+    type: string
+    brief: Email recipient address
+    stability: stable
+    note: The email address of the recipient for whom the email is being sent. This is typically used for order confirmation emails and other transactional communications.
+    examples: ["customer@example.com", "user@domain.org"]
+  - key: app.currency.conversion.from
+    type: string
+    brief: Source currency code
+    stability: stable
+    note: The currency code being converted from
+    examples: ["USD", "EUR", "GBP"]
+  - key: app.currency.conversion.to
+    type: string
+    brief: Target currency code
+    stability: stable
+    note: The currency code being converted to
+    examples: ["USD", "EUR", "JPY"]

telemetry-schema/attributes/order.yaml

@@ -1,61 +1,57 @@
 # Copyright The OpenTelemetry Authors
 # SPDX-License-Identifier: Apache-2.0
 
-groups:
-  - id: registry.order
-    type: attribute_group
-    brief: Order, cart, and payment-related attributes
-    stability: stable
-    attributes:
-      - id: app.order.id
-        type: string
-        brief: Order identifier
-        stability: stable
-        note: The unique identifier for an order
-        examples: ["order-123", "ORD-456789"]
-      - id: app.order.amount
-        type: double
-        brief: Total order amount
-        stability: stable
-        note: The total monetary amount of the order
-        examples: [99.99, 150.50]
-      - id: app.order.items.count
-        type: int
-        brief: Number of items in order
-        stability: stable
-        note: The count of distinct items in the order
-        examples: [1, 5, 10]
-      - id: app.cart.items.count
-        type: int
-        brief: Number of items in cart
-        stability: stable
-        note: The count of items currently in the shopping cart
-        examples: [0, 3, 7]
-      - id: app.payment.amount
-        type: string
-        brief: Payment amount
-        stability: stable
-        note: The monetary amount being charged
-        examples: ["29.99", "99.95", "150.00"]
-      - id: app.payment.card_type
-        type: string
-        brief: Credit card type
-        stability: stable
-        note: The type of credit card being used for payment
-        examples: ["visa", "mastercard", "amex"]
-      - id: app.payment.card_valid
-        type: boolean
-        brief: Card validation status
-        stability: stable
-        note: Whether the card passed validation checks
-      - id: app.payment.charged
-        type: boolean
-        brief: Whether payment was successfully charged
-        stability: stable
-        note: Indicates whether the payment transaction was successfully charged to the customer's payment method (true) or not charged (false). For synthetic requests, this is set to false.
-      - id: app.payment.transaction.id
-        type: string
-        brief: Payment transaction identifier
-        stability: stable
-        note: Unique identifier for the payment transaction
-        examples: ["txn-abc123", "PAY-456789"]
+file_format: definition/2
+attributes:
+  - key: app.order.id
+    type: string
+    brief: Order identifier
+    stability: stable
+    note: The unique identifier for an order
+    examples: ["order-123", "ORD-456789"]
+  - key: app.order.amount
+    type: double
+    brief: Total order amount
+    stability: stable
+    note: The total monetary amount of the order
+    examples: [99.99, 150.50]
+  - key: app.order.items.count
+    type: int
+    brief: Number of items in order
+    stability: stable
+    note: The count of distinct items in the order
+    examples: [1, 5, 10]
+  - key: app.cart.items.count
+    type: int
+    brief: Number of items in cart
+    stability: stable
+    note: The count of items currently in the shopping cart
+    examples: [0, 3, 7]
+  - key: app.payment.amount
+    type: string
+    brief: Payment amount
+    stability: stable
+    note: The monetary amount being charged
+    examples: ["29.99", "99.95", "150.00"]
+  - key: app.payment.card_type
+    type: string
+    brief: Credit card type
+    stability: stable
+    note: The type of credit card being used for payment
+    examples: ["visa", "mastercard", "amex"]
+  - key: app.payment.card_valid
+    type: boolean
+    brief: Card validation status
+    stability: stable
+    note: Whether the card passed validation checks
+  - key: app.payment.charged
+    type: boolean
+    brief: Whether payment was successfully charged
+    stability: stable
+    note: Indicates whether the payment transaction was successfully charged to the customer's payment method (true) or not charged (false). For synthetic requests, this is set to false.
+  - key: app.payment.transaction.id
+    type: string
+    brief: Payment transaction identifier
+    stability: stable
+    note: Unique identifier for the payment transaction
+    examples: ["txn-abc123", "PAY-456789"]