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
- Add Apache license headers to Jinja2 template files
- 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/

Note: Claude was used to assist with this change. The author has
verified all work.

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/attribute_macros.j2

@@ -1,3 +1,5 @@
+{#- Copyright The OpenTelemetry Authors -#}
+{#- SPDX-License-Identifier: Apache-2.0 -#}
 {#- Attribute macros for Weaver templates -#}
 
 {#- Renders the type of an attribute -#}

src/telemetry-docs/templates/markdown/mkdocs_nav.yml.j2

@@ -1,3 +1,5 @@
+{#- Copyright The OpenTelemetry Authors -#}
+{#- SPDX-License-Identifier: Apache-2.0 -#}
 {#- This template generates mkdocs.yml with dynamic navigation -#}
 {#- It inherits from mkdocs-base.yml for all static configuration -#}
 {#- Context: ctx.registries (list of {name}), ctx.services (list of {name}) -#}

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

@@ -1,3 +1,5 @@
+{#- Copyright The OpenTelemetry Authors -#}
+{#- SPDX-License-Identifier: Apache-2.0 -#}
 {#- Home page template - generates README.md for mkdocs -#}
 {#- Context: Full registry data from Weaver -#}
 
@@ -20,17 +22,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

@@ -1,3 +1,5 @@
+{#- Copyright The OpenTelemetry Authors -#}
+{#- SPDX-License-Identifier: Apache-2.0 -#}
 {#- This template is rendered per registry attribute group. -#}
 {#- Context variables provided by Weaver: -#}
 {#- - ctx.id: The registry id (e.g., "product", "user") -#}
@@ -11,7 +13,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/service.md.j2

@@ -1,3 +1,5 @@
+{#- Copyright The OpenTelemetry Authors -#}
+{#- SPDX-License-Identifier: Apache-2.0 -#}
 {#- This template is rendered per service registry namespace. -#}
 {#- Context variables provided by Weaver: -#}
 {#- - ctx.id: The service id (e.g., "recommendation") -#}

src/telemetry-docs/templates/markdown/stability.j2

@@ -1,3 +1,5 @@
+{#- Copyright The OpenTelemetry Authors -#}
+{#- SPDX-License-Identifier: Apache-2.0 -#}
 {#- Stability badge macros for Weaver templates -#}
 {% macro badge(stability, deprecated) -%}
 {%- if deprecated %}![Deprecated](https://img.shields.io/badge/-deprecated-red)

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