Moves away from strict Violation enum to open Violation based on Advice (#1038)

* Update weaver_checker to have more flexible violation deserialziation.

* Fix live check to use new violation spec.

* Last cleanups of Advice->Violation.

* Fix clippy.

* Fix spellcheck.

* Update rendering templates for new generic violations.

* Fix jinja filter.

* Fix error diagnostic output.

* Fix live check templates.

* Rename Violation to PolicyFinding.  Hide sub-mod in weaver-checker.

* cargo fmt

* First crack at updating docs.

* Add changelog.

* Fix spelling issues.

* Update examples for now, will need to revisit to remove the old-school otel policies when we move to v2 schema.

Author: jsuereth

CHANGELOG.md

@@ -8,6 +8,9 @@ All notable changes to this project will be documented in this file.
 - Add support for V2 schema in `weaver check` ([#1016](https://github.com/open-telemetry/weaver/pull/1016) by @jsuereth)
 - Add support for V2 schema in `emit` ([#1019](https://github.com/open-telemetry/weaver/pull/1019) by @jerbly)
 - Add support for V2 schema in `live-check` ([#1022](https://github.com/open-telemetry/weaver/pull/1022) by @jerbly)
+- 💥 BREAKING CHANGE 💥 `Violation` and `Advice` have been renamed
+  to `PolicyFinding`. We now use the same structure between all
+  rego policies in weaver. ([#1038](https://github.com/open-telemetry/weaver/pull/1038) by @jsuereth)
 
 # [0.19.0] - 2025-11-04
 

crates/weaver_checker/README.md

@@ -7,7 +7,7 @@
   - [Policy Definition and Verification](#policy-definition-and-verification)
   - [Usage](#usage)
   - [Policy Examples](#policy-examples)
-- [Creating Rules for Violation Detection](#creating-rules-for-violation-detection)
+- [Creating Rules for Findings](#creating-rules-for-findings)
   - [Understanding the `deny` Rule](#understanding-the-deny-rule)
   - [Key Concepts for Rule Development](#key-concepts-for-rule-development)
   - [Step-by-Step Guide to Creating a New Rule](#step-by-step-guide-to-creating-a-new-rule)
@@ -61,8 +61,8 @@ by the Weaver tool during various phases of the development process.
 
 The policy verification process involves:
 - Reading the semconv files of both the new and previous versions.
-- Applying Rego policies to these files to identify violations.
-- Displaying any detected policy violations, aiding in the resolution before
+- Applying Rego policies to these files to identify findings (can be `violation`, `informational` or `warning`).
+- Displaying any detected policy findings, aiding in the resolution before
   publication.
 
 The following diagram illustrates the policy verification process:
@@ -255,88 +255,98 @@ groups:
         deprecated: true
 ```
 
-... will generate the following violations.
+... will generate the following findings.
 
 ```json
 [
   {
     "type": "semconv_attribute",
-    "id": "attr_stability_deprecated",
-    "category": "attribute",
-    "group": "registry.network1",
-    "attr": "protocol.name"
+    "context": {
+      "id": "attr_stability_deprecated",
+      "category": "attribute",
+      "group": "registry.network1",
+      "attr": "protocol.name",
+    },
+    "message": "...",
+    "level": "violation",
   },
   {
-    "type": "semconv_attribute",
-    "id": "attr_removed",
-    "category": "schema_evolution",
-    "group": "registry.network1",
-    "attr": "protocol.name.3"
+    "id": "semconv_attribute",
+    "context": {
+      "id": "attr_stability_deprecated",
+      "category": "attribute",
+      "group": "registry.network1",
+      "attr": "protocol.name",
+    },
+    "message": "...",
+    "level": "violation",
   },
   {
-    "type": "semconv_attribute",
-    "id": "registry_with_ref_attr",
-    "category": "attribute_registry",
-    "group": "registry.network1",
-    "attr": "protocol.port"
+    "id": "semconv_attribute",
+    "context": {
+      "id": "attr_stability_deprecated",
+      "category": "attribute",
+      "group": "registry.network1",
+      "attr": "protocol.name",
+    },
+    "message": "...",
+    "level": "violation",
   }
 ]
 ```
 
-## Creating Rules for Violation Detection
+## Creating Rules for Findings
 
 The Weaver Policy Engine allows for the dynamic creation and enforcement of
 rules to maintain the integrity and consistency of semantic conventions and
 telemetry schemas. By leveraging the Rego language, developers can specify
-policies that define what constitutes a violation within these domains. This
-section explains how to craft rules for detecting new violations, enhancing the
+policies that define what constitutes a finding within these domains. This
+section explains how to craft rules for detecting new finding, enhancing the
 engine's capability to safeguard the quality and coherence of semantic
 conventions and application telemetry schemas.
 
 ### Understanding the `deny` Rule
 
-The `deny` rule serves as the cornerstone for defining policy violations. When
+The `deny` rule serves as the cornerstone for defining policy finding. When
 the conditions specified within a `deny` rule are met, it indicates a policy
-violation. Each `deny` rule must uniquely identify the violation it detects by
+finding. Each `deny` rule must uniquely identify the finding it detects by
 producing a descriptive message or a structured object that outlines the nature
-of the violation.
+of the finding.
 
 ### Key Concepts for Rule Development
 
-- **Rule Name**: Rules detecting violations must be named `deny`. This is a
-  convention chosen by the Weaver project to facilitate the use and management of
-  these policy files.
-- **Violation Conditions**: The body of a `deny` rule contains one or more
-  conditions that, when true, signal a violation. These conditions can range from
+- **Rule Name**: Rules detecting a finding (e.g. detecting issues or violations)
+  must be named `deny`. This is a convention chosen by the Weaver project to
+  facilitate the use and management of these policy files.
+- **Finding Conditions**: The body of a `deny` rule contains one or more
+  conditions that, when true, signal a finding. These conditions can range from
   simple checks, like the presence of a deprecated attribute, to complex validations
   involving multiple components of the semantic conventions or telemetry schemas.
-- **Violation Message**: Upon detecting a violation, the rule should generate a
-  message or an object that provides detailed information about the violation,
-  including the type of violation, relevant identifiers (e.g., attribute or group
-  ID), and a brief description of the issue.
+- **Finding Message**: Upon detecting a finding, the rule should generate a
+  message or an object that provides detailed information about the finding,
+  including an id, the severity level, a human readable description, and
+  any other relevant context you would like to attach.
 
 ### Step-by-Step Guide to Creating a New Rule
 
-1. **Identify the Violation**: Determine the specific condition or practice that
-   should be flagged as a violation. This could be a new policy requirement, a best
+1. **Identify the Finding**: Determine the specific condition or practice that
+   should be flagged as a finding. This could be a new policy requirement, a best
    practice, or an identified gap in the current policy enforcement.
 
 2. **Define the Rule Conditions**: Craft a set of conditions that accurately
-   capture the criteria for the violation. Utilize the Rego language to express
+   capture the criteria for the finding. Utilize the Rego language to express
    these conditions, making use of variables, functions, and operators as necessary.
 
-3. **Construct the Violation Output**: For defining the structure of the violation
-   object, you can either reuse one of the already defined categories (i.e.,
-   attr_registry_violation, attr_violation, schema_evolution_violation), or define
-   a new one if the category of this violation has not already been defined.
+3. **Construct the Finding Output**: For defining the structure of the finding
+   object.
 
 4. **Implement the Rule in Rego**: Write the `deny` rule in Rego, encapsulating
-   the conditions and violation output you've defined. Ensure the rule is clearly
+   the conditions and finding output you've defined. Ensure the rule is clearly
    commented and documented to facilitate understanding and maintenance.
 
 5. **Test the Rule**: Before integrating the new rule into the Weaver Policy
    Engine, test it with various input scenarios to ensure it accurately detects
-   violations without producing false positives or negatives. A unit test
+   finding without producing false positives or negatives. A unit test
    framework will be provided to facilitate this process in a future PR.
 
 ## Links

crates/weaver_checker/data/policies/otel_policies.rego

@@ -48,6 +48,7 @@ attr_exists_in_new_group(group_id, attr_id) if {
 
 # Build an attribute registry violation
 attr_registry_violation(violation_id, group_id, attr_id) := violation if {
+	# Uses legacy semconv attribute type.
 	violation := {
 		"id": violation_id,
 		"type": "semconv_attribute",
@@ -59,6 +60,7 @@ attr_registry_violation(violation_id, group_id, attr_id) := violation if {
 
 # Build an attribute violation
 attr_violation(violation_id, group_id, attr_id) := violation if {
+	# Uses legacy semconv attribute type.
 	violation := {
 		"id": violation_id,
 		"type": "semconv_attribute",
@@ -70,11 +72,15 @@ attr_violation(violation_id, group_id, attr_id) := violation if {
 
 # Build a schema evolution violation
 schema_evolution_violation(violation_id, group_id, attr_id) := violation if {
+	# Uses New policy violations
 	violation := {
 		"id": violation_id,
-		"type": "semconv_attribute",
-		"category": "schema_evolution",
-		"group": group_id,
-		"attr": attr_id,
+		"context": {
+			"id": "schema_evolution",
+			"group": group_id,
+			"attr": attr_id,
+		},
+		"message": "Schema evolution violation",
+		"level": "violation",
 	}
 }