Introduce the ability to define namespaces #802

Author: thompson-tomo

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(),
                 }

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,

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,
         },

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

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
+    }
+}

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());
+    }
 }

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
+    }
+}