Add imports section in semconv to support references on attribute_groups/metrics/events/entities from custom registries

crates/weaver_resolver/data/multi-registry/custom_registry/custom_registry.yaml

@@ -28,4 +28,7 @@ groups:
       - ref: auction.name
         requirement_level: recommended
       - ref: error.type
-        requirement_level: required
+        requirement_level: required
+
+imports:
+  - metric_ref: metric.example_counter

crates/weaver_resolver/data/multi-registry/otel_registry/otel_registry.yaml

@@ -21,3 +21,13 @@ groups:
         requirement_level: recommended
         examples:
           "Unused"
+
+  - id: metric.example_counter
+    type: metric
+    metric_name: example.counter
+    stability: development
+    brief: A counter of the number of messages processed.
+    instrument: counter
+    unit: "1"
+    attributes:
+      - ref: error.type

crates/weaver_resolver/src/lib.rs

@@ -438,13 +438,14 @@ mod tests {
                         assert_eq!(semconv_spec.groups().len(), 2);
                         assert_eq!(&semconv_spec.groups()[0].id, "shared.attributes");
                         assert_eq!(&semconv_spec.groups()[1].id, "metric.auction.bid.count");
+                        assert_eq!(semconv_spec.imports().expect("Imports not found").len(), 1);
                     }
                     "otel" => {
                         assert_eq!(
                             source.path,
                             "data/multi-registry/otel_registry/otel_registry.yaml"
                         );
-                        assert_eq!(semconv_spec.groups().len(), 2);
+                        assert_eq!(semconv_spec.groups().len(), 3);
                         assert_eq!(&semconv_spec.groups()[0].id, "otel.registry");
                         assert_eq!(&semconv_spec.groups()[1].id, "otel.unused");
                     }
@@ -467,6 +468,9 @@ mod tests {
                         // The group `otel.unused` should be garbage collected
                         let group = resolved_registry.group("otel.unused");
                         assert!(group.is_none());
+                        // The group referenced in the `imports` should not be garbage collected
+                        let group = resolved_registry.group("metric.example_counter");
+                        assert!(group.is_some());
                     }
 
                     let metrics = resolved_registry.groups(GroupType::Metric);

crates/weaver_resolver/src/registry.rs

@@ -15,7 +15,7 @@ use weaver_resolved_schema::attribute::UnresolvedAttribute;
 use weaver_resolved_schema::lineage::{AttributeLineage, GroupLineage};
 use weaver_resolved_schema::registry::{Group, Registry};
 use weaver_semconv::attribute::AttributeSpec;
-use weaver_semconv::group::GroupSpecWithProvenance;
+use weaver_semconv::group::{GroupImportWithProvenance, GroupSpecWithProvenance};
 use weaver_semconv::manifest::RegistryManifest;
 use weaver_semconv::provenance::Provenance;
 use weaver_semconv::registry::SemConvRegistry;
@@ -30,6 +30,9 @@ pub struct UnresolvedRegistry {
     /// The resolution process will progressively move the unresolved groups
     /// into the registry field once they are resolved.
     pub groups: Vec<UnresolvedGroup>,
+
+    /// List of unresolved imports that belong to the semantic convention
+    pub imports: Vec<GroupImportWithProvenance>,
 }
 
 /// A group containing unresolved attributes.
@@ -43,7 +46,7 @@ pub struct UnresolvedGroup {
     /// The resolution process will progressively move the unresolved attributes,
     /// and other signals, into the group field once they are resolved.
     pub attributes: Vec<UnresolvedAttribute>,
-
+    
     /// The provenance of the group (URL or path).
     pub provenance: Provenance,
 }
@@ -137,7 +140,7 @@ pub fn resolve_semconv_registry(
     check_root_attribute_id_duplicates(&ureg.registry, &attr_name_index, &mut errors);
 
     if !include_unreferenced {
-        gc_unreferenced_objects(registry.manifest(), &mut ureg.registry, attr_catalog);
+        gc_unreferenced_objects(registry.manifest(), &mut ureg.registry, &ureg.imports, attr_catalog);
     }
 
     WResult::OkWithNFEs(ureg.registry, errors)
@@ -149,16 +152,26 @@ pub fn resolve_semconv_registry(
 fn gc_unreferenced_objects(
     manifest: Option<&RegistryManifest>,
     registry: &mut Registry,
+    imports: &[GroupImportWithProvenance],
     attr_catalog: &mut AttributeCatalog,
 ) {
+    // Build a set of imported IDs from the imports.
+    let imported_ids: HashSet<&str> = imports
+        .iter()
+        .map(|iwp| iwp.import.r#ref())
+        .collect();
+
     if let Some(manifest) = manifest {
         if manifest.dependencies.as_ref().map_or(0, |d| d.len()) > 0 {
             // This registry has dependencies.
             let current_reg_id = manifest.name.clone();
 
             // Remove all groups that are not defined in the current registry.
             registry.groups.retain(|group| {
-                if let Some(lineage) = &group.lineage {
+                if imported_ids.contains(group.id.as_str()) {
+                    // This group is referenced in a dependency, so we keep it.
+                    true
+                } else if let Some(lineage) = &group.lineage {
                     lineage.provenance().registry_id.as_ref() == current_reg_id
                 } else {
                     true
@@ -307,10 +320,14 @@ fn unresolved_registry_from_specs(
         .unresolved_group_with_provenance_iter()
         .map(group_from_spec)
         .collect();
-
+    let imports = registry
+        .unresolved_imports_iter()
+        .collect::<Vec<_>>();
+
     UnresolvedRegistry {
         registry: Registry::new(registry_url),
         groups,
+        imports,
     }
 }
 

crates/weaver_semconv/src/group.rs

@@ -106,6 +106,44 @@
     pub entity_associations: Vec<String>,
 }
 
+/// Represents an import of a group defined in an imported registry.
+/// Currently supports references to groups of type `metric`, `event`, and `entity`.
+#[derive(Serialize, Deserialize, Debug, Clone, JsonSchema)]
+#[serde(deny_unknown_fields)]
+#[serde(untagged)]
+#[serde(rename_all = "snake_case")]
+pub enum GroupImport {
+    /// Imports a metric group from the imported registry.
+    MetricRef {
+        /// The ID of the metric group being referenced in the imported registry.
+        metric_ref: String,
+        // Additional overridable fields may be added in the future.
+    },
+    /// Imports an event group from the imported registry.
+    EventRef {
+        /// The ID of the event group being referenced in the imported registry.
+        event_ref: String,
+        // Additional overridable fields may be added in the future.
+    },
+    /// Imports an entity group from the imported registry.
+    EntityRef {
+        /// The ID of the entity group being referenced in the imported registry.
+        entity_ref: String,
+        // Additional overridable fields may be added in the future.
+    },
+}
+
+impl GroupImport {
+    /// Returns the reference of the group being imported.
+    pub fn r#ref(&self) -> &str {
+        match self {
+            GroupImport::MetricRef { metric_ref } => metric_ref,
+            GroupImport::EventRef { event_ref } => event_ref,
+            GroupImport::EntityRef { entity_ref } => entity_ref,
+        }
+    }
+}
+
 impl GroupSpec {
     /// Validation logic for the group.
     pub(crate) fn validate(&self, path_or_url: &str) -> WResult<(), Error> {
@@ -1860,3 +1898,12 @@
     /// The provenance of the group spec (path or URL).
     pub provenance: Provenance,
 }
+
+/// A group import with its provenance (path or URL).
+#[derive(Debug, Clone, Deserialize)]
+pub struct GroupImportWithProvenance {
+    /// The group import.
+    pub import: GroupImport,
+    /// The provenance of the group import (path or URL).
+    pub provenance: Provenance,
+}

crates/weaver_semconv/src/registry.rs

@@ -3,7 +3,7 @@
 //! Semantic Convention Registry.
 
 use crate::attribute::AttributeSpecWithProvenance;
-use crate::group::GroupSpecWithProvenance;
+use crate::group::{GroupImportWithProvenance, GroupSpecWithProvenance};
 use crate::json_schema::JsonSchemaValidator;
 use crate::manifest::RegistryManifest;
 use crate::metric::MetricSpecWithProvenance;
@@ -246,6 +246,23 @@ impl SemConvRegistry {
             })
     }
 
+    /// Returns an iterator over all the unresolved imports defined in the semantic convention
+    /// registry. Each import is associated with its provenance (path or URL).
+    pub fn unresolved_imports_iter(&self) -> impl Iterator<Item = GroupImportWithProvenance> + '_ {
+        self.specs
+            .iter()
+            .flat_map(|SemConvSpecWithProvenance { spec, provenance }| {
+                spec.imports.iter().flat_map(|imports| {
+                    imports
+                        .iter()
+                        .map(|group_import| GroupImportWithProvenance {
+                            import: group_import.clone(),
+                            provenance: provenance.clone(),
+                        })
+                })
+            })
+    }
+
     /// Returns a set of stats about the semantic convention registry.
     pub fn stats(&self) -> Stats {
         Stats {
@@ -347,6 +364,7 @@ mod tests {
                         annotations: None,
                         entity_associations: Vec::new(),
                     }],
+                    imports: None,
                 },
             ),
             (
@@ -373,6 +391,7 @@ mod tests {
                         annotations: None,
                         entity_associations: Vec::new(),
                     }],
+                    imports: None,
                 },
             ),
         ];

crates/weaver_semconv/src/semconv.rs

@@ -2,7 +2,7 @@
 
 //! Semantic convention specification.
 
-use crate::group::GroupSpec;
+use crate::group::{GroupImport, GroupSpec};
 use crate::json_schema::JsonSchemaValidator;
 use crate::provenance::Provenance;
 use crate::Error;
@@ -19,6 +19,10 @@ use weaver_common::result::WResult;
 pub struct SemConvSpec {
     /// A collection of semantic convention groups or [`GroupSpec`].
     pub(crate) groups: Vec<GroupSpec>,
+
+    /// A list of imports referencing groups defined in a dependent registry.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) imports: Option<Vec<GroupImport>>,
 }
 
 /// A wrapper for a [`SemConvSpec`] with its provenance.
@@ -172,6 +176,12 @@ impl SemConvSpec {
     pub fn groups(&self) -> &[GroupSpec] {
         &self.groups
     }
+
+    /// Returns the list of imports in the semantic convention spec.
+    #[must_use]
+    pub fn imports(&self) -> Option<&[GroupImport]> {
+        self.imports.as_deref()
+    }
 }
 
 impl SemConvSpecWithProvenance {
@@ -278,11 +288,16 @@ mod tests {
                 stability: "stable"
                 brief: "description2"
                 type: "int"
+        imports:
+          - metric_ref: "metric_id"
+          - event_ref: "event_id"
+          - entity_ref: "entity_id"
         "#;
         let semconv_spec = SemConvSpec::from_string(spec)
             .into_result_failing_non_fatal()
             .unwrap();
         assert_eq!(semconv_spec.groups.len(), 2);
+        assert_eq!(semconv_spec.imports.as_ref().unwrap().len(), 3);
 
         // Invalid yaml
         let spec = r#"