Fail on unstructured deprecated property under --future flag

CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to this project will be documented in this file.
 
 - Add support for metrics in Live Check. ([#728](https://github.com/open-telemetry/weaver/pull/728) by @jerbly)
 - Fix #750 - Dual registry resolves incorrectly. ([#753](https://github.com/open-telemetry/weaver/pull/753) by @lquerel)
+- Fail on unstructured `deprecated` note (behind `--future` flag) ([#737](https://github.com/open-telemetry/weaver/pull/737) by @lmolkova)
 
 # [0.15.0] - 2025-05-01
 

crates/weaver_codegen_test/semconv_registry/registry/deprecated/network.yaml

@@ -6,55 +6,74 @@ groups:
     attributes:
       - id: net.sock.peer.name
         type: string
-        deprecated: "Removed."
+        deprecated:
+          reason: obsoleted
+          note: >
+            Removed, no replacement at this time.
         stability: experimental
         brief: Deprecated, no replacement at this time.
         examples: ['/var/my.sock']
       - id: net.sock.peer.addr
         type: string
-        deprecated: "Replaced by `network.peer.address`."
+        deprecated:
+          reason: renamed
+          renamed_to: network.peer.address
         stability: experimental
         brief: Deprecated, use `network.peer.address`.
         examples: ['192.168.0.1']
       - id: net.sock.peer.port
         type: int
-        deprecated: "Replaced by `network.peer.port`."
+        deprecated:
+          reason: renamed
+          renamed_to: network.peer.port
         stability: experimental
         examples: [65531]
         brief: Deprecated, use `network.peer.port`.
       - id: net.peer.name
         type: string
-        deprecated: "Replaced by `server.address` on client spans and `client.address` on server spans."
+        deprecated:
+          reason: uncategorized
+          note: "Replaced by `server.address` on client spans and `client.address` on server spans."
         stability: experimental
         brief: Deprecated, use `server.address` on client spans and `client.address` on server spans.
         examples: ['example.com']
       - id: net.peer.port
         type: int
-        deprecated: "Replaced by `server.port` on client spans and `client.port` on server spans."
+        deprecated:
+          reason: uncategorized
+          note: "Replaced by `server.port` on client spans and `client.port` on server spans."
         stability: experimental
         brief: Deprecated, use `server.port` on client spans and `client.port` on server spans.
         examples: [8080]
       - id: net.host.name
         type: string
-        deprecated: "Replaced by `server.address`."
+        deprecated:
+          reason: renamed
+          renamed_to: server.address
         stability: experimental
         brief: Deprecated, use `server.address`.
         examples: ['example.com']
       - id: net.host.port
         type: int
-        deprecated: "Replaced by `server.port`."
+        deprecated:
+          reason: renamed
+          renamed_to: server.port
         stability: experimental
         brief: Deprecated, use `server.port`.
         examples: [8080]
       - id: net.sock.host.addr
         type: string
-        deprecated: "Replaced by `network.local.address`."
+        deprecated:
+          reason: renamed
+          renamed_to: network.local.address
         stability: experimental
         brief: Deprecated, use `network.local.address`.
         examples: ['/var/my.sock']
       - id: net.sock.host.port
         type: int
-        deprecated: "Replaced by `network.local.port`."
+        deprecated:
+          reason: renamed
+          renamed_to: network.local.port
         stability: experimental
         brief: Deprecated, use `network.local.port`.
         examples: [8080]
@@ -84,18 +103,24 @@ groups:
               value: "other"
               stability: experimental
               brief: 'Something else (non IP-based).'
-        deprecated: "Replaced by `network.transport`."
+        deprecated:
+          reason: renamed
+          renamed_to: network.transport
         stability: experimental
         brief: Deprecated, use `network.transport`.
       - id: net.protocol.name
         type: string
-        deprecated: "Replaced by `network.protocol.name`."
+        deprecated:
+          reason: renamed
+          renamed_to: network.protocol.name
         stability: experimental
         brief: Deprecated, use `network.protocol.name`.
         examples: ['amqp', 'http', 'mqtt']
       - id: net.protocol.version
         type: string
-        deprecated: "Replaced by `network.protocol.version`."
+        deprecated:
+          reason: renamed
+          renamed_to: network.protocol.version
         stability: experimental
         brief: Deprecated, use `network.protocol.version`.
         examples: '3.1.1'

crates/weaver_forge/data/exporter.yaml

@@ -23,12 +23,16 @@ groups:
       - id: otel.library.name
         stability: stable
         type: string
-        deprecated: use the `otel.scope.name` attribute.
+        deprecated:
+          reason: renamed
+          renamed_to: otel.scope.name
         brief:
         examples: ['io.opentelemetry.contrib.mongodb']
       - id: otel.library.version
         stability: stable
         type: string
-        deprecated: use the `otel.scope.version` attribute.
+        deprecated:
+          reason: renamed
+          renamed_to: otel.scope.version
         brief:
         examples: ['1.0.0']

crates/weaver_forge/expected_output/test/resource/library.md

@@ -22,7 +22,7 @@ Brief: Span attributes used by non-OTLP exporters to represent OpenTelemetry Sco
 - Examples: [
     "io.opentelemetry.contrib.mongodb",
 ]
-- Deprecated: use the `otel.scope.name` attribute.
+- Deprecated: Replaced by `otel.scope.name`.
 
 - Stability: Stable
 
@@ -38,7 +38,7 @@ Brief: Span attributes used by non-OTLP exporters to represent OpenTelemetry Sco
 - Examples: [
     "1.0.0",
 ]
-- Deprecated: use the `otel.scope.version` attribute.
+- Deprecated: Replaced by `otel.scope.version`.
 
 - Stability: Stable
 

crates/weaver_forge/src/extensions/otel.rs

@@ -851,7 +851,7 @@ mod tests {
                 Ctx { attr },
             )
             .unwrap(),
-            "uncategorized: Replaced by new_name."
+            "unspecified: Replaced by new_name."
         );
 
         // ---------------------------------------------------------------------

crates/weaver_live_check/src/advice.rs

@@ -53,7 +53,9 @@ fn deprecated_to_value(deprecated: &Deprecated) -> Value {
     match deprecated {
         Deprecated::Renamed { .. } => Value::String("renamed".to_owned()),
         Deprecated::Obsoleted { .. } => Value::String("obsoleted".to_owned()),
-        Deprecated::Uncategorized { .. } => Value::String("uncategorized".to_owned()),
+        Deprecated::Uncategorized { .. } | Deprecated::Unspecified { .. } => {
+            Value::String("uncategorized".to_owned())
+        }
     }
 }
 

crates/weaver_resolved_schema/src/lib.rs

@@ -329,7 +329,7 @@ impl ResolvedTelemetrySchema {
                                 },
                             );
                         }
-                        Deprecated::Uncategorized { note } => {
+                        Deprecated::Unspecified { note } | Deprecated::Uncategorized { note } => {
                             changes.add_change(
                                 SchemaItemType::RegistryAttributes,
                                 SchemaItemChange::Uncategorized {
@@ -410,7 +410,7 @@ impl ResolvedTelemetrySchema {
                                 },
                             );
                         }
-                        Deprecated::Uncategorized { note } => {
+                        Deprecated::Unspecified { note } | Deprecated::Uncategorized { note } => {
                             changes.add_change(
                                 schema_item_type,
                                 SchemaItemChange::Uncategorized {

crates/weaver_semconv/data/exporter.yaml

@@ -25,12 +25,16 @@ groups:
       - id: name
         stability: stable
         type: string
-        deprecated: use the `otel.scope.name` attribute.
+        deprecated:
+          reason: renamed
+          renamed_to: otel.scope.name
         brief:
         examples: ['io.opentelemetry.contrib.mongodb']
       - id: version
         stability: stable
         type: string
-        deprecated: use the `otel.scope.version` attribute.
+        deprecated:
+          reason: renamed
+          renamed_to: otel.scope.version
         brief:
         examples: ['1.0.0']

crates/weaver_semconv/data/invalid-stability.yaml

@@ -17,5 +17,7 @@ groups:
           When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent
           the client address behind any intermediaries (e.g. proxies) if it's available.
         examples: ['/tmp/my.sock', '10.1.2.80']
-        deprecated: use xyz instead
+        deprecated:
+          reason: renamed
+          renamed_to: xyz
         stability: stable

crates/weaver_semconv/src/deprecated.rs

@@ -43,6 +43,13 @@ pub enum Deprecated {
         /// The note to provide more context about the deprecation.
         note: String,
     },
+
+    /// This variant is used to capture old, unstructured deprecated "string".
+    /// Used for backward-compatibility only.
+    Unspecified {
+        /// The note to provide more context about the deprecation.
+        note: String,
+    },
 }
 
 /// Custom deserialization function to handle both old and new formats.
@@ -72,7 +79,7 @@ where
         where
             E: de::Error,
         {
-            Ok(Deprecated::Uncategorized {
+            Ok(Deprecated::Unspecified {
                 note: value.to_owned(),
             })
         }
@@ -172,7 +179,8 @@ impl Display for Deprecated {
         let text = match self {
             Deprecated::Renamed { note, .. }
             | Deprecated::Obsoleted { note }
-            | Deprecated::Uncategorized { note } => note,
+            | Deprecated::Uncategorized { note }
+            | Deprecated::Unspecified { note } => note,
         };
         write!(f, "{}", text)
     }
@@ -192,14 +200,14 @@ mod tests {
     fn test_deser_and_to_string() {
         let yaml_data = r#"
 - deprecated: 'Replaced by `jvm.buffer.memory.used`.'
-- deprecated: 
+- deprecated:
     reason: obsoleted
 - deprecated:
     reason: renamed
     renamed_to: foo.unique_id
 - deprecated:
     reason: uncategorized
-    note: This field is deprecated for some complex reasons.   
+    note: This field is deprecated for some complex reasons.
 - deprecated:
     reason: renamed
     renamed_to: foo.unique_id
@@ -210,7 +218,7 @@ mod tests {
         assert_eq!(items.len(), 5);
         assert_eq!(
             items[0].deprecated,
-            Some(Deprecated::Uncategorized {
+            Some(Deprecated::Unspecified {
                 note: "Replaced by `jvm.buffer.memory.used`.".to_owned()
             })
         );

crates/weaver_semconv/src/group.rs

@@ -256,6 +256,14 @@ impl GroupSpec {
             }
         }
 
+        if matches!(self.deprecated, Some(Deprecated::Unspecified { .. })) {
+            errors.push(Error::UnstructuredDeprecatedProperty {
+                path_or_url: path_or_url.to_owned(),
+                id: self.id.clone(),
+                error: "Unstructured deprecated note is not supported on groups.".to_owned(),
+            });
+        }
+
         // Validates the attributes.
         for attribute in &self.attributes {
             match attribute {
@@ -316,6 +324,15 @@ impl GroupSpec {
                             }
                         }
                     }
+
+                    if matches!(deprecated, Some(Deprecated::Unspecified { .. })) {
+                        errors.push(Error::UnstructuredDeprecatedProperty {
+                            path_or_url: path_or_url.to_owned(),
+                            id: attribute.id(),
+                            error: "Unstructured deprecated note is not supported on attributes."
+                                .to_owned(),
+                        });
+                    }
                 }
                 AttributeSpec::Ref { .. } => {}
             }
@@ -602,7 +619,7 @@ mod tests {
         CompoundError, InvalidAttributeAllowCustomValues, InvalidAttributeWarning,
         InvalidExampleWarning, InvalidGroup, InvalidGroupMissingExtendsOrAttributes,
         InvalidGroupMissingType, InvalidGroupStability, InvalidGroupUsesPrefix, InvalidMetric,
-        InvalidSpanMissingSpanKind,
+        InvalidSpanMissingSpanKind, UnstructuredDeprecatedProperty,
     };
 
     use super::*;
@@ -753,6 +770,23 @@ mod tests {
                 ],
             ),
         ), result);
+
+        // Group deprecated is set to unspecified
+        group.name = Some("test".to_owned());
+        group.span_kind = None;
+        group.events = vec![];
+        group.deprecated = Some(Deprecated::Unspecified {
+            note: "note".to_owned(),
+        });
+        let result = group.validate("<test>").into_result_failing_non_fatal();
+        assert_eq!(
+            Err(UnstructuredDeprecatedProperty {
+                path_or_url: "<test>".to_owned(),
+                id: "test".to_owned(),
+                error: "Unstructured deprecated note is not supported on groups.".to_owned(),
+            },),
+            result
+        );
     }
 
     #[test]
@@ -990,6 +1024,33 @@ mod tests {
             },),
             result
         );
+
+        // Deprecated is set to unspecified.
+        group.attributes = vec![AttributeSpec::Id {
+            id: "test".to_owned(),
+            r#type: AttributeType::PrimitiveOrArray(PrimitiveOrArrayTypeSpec::String),
+            brief: Some("brief".to_owned()),
+            stability: Some(Stability::Stable),
+            deprecated: Some(Deprecated::Unspecified {
+                note: "note".to_owned(),
+            }),
+            examples: Some(Examples::String("test".to_owned())),
+            tag: None,
+            requirement_level: Default::default(),
+            sampling_relevant: None,
+            note: "".to_owned(),
+            annotations: None,
+            role: Default::default(),
+        }];
+        let result = group.validate("<test>").into_result_failing_non_fatal();
+        assert_eq!(
+            Err(UnstructuredDeprecatedProperty {
+                path_or_url: "<test>".to_owned(),
+                id: "test".to_owned(),
+                error: "Unstructured deprecated note is not supported on attributes.".to_owned(),
+            },),
+            result
+        );
     }
 
     #[test]