Add json schema for policy findings, make context optional

.github/workflows/ci.yml

@@ -298,6 +298,7 @@ jobs:
         run: |
           cargo run -- --quiet registry json-schema -j semconv-definition-v2 -o /tmp/semconv.schema.v2.json
           cargo run -- --quiet registry json-schema -j resolved-registry-v2 -o /tmp/semconv.resolved.v2.json
+          cargo run -- --quiet registry json-schema -j policy-finding -o /tmp/policy.finding.json
       - name: Check generated files are up-to-date
         run: |
           failed=0
@@ -320,6 +321,12 @@ jobs:
             failed=1
           fi
 
+          if ! diff -q schemas/policy.finding.json /tmp/policy.finding.json > /dev/null 2>&1; then
+            echo "schemas/policy.finding.json is out of date. Run 'cargo run -- --quiet registry json-schema -j policy-finding -o ./schemas/policy.finding.json' to regenerate it."
+            diff schemas/policy.finding.json /tmp/policy.finding.json
+            failed=1
+          fi
+
           exit $failed
   coverage:
     name: Coverage

CONTRIBUTING.md

@@ -55,6 +55,7 @@ cargo run -- --quiet markdown-help > docs/usage.md
 ```bash
 cargo run -- --quiet registry json-schema -j semconv-definition-v2 -o ./schemas/semconv.schema.v2.json
 cargo run -- --quiet registry json-schema -j resolved-registry-v2 -o ./schemas/semconv.resolved.v2.json
+cargo run -- --quiet registry json-schema -j policy-finding -o ./schemas/policy.finding.json
 ```
 
 **Run `just` before any push to pre-validate all the steps performed by CI.**

crates/weaver_checker/src/finding.rs

@@ -21,7 +21,7 @@ pub struct PolicyFinding {
     /// The context associated with the finding e.g. { "attribute_name": "foo.bar", "attribute_value": "bar" }
     /// The context should contain all dynamic parts of the message
     /// Context values may be used with custom templates and filters to customize reports.
-    pub context: Value,
+    pub context: Option<Value>,
 
     /// The human-readable message of the finding e.g. "This attribute 'foo.bar' is deprecated, reason: 'use foo.baz'"
     /// The message, along with signal_name and signal_type, should contain enough information to understand the advice and
@@ -55,7 +55,7 @@ impl PolicyFinding {
         let message = format!("id={id}, category={category}, group={group}, attr={attr}");
         PolicyFinding {
             id: SEMCONV_ATTRIBUTE.to_owned(),
-            context: ctx,
+            context: Some(ctx),
             message,
             level: FindingLevel::Violation,
             signal_type: None,
@@ -144,11 +144,9 @@ impl<'de> serde::de::Visitor<'de> for ViolationBuilder {
                 let message = opt_message.ok_or(serde::de::Error::missing_field("message"))?;
                 let signal_type = opt_signal_type;
                 let signal_name = opt_signal_name;
-                let advice_context =
-                    opt_context.ok_or(serde::de::Error::missing_field("advice_context"))?;
                 Ok(PolicyFinding {
                     id,
-                    context: advice_context,
+                    context: opt_context,
                     message,
                     level,
                     signal_type,
@@ -162,10 +160,9 @@ impl<'de> serde::de::Visitor<'de> for ViolationBuilder {
                 let message = opt_message.ok_or(serde::de::Error::missing_field("message"))?;
                 let signal_type = opt_signal_type;
                 let signal_name = opt_signal_name;
-                let context = opt_context.ok_or(serde::de::Error::missing_field("context"))?;
                 Ok(PolicyFinding {
                     id,
-                    context,
+                    context: opt_context,
                     message,
                     level,
                     signal_type,
@@ -187,7 +184,14 @@ impl Display for PolicyFinding {
             _ => write!(
                 f,
                 "id={}, context={}, message={}, level={:?}, signal_type={:?}, signal_name={:?}",
-                self.id, self.context, self.message, self.level, self.signal_type, self.signal_name,
+                self.id,
+                self.context
+                    .as_ref()
+                    .map_or("None".to_owned(), |c| c.to_string()),
+                self.message,
+                self.level,
+                self.signal_type,
+                self.signal_name,
             ),
         }
     }
@@ -201,6 +205,48 @@ impl PolicyFinding {
     }
 }
 
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_deserialize_unknown_type_returns_error() {
+        let json =
+            r#"{"type": "unknown_type", "id": "foo", "message": "bar", "level": "violation"}"#;
+        let result = serde_json::from_str::<PolicyFinding>(json);
+        assert!(
+            result.is_err(),
+            "Expected error for unknown type, got: {result:?}"
+        );
+    }
+
+    #[test]
+    fn test_display_with_no_context() {
+        let finding = PolicyFinding {
+            id: "some_id".to_owned(),
+            context: None,
+            message: "some message".to_owned(),
+            level: FindingLevel::Violation,
+            signal_type: None,
+            signal_name: None,
+        };
+        assert!(finding.to_string().contains("context=None"));
+    }
+
+    #[test]
+    fn test_display_with_context() {
+        let finding = PolicyFinding {
+            id: "some_id".to_owned(),
+            context: Some(serde_json::json!({"key": "value"})),
+            message: "some message".to_owned(),
+            level: FindingLevel::Violation,
+            signal_type: None,
+            signal_name: None,
+        };
+        assert!(finding.to_string().contains("context={\"key\":\"value\"}"));
+    }
+}
+
 /// The level of a finding.
 #[derive(
     Debug, Clone, PartialEq, Serialize, Deserialize, PartialOrd, Ord, Eq, Hash, JsonSchema,

crates/weaver_checker/src/lib.rs

@@ -504,11 +504,11 @@ mod tests {
             ),
             PolicyFinding {
                 id: "attr_removed".to_owned(),
-                context: serde_json::json!({
+                context: Some(serde_json::json!({
                     "id": "schema_evolution",
                     "group": "registry.network1".to_owned(),
                     "attr": "protocol.name.3".to_owned(),
-                }),
+                })),
                 message: "Schema evolution violation".to_owned(),
                 level: crate::finding::FindingLevel::Violation,
                 signal_type: None,
@@ -578,7 +578,13 @@ mod tests {
         format!(
             "{}-{}",
             v.id,
-            v.context.as_object().unwrap().get("id").unwrap()
+            v.context
+                .as_ref()
+                .unwrap()
+                .as_object()
+                .unwrap()
+                .get("id")
+                .unwrap()
         )
     }
     #[test]

crates/weaver_live_check/src/advice/mod.rs

@@ -40,7 +40,7 @@ pub trait Advisor {
 /// Fluent builder for creating PolicyFinding instances with automatic emission
 pub struct FindingBuilder {
     id: String,
-    context: JsonValue,
+    context: Option<JsonValue>,
     message: String,
     level: FindingLevel,
     signal_type: Option<String>,
@@ -52,7 +52,7 @@ impl FindingBuilder {
     pub fn new(id: impl Into<String>) -> Self {
         Self {
             id: id.into(),
-            context: JsonValue::Null,
+            context: None,
             message: String::new(),
             level: FindingLevel::Information,
             signal_type: None,
@@ -63,7 +63,7 @@ impl FindingBuilder {
     /// Set the context JSON for this finding
     #[must_use]
     pub fn context(mut self, context: JsonValue) -> Self {
-        self.context = context;
+        self.context = Some(context);
         self
     }
 

crates/weaver_live_check/src/advice/type_advisor.rs

@@ -142,9 +142,9 @@ fn check_attributes<T: CheckableAttribute>(
             };
             advice_list.push(PolicyFinding {
                 id: advice_type,
-                context: json!({
+                context: Some(json!({
                     ATTRIBUTE_NAME_ADVICE_CONTEXT_KEY: key.to_owned()
-                }),
+                })),
                 message,
                 level: advice_level,
                 signal_type: sample.signal_type(),