From e2d603790140a41ee37e1ed65c019c9bbf688de3 Mon Sep 17 00:00:00 2001
From: James Thompson <thompson.tomo@outlook.com>
Date: Wed, 16 Jul 2025 18:33:56 +1000
Subject: [PATCH 1/2] Introduce the ability to define namespaces #802

---
 crates/weaver_forge/src/registry.rs           | 12 ++++
 crates/weaver_resolved_schema/src/registry.rs | 22 +++++-
 crates/weaver_resolver/src/registry.rs        |  2 +
 crates/weaver_semconv/data/gen-ai.yaml        | 12 ++++
 crates/weaver_semconv/src/footer.rs           | 38 ++++++++++
 crates/weaver_semconv/src/group.rs            | 67 ++++++++++++++++--
 crates/weaver_semconv/src/header.rs           | 38 ++++++++++
 crates/weaver_semconv/src/lib.rs              |  3 +
 crates/weaver_semconv/src/registry.rs         |  4 ++
 crates/weaver_semconv/src/style.rs            | 69 +++++++++++++++++++
 src/registry/stats.rs                         |  3 +
 11 files changed, 265 insertions(+), 5 deletions(-)
 create mode 100644 crates/weaver_semconv/data/gen-ai.yaml
 create mode 100644 crates/weaver_semconv/src/footer.rs
 create mode 100644 crates/weaver_semconv/src/header.rs
 create mode 100644 crates/weaver_semconv/src/style.rs

diff --git a/crates/weaver_forge/src/registry.rs b/crates/weaver_forge/src/registry.rs
index f44ec30c..711a52a5 100644
--- a/crates/weaver_forge/src/registry.rs
+++ b/crates/weaver_forge/src/registry.rs
@@ -14,7 +14,9 @@ use weaver_resolved_schema::lineage::GroupLineage;
 use weaver_resolved_schema::registry::{Group, Registry};
 use weaver_semconv::any_value::AnyValueSpec;
 use weaver_semconv::deprecated::Deprecated;
+use weaver_semconv::footer::FooterSpec;
 use weaver_semconv::group::{GroupType, InstrumentSpec, SpanKindSpec};
+use weaver_semconv::header::HeaderSpec;
 use weaver_semconv::stability::Stability;
 use weaver_semconv::YamlValue;
 
@@ -116,6 +118,12 @@ pub struct ResolvedGroup {
     #[serde(default)]
     #[serde(skip_serializing_if = "Vec::is_empty")]
     pub entity_associations: Vec<String>,
+    /// Header for the namespace/page.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub header: Option<HeaderSpec>,
+    /// Footer for the namespace/page.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub footer: Option<FooterSpec>,
     /// Annotations for the group.
     #[serde(default)]
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -172,6 +180,8 @@ impl ResolvedGroup {
             lineage,
             display_name: group.display_name.clone(),
             body: group.body.clone(),
+            footer: group.footer.clone(),
+            header: group.header.clone(),
             entity_associations: group.entity_associations.clone(),
             annotations: group.annotations.clone(),
         })
@@ -233,6 +243,8 @@ impl ResolvedRegistry {
                     lineage,
                     display_name: group.display_name.clone(),
                     body: group.body.clone(),
+                    footer: group.footer.clone(),
+                    header: group.header.clone(),
                     entity_associations: group.entity_associations.clone(),
                     annotations: group.annotations.clone(),
                 }
diff --git a/crates/weaver_resolved_schema/src/registry.rs b/crates/weaver_resolved_schema/src/registry.rs
index 52eff43d..7547388a 100644
--- a/crates/weaver_resolved_schema/src/registry.rs
+++ b/crates/weaver_resolved_schema/src/registry.rs
@@ -13,10 +13,12 @@ use crate::catalog::Catalog;
 use crate::error::{handle_errors, Error};
 use crate::lineage::GroupLineage;
 use crate::registry::GroupStats::{
-    AttributeGroup, Entity, Event, Metric, MetricGroup, Scope, Span, Undefined,
+    AttributeGroup, Entity, Event, Metric, MetricGroup, Scope, Span, Undefined, NameSpace
 };
 use serde::{Deserialize, Serialize};
 use weaver_semconv::deprecated::Deprecated;
+use weaver_semconv::footer::FooterSpec;
+use weaver_semconv::header::HeaderSpec;
 use weaver_semconv::group::{GroupType, InstrumentSpec, SpanKindSpec};
 use weaver_semconv::provenance::Provenance;
 use weaver_semconv::stability::Stability;
@@ -127,6 +129,12 @@ pub struct Group {
     /// This fields is only used for event groups.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub body: Option<AnyValueSpec>,
+    /// Header for the namespace/page.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub header: Option<HeaderSpec>,
+    /// Footer for the namespace/page.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub footer: Option<FooterSpec>,
     /// Annotations for the group.
     #[serde(default)]
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -155,6 +163,7 @@ impl Group {
             GroupType::MetricGroup => None,
             GroupType::Entity => self.name.as_deref(),
             GroupType::Scope => None,
+            GroupType::NameSpace => self.name.as_deref(),
             GroupType::Undefined => None,
         }
     }
@@ -218,6 +227,11 @@ pub enum GroupStats {
         /// Common statistics for this type of group.
         common_stats: CommonGroupStats,
     },
+    /// Statistics for a namespace.
+    NameSpace {
+        /// Common statistics for this type of group.
+        common_stats: CommonGroupStats,
+    },
     /// Statistics for a span.
     Span {
         /// Common statistics for this type of group.
@@ -307,6 +321,9 @@ impl Registry {
                         GroupType::Scope => Scope {
                             common_stats: CommonGroupStats::default(),
                         },
+                        GroupType::NameSpace => NameSpace {
+                            common_stats: CommonGroupStats::default(),
+                        },
                         GroupType::Span => Span {
                             common_stats: CommonGroupStats::default(),
                             span_kind_breakdown: HashMap::new(),
@@ -359,6 +376,9 @@ impl Registry {
                     Scope { common_stats } => {
                         common_stats.update_stats(group);
                     }
+                    NameSpace { common_stats } => {
+                        common_stats.update_stats(group);
+                    }
                     Span {
                         common_stats,
                         span_kind_breakdown,
diff --git a/crates/weaver_resolver/src/registry.rs b/crates/weaver_resolver/src/registry.rs
index 8123bf6f..172041aa 100644
--- a/crates/weaver_resolver/src/registry.rs
+++ b/crates/weaver_resolver/src/registry.rs
@@ -397,6 +397,8 @@ fn group_from_spec(group: GroupSpecWithProvenance) -> UnresolvedGroup {
             lineage: Some(GroupLineage::new(group.provenance.clone())),
             display_name: group.spec.display_name,
             body: group.spec.body,
+            header: group.spec.header,
+            footer: group.spec.footer,
             annotations: group.spec.annotations,
             entity_associations: group.spec.entity_associations,
         },
diff --git a/crates/weaver_semconv/data/gen-ai.yaml b/crates/weaver_semconv/data/gen-ai.yaml
new file mode 100644
index 00000000..4030089f
--- /dev/null
+++ b/crates/weaver_semconv/data/gen-ai.yaml
@@ -0,0 +1,12 @@
+groups:
+  - id: namespace.gen-ai
+    type: namespace
+    name: gen-ai
+    note: This is a description of the gen ai namespace
+    brief: This is a summary of the gen ai namespace
+    header:
+      title: Migration strategy
+      content: To protect personl information the following document should be followed.
+      style: warning
+    footer:
+      content: Footer
\ No newline at end of file
diff --git a/crates/weaver_semconv/src/footer.rs b/crates/weaver_semconv/src/footer.rs
new file mode 100644
index 00000000..807308a2
--- /dev/null
+++ b/crates/weaver_semconv/src/footer.rs
@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//! Stability specification.
+
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+use crate::style::Style;
+
+/// A header specification
+#[derive(Serialize, Deserialize, Clone, Debug, Eq, PartialEq, JsonSchema)]
+#[serde(deny_unknown_fields)]
+pub struct FooterSpec {
+
+    /// The title of the footer.
+    pub title: Option<String>,
+    /// The content in the footer.
+    pub content: String,
+    /// The style of the footer.
+    pub style: Option<Style>,
+}
+
+impl FooterSpec {
+    /// returns the title of the footer
+    #[must_use]
+    fn title(&self) -> &Option<String> {
+        &self.title
+    }
+    /// returns the content of the footer
+    #[must_use]
+    fn content(&self) -> &String {
+        &self.content
+    }
+    /// returns the style of the footer
+    #[must_use]
+    fn style(&self) -> &Option<Style> {
+        &self.style
+    }
+}
diff --git a/crates/weaver_semconv/src/group.rs b/crates/weaver_semconv/src/group.rs
index 831e1b23..6547f31b 100644
--- a/crates/weaver_semconv/src/group.rs
+++ b/crates/weaver_semconv/src/group.rs
@@ -13,7 +13,9 @@ use std::fmt::{Display, Formatter};
 use crate::any_value::AnyValueSpec;
 use crate::attribute::{AttributeSpec, AttributeType, PrimitiveOrArrayTypeSpec};
 use crate::deprecated::Deprecated;
+use crate::footer::FooterSpec;
 use crate::group::InstrumentSpec::{Counter, Gauge, Histogram, UpDownCounter};
+use crate::header::HeaderSpec;
 use crate::provenance::Provenance;
 use crate::semconv::Imports;
 use crate::stability::Stability;
@@ -109,6 +111,12 @@ pub struct GroupSpec {
     /// Note: only valid if type is event
     #[serde(skip_serializing_if = "Option::is_none")]
     pub body: Option<AnyValueSpec>,
+    /// Header for the namespace/page.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub header: Option<HeaderSpec>,
+    /// Footer for the namespace/page.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub footer: Option<FooterSpec>,
     /// Annotations for the group.
     #[serde(default)]
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -137,8 +145,8 @@ impl GroupSpec {
             });
         }
 
-        // Field stability is required for all group types except attribute group.
-        if self.r#type != GroupType::AttributeGroup && self.stability.is_none() {
+        // Field stability is required for all group types except namespaces & attribute group.
+        if self.r#type != GroupType::AttributeGroup && self.r#type != GroupType::NameSpace && self.stability.is_none() {
             errors.push(Error::InvalidGroupStability {
                 path_or_url: path_or_url.to_owned(),
                 group_id: self.id.clone(),
@@ -159,9 +167,10 @@ impl GroupSpec {
         // Groups should only reference attributes once.
         validate_duplicate_attribute_ref(&mut errors, &self.attributes, &self.id, path_or_url);
 
-        // All types, except metric and event, must have extends or attributes or both.
+        // All types, except namespaces, metric and event, must have extends or attributes or both.
         if self.r#type != GroupType::Metric
             && self.r#type != GroupType::Event
+            && self.r#type != GroupType::NameSpace
             && self.extends.is_none()
             && self.attributes.is_empty()
         {
@@ -182,6 +191,7 @@ impl GroupSpec {
                         .to_owned(),
                 });
             }
+            // TODO: this should become a warning as span events are deprecated
             if !self.events.is_empty() {
                 errors.push(Error::InvalidGroup {
                     path_or_url: path_or_url.to_owned(),
@@ -545,7 +555,7 @@ fn validate_any_value(
     }
 }
 
-/// The different types of groups: `attribute_group`, `span`, `event`, `metric`, `entity`, `scope`.
+/// The different types of groups: `attribute_group`, `span`, `event`, `metric`, `entity`, `scope`, `namespace`.
 ///
 /// Note: The `resource` type is no longer used and is an alias for `entity`.
 #[derive(Serialize, Deserialize, Debug, Eq, PartialEq, Hash, Clone, JsonSchema)]
@@ -572,6 +582,8 @@ pub enum GroupType {
     Scope,
     /// Undefined group type.
     Undefined,
+    /// Namespace semantic convention.
+    NameSpace,
 }
 
 impl Default for GroupType {
@@ -697,6 +709,8 @@ mod tests {
             name: None,
             display_name: None,
             body: None,
+            header: None,
+            footer: None,
             annotations: None,
             entity_associations: Vec::new(),
         };
@@ -862,6 +876,8 @@ mod tests {
             name: None,
             display_name: None,
             body: None,
+            header: None,
+            footer: None,
             annotations: None,
             entity_associations: Vec::new(),
         };
@@ -1159,6 +1175,8 @@ mod tests {
                     ),
                 },
             }),
+            header: None,
+            footer: None,
             annotations: None,
             entity_associations: Vec::new(),
         };
@@ -1374,6 +1392,8 @@ mod tests {
                     ),
                 },
             }),
+            header: None,
+            footer: None,
             annotations: None,
             entity_associations: Vec::new(),
         };
@@ -1518,6 +1538,8 @@ mod tests {
             name: None,
             display_name: None,
             body: None,
+            header: None,
+            footer: None,
             annotations: None,
             entity_associations: Vec::new(),
         };
@@ -1688,6 +1710,8 @@ mod tests {
             name: None,
             display_name: None,
             body: None,
+            header: None,
+            footer: None,
             annotations: None,
             entity_associations: Vec::new(),
         };
@@ -1840,6 +1864,8 @@ mod tests {
             name: None,
             display_name: None,
             body: None,
+            header: None,
+            footer: None,
             annotations: None,
             entity_associations: Vec::new(),
         };
@@ -1900,6 +1926,8 @@ mod tests {
             name: None,
             display_name: None,
             body: None,
+            header: None,
+            footer: None,
             annotations: None,
             entity_associations: vec!["test".to_owned()],
         };
@@ -1938,4 +1966,35 @@ mod tests {
             result
         );
     }
+
+    #[test]
+    fn test_validate_namespace(){
+        let mut group = GroupSpec {
+            id: "test".to_owned(),
+            r#type: GroupType::NameSpace,
+            name: Some("test_namespace".to_owned()),
+            brief: "test".to_owned(),
+            note: "test".to_owned(),
+            prefix: "".to_owned(),
+            extends: None,
+            stability: None,
+            deprecated: None,
+            span_kind: None,
+            events: vec![],
+            metric_name: None,
+            instrument: None,
+            unit: None,
+            display_name: None,
+            attributes: vec![],
+            body: None,
+            header: None,
+            footer: None,
+            annotations: None,
+            entity_associations: Vec::new(),
+        };
+        assert!(group
+            .validate("<test>")
+            .into_result_failing_non_fatal()
+            .is_ok());
+    }
 }
diff --git a/crates/weaver_semconv/src/header.rs b/crates/weaver_semconv/src/header.rs
new file mode 100644
index 00000000..1ea38aa0
--- /dev/null
+++ b/crates/weaver_semconv/src/header.rs
@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//! Stability specification.
+
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+use crate::style::Style;
+
+/// A header specification
+#[derive(Serialize, Deserialize, Clone, Debug, Eq, PartialEq, JsonSchema)]
+#[serde(deny_unknown_fields)]
+pub struct HeaderSpec {
+
+    /// The title of the header.
+    pub title: Option<String>,
+    /// The content in the header.
+    pub content: String,
+    /// The style of the header.
+    pub style: Style,
+}
+
+impl HeaderSpec {
+    /// returns the title of the header
+    #[must_use]
+    fn title(&self) -> &Option<String> {
+        &self.title
+    }
+    /// returns the content of the header
+    #[must_use]
+    fn content(&self) -> &String {
+        &self.content
+    }
+    /// returns the style of the header
+    #[must_use]
+    fn style(&self) -> &Style {
+        &self.style
+    }
+}
diff --git a/crates/weaver_semconv/src/lib.rs b/crates/weaver_semconv/src/lib.rs
index 37b7c9ca..51cbda96 100644
--- a/crates/weaver_semconv/src/lib.rs
+++ b/crates/weaver_semconv/src/lib.rs
@@ -16,7 +16,9 @@ use weaver_common::error::{format_errors, WeaverError};
 pub mod any_value;
 pub mod attribute;
 pub mod deprecated;
+pub mod footer;
 pub mod group;
+pub mod header;
 pub mod json_schema;
 pub mod manifest;
 pub mod metric;
@@ -26,6 +28,7 @@ pub mod registry_repo;
 pub mod semconv;
 pub mod stability;
 pub mod stats;
+pub mod style;
 
 /// An error that can occur while loading a semantic convention registry.
 #[derive(thiserror::Error, Debug, Clone, PartialEq, Serialize, Diagnostic)]
diff --git a/crates/weaver_semconv/src/registry.rs b/crates/weaver_semconv/src/registry.rs
index 9160b949..e590a06d 100644
--- a/crates/weaver_semconv/src/registry.rs
+++ b/crates/weaver_semconv/src/registry.rs
@@ -357,6 +357,8 @@ mod tests {
                         name: None,
                         display_name: Some("Group 1".to_owned()),
                         body: None,
+                        header: None,
+                        footer: None,
                         annotations: None,
                         entity_associations: Vec::new(),
                     }],
@@ -384,6 +386,8 @@ mod tests {
                         name: None,
                         display_name: Some("Group 2".to_owned()),
                         body: None,
+                        header: None,
+                        footer: None,
                         annotations: None,
                         entity_associations: Vec::new(),
                     }],
diff --git a/crates/weaver_semconv/src/style.rs b/crates/weaver_semconv/src/style.rs
new file mode 100644
index 00000000..2a66cb77
--- /dev/null
+++ b/crates/weaver_semconv/src/style.rs
@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//! Stability specification.
+
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+use std::fmt::{Display, Formatter};
+
+/// The level of stability for a definition. Defined in [OTEP-232](https://github.com/open-telemetry/oteps/blob/main/text/0232-maturity-of-otel.md)
+#[derive(Serialize, Deserialize, Clone, Debug, Eq, PartialEq, Hash, JsonSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum Style {
+    /// A note message.
+    Note,
+    /// A tip message.
+    Tip,
+    /// An Important message.
+    Important,
+    /// A Warning message.
+    Warning,
+    /// A Caution message.
+    Caution,
+}
+
+/// Implements a human readable display for the stability.
+impl Display for Style {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Style::Note => write!(f, "NOTE"),
+            Style::Tip => write!(f, "TIP"),
+            Style::Important => write!(f, "IMPORTANT"),
+            Style::Warning => write!(f, "WARNING"),
+            Style::Caution => write!(f, "CAUTION"),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json;
+
+    #[test]
+    fn test_deserialize_stability() {
+        let note: Style = serde_json::from_str("\"note\"").unwrap();
+        assert_eq!(note, Style::Note);
+
+        let tip: Style = serde_json::from_str("\"tip\"").unwrap();
+        assert_eq!(tip, Style::Tip);
+
+        let important: Style = serde_json::from_str("\"important\"").unwrap();
+        assert_eq!(important, Style::Important);
+
+        let warning: Style = serde_json::from_str("\"warning\"").unwrap();
+        assert_eq!(warning, Style::Warning);
+
+        let caution: Style = serde_json::from_str("\"caution\"").unwrap();
+        assert_eq!(caution, Style::Caution);
+    }
+
+    #[test]
+    fn test_display() {
+        assert_eq!(Style::Note.to_string(), "NOTE");
+        assert_eq!(Style::Tip.to_string(), "TIP");
+        assert_eq!(Style::Important.to_string(), "IMPORTANT");
+        assert_eq!(Style::Warning.to_string(), "WARNING");
+        assert_eq!(Style::Caution.to_string(), "CAUTION");
+    }
+}
diff --git a/src/registry/stats.rs b/src/registry/stats.rs
index 4d922c3c..94874e97 100644
--- a/src/registry/stats.rs
+++ b/src/registry/stats.rs
@@ -117,6 +117,9 @@ fn display_schema_stats(schema: &ResolvedTelemetrySchema) {
                     display_common_group_stats(group_type, common_stats);
                     total_number_of_attributes += common_stats.total_attribute_count;
                 }
+                GroupStats::NameSpace { common_stats } => {
+                    display_common_group_stats(group_type, common_stats);
+                }
                 GroupStats::Span {
                     common_stats,
                     span_kind_breakdown,

From 15f643609ee60158082e515c1f1b8444f89019a3 Mon Sep 17 00:00:00 2001
From: James Thompson <thompson.tomo@outlook.com>
Date: Sun, 3 Aug 2025 12:25:24 +1000
Subject: [PATCH 2/2] Update implementation for simplicity

---
 crates/weaver_emit/src/lib.rs                 |  9 +++
 crates/weaver_forge/src/registry.rs           | 14 ++--
 crates/weaver_live_check/src/live_checker.rs  |  6 ++
 crates/weaver_resolved_schema/src/registry.rs | 10 +--
 crates/weaver_resolver/src/registry.rs        |  3 +-
 crates/weaver_semconv/data/gen-ai.yaml        | 11 ++-
 crates/weaver_semconv/src/footer.rs           | 38 ----------
 crates/weaver_semconv/src/group.rs            | 37 ++++------
 crates/weaver_semconv/src/header.rs           | 38 ----------
 crates/weaver_semconv/src/lib.rs              |  4 +-
 crates/weaver_semconv/src/migration.rs        | 37 ++++++++++
 crates/weaver_semconv/src/registry.rs         |  6 +-
 crates/weaver_semconv/src/style.rs            | 69 -------------------
 13 files changed, 80 insertions(+), 202 deletions(-)
 delete mode 100644 crates/weaver_semconv/src/footer.rs
 delete mode 100644 crates/weaver_semconv/src/header.rs
 create mode 100644 crates/weaver_semconv/src/migration.rs
 delete mode 100644 crates/weaver_semconv/src/style.rs

diff --git a/crates/weaver_emit/src/lib.rs b/crates/weaver_emit/src/lib.rs
index 3a5f675b..3cf87b5d 100644
--- a/crates/weaver_emit/src/lib.rs
+++ b/crates/weaver_emit/src/lib.rs
@@ -239,6 +239,7 @@ mod tests {
                     body: None,
                     entity_associations: vec![],
                     annotations: None,
+                    migration: None,
                 },
                 ResolvedGroup {
                     id: "test.updowncounter".to_owned(),
@@ -261,6 +262,7 @@ mod tests {
                     display_name: None,
                     body: None,
                     annotations: None,
+                    migration: None,
                 },
                 ResolvedGroup {
                     id: "test.counter".to_owned(),
@@ -283,6 +285,7 @@ mod tests {
                     display_name: None,
                     body: None,
                     annotations: None,
+                    migration: None,
                 },
                 ResolvedGroup {
                     id: "test.gauge".to_owned(),
@@ -305,6 +308,7 @@ mod tests {
                     display_name: None,
                     body: None,
                     annotations: None,
+                    migration: None,
                 },
                 ResolvedGroup {
                     id: "test.histogram".to_owned(),
@@ -327,6 +331,7 @@ mod tests {
                     display_name: None,
                     body: None,
                     annotations: None,
+                    migration: None,
                 },
                 ResolvedGroup {
                     id: "test.updowncounter.double".to_owned(),
@@ -349,6 +354,7 @@ mod tests {
                     display_name: None,
                     body: None,
                     annotations: None,
+                    migration: None,
                 },
                 ResolvedGroup {
                     id: "test.counter.double".to_owned(),
@@ -371,6 +377,7 @@ mod tests {
                     display_name: None,
                     body: None,
                     annotations: None,
+                    migration: None,
                 },
                 ResolvedGroup {
                     id: "test.gauge.double".to_owned(),
@@ -393,6 +400,7 @@ mod tests {
                     display_name: None,
                     body: None,
                     annotations: None,
+                    migration: None,
                 },
                 ResolvedGroup {
                     id: "test.histogram.double".to_owned(),
@@ -415,6 +423,7 @@ mod tests {
                     display_name: None,
                     body: None,
                     annotations: None,
+                    migration: None,
                 },
             ],
         };
diff --git a/crates/weaver_forge/src/registry.rs b/crates/weaver_forge/src/registry.rs
index 711a52a5..c4d7282d 100644
--- a/crates/weaver_forge/src/registry.rs
+++ b/crates/weaver_forge/src/registry.rs
@@ -14,9 +14,8 @@ use weaver_resolved_schema::lineage::GroupLineage;
 use weaver_resolved_schema::registry::{Group, Registry};
 use weaver_semconv::any_value::AnyValueSpec;
 use weaver_semconv::deprecated::Deprecated;
-use weaver_semconv::footer::FooterSpec;
 use weaver_semconv::group::{GroupType, InstrumentSpec, SpanKindSpec};
-use weaver_semconv::header::HeaderSpec;
+use weaver_semconv::migration::MigrationSpec;
 use weaver_semconv::stability::Stability;
 use weaver_semconv::YamlValue;
 
@@ -120,10 +119,7 @@ pub struct ResolvedGroup {
     pub entity_associations: Vec<String>,
     /// Header for the namespace/page.
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub header: Option<HeaderSpec>,
-    /// Footer for the namespace/page.
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub footer: Option<FooterSpec>,
+    pub migration: Option<MigrationSpec>,
     /// Annotations for the group.
     #[serde(default)]
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -180,8 +176,7 @@ impl ResolvedGroup {
             lineage,
             display_name: group.display_name.clone(),
             body: group.body.clone(),
-            footer: group.footer.clone(),
-            header: group.header.clone(),
+            migration: group.migration.clone(),
             entity_associations: group.entity_associations.clone(),
             annotations: group.annotations.clone(),
         })
@@ -243,8 +238,7 @@ impl ResolvedRegistry {
                     lineage,
                     display_name: group.display_name.clone(),
                     body: group.body.clone(),
-                    footer: group.footer.clone(),
-                    header: group.header.clone(),
+                    migration: group.migration.clone(),
                     entity_associations: group.entity_associations.clone(),
                     annotations: group.annotations.clone(),
                 }
diff --git a/crates/weaver_live_check/src/live_checker.rs b/crates/weaver_live_check/src/live_checker.rs
index 1d289772..aecd1b37 100644
--- a/crates/weaver_live_check/src/live_checker.rs
+++ b/crates/weaver_live_check/src/live_checker.rs
@@ -455,6 +455,7 @@ mod tests {
                 display_name: None,
                 body: None,
                 annotations: None,
+                migration: None,
             }],
         }
     }
@@ -527,6 +528,7 @@ mod tests {
                     display_name: Some("System Memory Attributes".to_owned()),
                     body: None,
                     annotations: None,
+                migration: None,
                 },
                 // System uptime metric
                 ResolvedGroup {
@@ -550,6 +552,7 @@ mod tests {
                     display_name: None,
                     body: None,
                     annotations: None,
+                    migration: None,
                 },
                 // System memory usage metric
                 ResolvedGroup {
@@ -591,6 +594,7 @@ mod tests {
                     display_name: None,
                     body: None,
                     annotations: None,
+                    migration: None,
                 },
             ],
         }
@@ -642,6 +646,7 @@ mod tests {
                 display_name: None,
                 body: None,
                 annotations: None,
+                migration: None,
             }],
         };
 
@@ -895,6 +900,7 @@ mod tests {
                 display_name: None,
                 body: None,
                 annotations: None,
+                migration: None,
             }],
         };
 
diff --git a/crates/weaver_resolved_schema/src/registry.rs b/crates/weaver_resolved_schema/src/registry.rs
index 7547388a..33060d52 100644
--- a/crates/weaver_resolved_schema/src/registry.rs
+++ b/crates/weaver_resolved_schema/src/registry.rs
@@ -17,8 +17,7 @@ use crate::registry::GroupStats::{
 };
 use serde::{Deserialize, Serialize};
 use weaver_semconv::deprecated::Deprecated;
-use weaver_semconv::footer::FooterSpec;
-use weaver_semconv::header::HeaderSpec;
+use weaver_semconv::migration::MigrationSpec;
 use weaver_semconv::group::{GroupType, InstrumentSpec, SpanKindSpec};
 use weaver_semconv::provenance::Provenance;
 use weaver_semconv::stability::Stability;
@@ -129,12 +128,9 @@ pub struct Group {
     /// This fields is only used for event groups.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub body: Option<AnyValueSpec>,
-    /// Header for the namespace/page.
+    /// Migration details for the namespace.
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub header: Option<HeaderSpec>,
-    /// Footer for the namespace/page.
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub footer: Option<FooterSpec>,
+    pub migration: Option<MigrationSpec>,
     /// Annotations for the group.
     #[serde(default)]
     #[serde(skip_serializing_if = "Option::is_none")]
diff --git a/crates/weaver_resolver/src/registry.rs b/crates/weaver_resolver/src/registry.rs
index 172041aa..2aa012fa 100644
--- a/crates/weaver_resolver/src/registry.rs
+++ b/crates/weaver_resolver/src/registry.rs
@@ -397,8 +397,7 @@ fn group_from_spec(group: GroupSpecWithProvenance) -> UnresolvedGroup {
             lineage: Some(GroupLineage::new(group.provenance.clone())),
             display_name: group.spec.display_name,
             body: group.spec.body,
-            header: group.spec.header,
-            footer: group.spec.footer,
+            migration: group.spec.migration,
             annotations: group.spec.annotations,
             entity_associations: group.spec.entity_associations,
         },
diff --git a/crates/weaver_semconv/data/gen-ai.yaml b/crates/weaver_semconv/data/gen-ai.yaml
index 4030089f..614f5a0a 100644
--- a/crates/weaver_semconv/data/gen-ai.yaml
+++ b/crates/weaver_semconv/data/gen-ai.yaml
@@ -4,9 +4,8 @@ groups:
     name: gen-ai
     note: This is a description of the gen ai namespace
     brief: This is a summary of the gen ai namespace
-    header:
-      title: Migration strategy
-      content: To protect personl information the following document should be followed.
-      style: warning
-    footer:
-      content: Footer
\ No newline at end of file
+    migration:
+      brief: Migration strategy
+      note: To protect personal information the following document should be followed.
+      targetVersion: 1.20.0
+      link: ./migration-guide.md
\ No newline at end of file
diff --git a/crates/weaver_semconv/src/footer.rs b/crates/weaver_semconv/src/footer.rs
deleted file mode 100644
index 807308a2..00000000
--- a/crates/weaver_semconv/src/footer.rs
+++ /dev/null
@@ -1,38 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-//! Stability specification.
-
-use schemars::JsonSchema;
-use serde::{Deserialize, Serialize};
-use crate::style::Style;
-
-/// A header specification
-#[derive(Serialize, Deserialize, Clone, Debug, Eq, PartialEq, JsonSchema)]
-#[serde(deny_unknown_fields)]
-pub struct FooterSpec {
-
-    /// The title of the footer.
-    pub title: Option<String>,
-    /// The content in the footer.
-    pub content: String,
-    /// The style of the footer.
-    pub style: Option<Style>,
-}
-
-impl FooterSpec {
-    /// returns the title of the footer
-    #[must_use]
-    fn title(&self) -> &Option<String> {
-        &self.title
-    }
-    /// returns the content of the footer
-    #[must_use]
-    fn content(&self) -> &String {
-        &self.content
-    }
-    /// returns the style of the footer
-    #[must_use]
-    fn style(&self) -> &Option<Style> {
-        &self.style
-    }
-}
diff --git a/crates/weaver_semconv/src/group.rs b/crates/weaver_semconv/src/group.rs
index 6547f31b..b2b54ee8 100644
--- a/crates/weaver_semconv/src/group.rs
+++ b/crates/weaver_semconv/src/group.rs
@@ -13,9 +13,8 @@ use std::fmt::{Display, Formatter};
 use crate::any_value::AnyValueSpec;
 use crate::attribute::{AttributeSpec, AttributeType, PrimitiveOrArrayTypeSpec};
 use crate::deprecated::Deprecated;
-use crate::footer::FooterSpec;
 use crate::group::InstrumentSpec::{Counter, Gauge, Histogram, UpDownCounter};
-use crate::header::HeaderSpec;
+use crate::migration::MigrationSpec;
 use crate::provenance::Provenance;
 use crate::semconv::Imports;
 use crate::stability::Stability;
@@ -111,12 +110,9 @@ pub struct GroupSpec {
     /// Note: only valid if type is event
     #[serde(skip_serializing_if = "Option::is_none")]
     pub body: Option<AnyValueSpec>,
-    /// Header for the namespace/page.
+    /// Migration details for the namespace/.
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub header: Option<HeaderSpec>,
-    /// Footer for the namespace/page.
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub footer: Option<FooterSpec>,
+    pub migration: Option<MigrationSpec>,
     /// Annotations for the group.
     #[serde(default)]
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -709,8 +705,7 @@ mod tests {
             name: None,
             display_name: None,
             body: None,
-            header: None,
-            footer: None,
+            migration: None,
             annotations: None,
             entity_associations: Vec::new(),
         };
@@ -876,8 +871,7 @@ mod tests {
             name: None,
             display_name: None,
             body: None,
-            header: None,
-            footer: None,
+            migration: None,
             annotations: None,
             entity_associations: Vec::new(),
         };
@@ -1175,8 +1169,7 @@ mod tests {
                     ),
                 },
             }),
-            header: None,
-            footer: None,
+            migration: None,
             annotations: None,
             entity_associations: Vec::new(),
         };
@@ -1392,8 +1385,7 @@ mod tests {
                     ),
                 },
             }),
-            header: None,
-            footer: None,
+            migration: None,
             annotations: None,
             entity_associations: Vec::new(),
         };
@@ -1538,8 +1530,7 @@ mod tests {
             name: None,
             display_name: None,
             body: None,
-            header: None,
-            footer: None,
+            migration: None,
             annotations: None,
             entity_associations: Vec::new(),
         };
@@ -1710,8 +1701,7 @@ mod tests {
             name: None,
             display_name: None,
             body: None,
-            header: None,
-            footer: None,
+            migration: None,
             annotations: None,
             entity_associations: Vec::new(),
         };
@@ -1864,8 +1854,7 @@ mod tests {
             name: None,
             display_name: None,
             body: None,
-            header: None,
-            footer: None,
+            migration: None,
             annotations: None,
             entity_associations: Vec::new(),
         };
@@ -1926,8 +1915,7 @@ mod tests {
             name: None,
             display_name: None,
             body: None,
-            header: None,
-            footer: None,
+            migration: None,
             annotations: None,
             entity_associations: vec!["test".to_owned()],
         };
@@ -1987,8 +1975,7 @@ mod tests {
             display_name: None,
             attributes: vec![],
             body: None,
-            header: None,
-            footer: None,
+            migration: None,
             annotations: None,
             entity_associations: Vec::new(),
         };
diff --git a/crates/weaver_semconv/src/header.rs b/crates/weaver_semconv/src/header.rs
deleted file mode 100644
index 1ea38aa0..00000000
--- a/crates/weaver_semconv/src/header.rs
+++ /dev/null
@@ -1,38 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-//! Stability specification.
-
-use schemars::JsonSchema;
-use serde::{Deserialize, Serialize};
-use crate::style::Style;
-
-/// A header specification
-#[derive(Serialize, Deserialize, Clone, Debug, Eq, PartialEq, JsonSchema)]
-#[serde(deny_unknown_fields)]
-pub struct HeaderSpec {
-
-    /// The title of the header.
-    pub title: Option<String>,
-    /// The content in the header.
-    pub content: String,
-    /// The style of the header.
-    pub style: Style,
-}
-
-impl HeaderSpec {
-    /// returns the title of the header
-    #[must_use]
-    fn title(&self) -> &Option<String> {
-        &self.title
-    }
-    /// returns the content of the header
-    #[must_use]
-    fn content(&self) -> &String {
-        &self.content
-    }
-    /// returns the style of the header
-    #[must_use]
-    fn style(&self) -> &Style {
-        &self.style
-    }
-}
diff --git a/crates/weaver_semconv/src/lib.rs b/crates/weaver_semconv/src/lib.rs
index 51cbda96..3fc132a0 100644
--- a/crates/weaver_semconv/src/lib.rs
+++ b/crates/weaver_semconv/src/lib.rs
@@ -16,9 +16,8 @@ use weaver_common::error::{format_errors, WeaverError};
 pub mod any_value;
 pub mod attribute;
 pub mod deprecated;
-pub mod footer;
 pub mod group;
-pub mod header;
+pub mod migration;
 pub mod json_schema;
 pub mod manifest;
 pub mod metric;
@@ -28,7 +27,6 @@ pub mod registry_repo;
 pub mod semconv;
 pub mod stability;
 pub mod stats;
-pub mod style;
 
 /// An error that can occur while loading a semantic convention registry.
 #[derive(thiserror::Error, Debug, Clone, PartialEq, Serialize, Diagnostic)]
diff --git a/crates/weaver_semconv/src/migration.rs b/crates/weaver_semconv/src/migration.rs
new file mode 100644
index 00000000..935e3e57
--- /dev/null
+++ b/crates/weaver_semconv/src/migration.rs
@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//! Stability specification.
+
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+/// A migration specification
+#[derive(Serialize, Deserialize, Clone, Debug, Eq, PartialEq, JsonSchema)]
+#[serde(deny_unknown_fields)]
+pub struct MigrationSpec {
+
+    /// An optional brief to be added alongside link to migration guide
+    pub brief: Option<String>,
+    /// An optional note to be added to the migration guide
+    pub note: Option<String>,
+    /// The version which the migration guide should guide a user to.
+    pub target: String,
+}
+
+impl MigrationSpec {
+    /// returns the brief of the migration guide
+    #[must_use]
+    fn brief(&self) -> &Option<String> {
+        &self.brief
+    }
+    /// returns the note of the migration guide
+    #[must_use]
+    fn note(&self) -> &Option<String> {
+        &self.note
+    }
+    /// returns the target of the migration guide 
+    #[must_use]
+    fn target(&self) -> &String {
+        &self.target
+    }
+}
diff --git a/crates/weaver_semconv/src/registry.rs b/crates/weaver_semconv/src/registry.rs
index e590a06d..6ad4fc6c 100644
--- a/crates/weaver_semconv/src/registry.rs
+++ b/crates/weaver_semconv/src/registry.rs
@@ -357,8 +357,7 @@ mod tests {
                         name: None,
                         display_name: Some("Group 1".to_owned()),
                         body: None,
-                        header: None,
-                        footer: None,
+                        migration: None,
                         annotations: None,
                         entity_associations: Vec::new(),
                     }],
@@ -386,8 +385,7 @@ mod tests {
                         name: None,
                         display_name: Some("Group 2".to_owned()),
                         body: None,
-                        header: None,
-                        footer: None,
+                        migration: None,
                         annotations: None,
                         entity_associations: Vec::new(),
                     }],
diff --git a/crates/weaver_semconv/src/style.rs b/crates/weaver_semconv/src/style.rs
deleted file mode 100644
index 2a66cb77..00000000
--- a/crates/weaver_semconv/src/style.rs
+++ /dev/null
@@ -1,69 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-//! Stability specification.
-
-use schemars::JsonSchema;
-use serde::{Deserialize, Serialize};
-use std::fmt::{Display, Formatter};
-
-/// The level of stability for a definition. Defined in [OTEP-232](https://github.com/open-telemetry/oteps/blob/main/text/0232-maturity-of-otel.md)
-#[derive(Serialize, Deserialize, Clone, Debug, Eq, PartialEq, Hash, JsonSchema)]
-#[serde(rename_all = "snake_case")]
-pub enum Style {
-    /// A note message.
-    Note,
-    /// A tip message.
-    Tip,
-    /// An Important message.
-    Important,
-    /// A Warning message.
-    Warning,
-    /// A Caution message.
-    Caution,
-}
-
-/// Implements a human readable display for the stability.
-impl Display for Style {
-    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
-        match self {
-            Style::Note => write!(f, "NOTE"),
-            Style::Tip => write!(f, "TIP"),
-            Style::Important => write!(f, "IMPORTANT"),
-            Style::Warning => write!(f, "WARNING"),
-            Style::Caution => write!(f, "CAUTION"),
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use serde_json;
-
-    #[test]
-    fn test_deserialize_stability() {
-        let note: Style = serde_json::from_str("\"note\"").unwrap();
-        assert_eq!(note, Style::Note);
-
-        let tip: Style = serde_json::from_str("\"tip\"").unwrap();
-        assert_eq!(tip, Style::Tip);
-
-        let important: Style = serde_json::from_str("\"important\"").unwrap();
-        assert_eq!(important, Style::Important);
-
-        let warning: Style = serde_json::from_str("\"warning\"").unwrap();
-        assert_eq!(warning, Style::Warning);
-
-        let caution: Style = serde_json::from_str("\"caution\"").unwrap();
-        assert_eq!(caution, Style::Caution);
-    }
-
-    #[test]
-    fn test_display() {
-        assert_eq!(Style::Note.to_string(), "NOTE");
-        assert_eq!(Style::Tip.to_string(), "TIP");
-        assert_eq!(Style::Important.to_string(), "IMPORTANT");
-        assert_eq!(Style::Warning.to_string(), "WARNING");
-        assert_eq!(Style::Caution.to_string(), "CAUTION");
-    }
-}