Add data related to messageExpression and auditAnnotations in Validat…

content/en/docs/policy-types/validating-policy/_index.md

@@ -169,11 +169,182 @@ spec:
         )
 ```
 
-To write a policy for JSON payloads:
+***To write a policy for JSON payloads:***
 1. Set `spec.evaluation.mode` to `JSON`.
 2. Next, define a `spec.matchConditions` with CEL expressions to tell the engine which payloads should be matched. 
 3. Finally, define your validation rules in `spec.validations`.
 
 To evaluate JSON policies, use the [Kyverno CLI](../../kyverno-cli/). 
 
 A Kyverno Engine SDK is planned for a subsequent release.
+
+## Reporting Details in ValidatingPolicy
+
+When a ValidatingPolicy is evaluated, the results are recorded in PolicyReports. PolicyReports are standard Kubernetes custom resources that summarize the outcomes of policy evaluations, including whether resources passed or failed validation.
+
+Kyverno provides additional fields in ValidatingPolicy rules to make PolicyReports more informative and contextual. Two important features are:
+
+### Using auditAnnotations to add custom data
+
+The auditAnnotations field allows attaching custom key-value data to the results stored in PolicyReports. These values can be static strings or dynamic expressions using [CEL (Common Expression Language)](/docs/policy-types/cel-libraries/)
+.
+
+This is useful for adding metadata such as severity, team ownership, or any resource-specific values that help consumers of the PolicyReport better understand and act on violations.
+
+***Example Policy:***
+
+```yaml
+apiVersion: policies.kyverno.io/v1alpha1
+kind: ValidatingPolicy
+metadata:
+  name: check-deployment-labels
+spec:
+  auditAnnotations:
+    - key: team
+      valueExpression: "platform" 
+  matchConstraints:
+    resourceRules:
+    - apiGroups:   [apps]
+      apiVersions: [v1]
+      operations:  [CREATE, UPDATE]
+      resources:   [deployments]
+  variables:
+    - name: environment
+      expression: >-
+        has(object.metadata.labels) && 'env' in object.metadata.labels && object.metadata.labels['env'] == 'prod'
+  validations:
+    - expression: >-
+        variables.environment == true
+      message: >-
+        Deployment labels must be env=prod
+```
+
+***Example Deployment:***
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx-deployment
+  labels:
+    app: nginx
+    env: prod
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: nginx
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - name: nginx
+        image: nginx:latest
+```
+
+***Resulting PolicyReport entry:***
+
+```bash
+# Example: Add PolicyReport output here
+```
+
+### Using messageExpression to generate dynamic messages
+
+While the message field provides a static failure message, messageExpression allows you to dynamically build messages using CEL expressions. This produces more contextual and precise failure descriptions.
+
+If both message and messageExpression are defined, the messageExpression takes precedence.
+
+The expression must evaluate to a string.
+
+If the expression fails or produces an invalid string (empty, whitespace-only, or multi-line), Kyverno falls back to the static message.
+
+***Example Policy:***
+
+```yaml
+apiVersion: policies.kyverno.io/v1alpha1
+kind: ValidatingPolicy
+metadata:
+  name: check-deployment-labels
+  annotations:
+    policies.kyverno.io/title: Check Deployment Labels
+    policies.kyverno.io/category: Other
+    policies.kyverno.io/severity: medium
+spec:
+  validationActions: 
+   - Audit
+  matchConstraints:
+    resourceRules:
+    - apiGroups:   [apps]
+      apiVersions: [v1]
+      operations:  [CREATE, UPDATE]
+      resources:   [deployments]
+  variables:
+    - name: environment
+      expression: >-
+        has(object.metadata.labels) && 'env' in object.metadata.labels && object.metadata.labels['env'] == 'prod'
+  validations:
+    - expression: >-
+        variables.environment == true
+      messageExpression: >-
+        'Deployment labels must be env=prod' + (has(object.metadata.labels) && 'env' in object.metadata.labels ? ' but found env=' + string(object.metadata.labels['env']) : ' but no env label is present')
+```
+***Example Resource Deployment:***
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: bad-deployment
+  labels:
+    app: nginx
+    env: testing
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: nginx
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - name: nginx
+        image: nginx:latest
+```
+
+***Resulting PolicyReport entry:***
+
+```yaml
+apiVersion: v1
+items:
+- apiVersion: wgpolicyk8s.io/v1alpha2
+  kind: PolicyReport
+  metadata:
+    generation: 1
+    labels:
+      app.kubernetes.io/managed-by: kyverno
+    ownerReferences:
+    - apiVersion: apps/v1
+      kind: Deployment
+      name: no-env
+  results:
+  - category: Other
+    message: Deployment labels must be env=prod but no env label is present
+    policy: check-deployment-labels
+    result: fail
+    scored: true
+    severity: medium
+    source: KyvernoValidatingPolicy
+  scope:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: no-env
+  summary:
+    error: 0
+    fail: 1
+    pass: 0
+    skip: 0
+    warn: 0
+```