What fields should a policy violation record carry beyond the human-readable message?

## The message is a rendering; the record is the contract When a policy engine denies a change it produces two things that are easy to conflate. One is the **message** — a sentence written for the person reading it. The other is the **violation record** — a structured object describing what failed, which is what every other system consumes. Teams that only ever look at their own terminal build the first and skip the second, and then discover that everything downstream has to reverse-engineer the sentence. ## The fields, and what each one buys **Rule identifier.** A short, stable id for the rule that fired — `container-memory-limit-required`, not "the memory rule". This is the key everything else joins on: counting how often a rule fires, filtering a report to one rule, correlating today's finding with last week's, and referring to it in a conversation. Without an id, the only handle anyone has is the sentence. **Severity.** A rating the emitting policy assigns. It lets a consumer triage — surface the high ones inline in the review, roll the low ones into a weekly report — without re-implementing that judgement per consumer. **Outcome.** What the engine actually did about this violation, which is not always "blocked". The same rule may be enforcing in one environment and only observing in another, and a record that does not say which one produced it cannot distinguish "this stopped a change" from "this would have stopped a change". Any counting of gate impact depends on this field. **Resource identity.** *Which* thing failed. For a cluster object: kind, namespace, name, and API group/version. For a source document: repository, file path and line. A change can carry dozens of objects; without identity the consumer cannot say which one, and cannot deduplicate across runs. **Field path.** *Where inside that thing.* `spec.template.spec.containers[2].resources.limits.memory` is what lets a review bot post its comment on the offending line rather than at the top of the file, and what lets a person fix a five-container manifest in one edit. This is the field most often left out and the one that most changes the experience. **Message.** The human sentence. Still needed — it is what the developer reads — but it is one field among several rather than the whole payload. **Remediation hint.** What to change, ideally naming the field and the value or where to get it. Machine-readable remediation is also what lets tooling offer a suggested fix rather than only a complaint. A record built from those fields looks like the example attached to this question. Note the shape: identity and location are discrete fields, and the prose is one of them. ## Why prose alone fails Every consumer of a denial wants something the sentence cannot give it. - A **pull-request bot** wants a file and line, or a resource and field path, so it can annotate the change where the problem is. From prose it can only paste a wall of text into one comment. - A **dashboard** wants to group by rule and severity to answer "which rules fire most and where". Grouping by message string splits one rule into as many buckets as it has message variants — because a good message embeds the specific container name, every occurrence is a distinct string. - A **metrics pipeline** wants counts by rule and outcome over time. Prose gives it one unusable dimension. - **Deduplication and suppression** want a stable key. The natural key is (rule id, resource identity, field path). Any consumer that has to build that key by parsing a sentence is building on sand. The deeper problem is that when prose is the only machine-readable thing, consumers *do* parse it. They write a regular expression against the message, it works, and now the wording of that sentence is load-bearing infrastructure that nobody documented as such. ## Two shapes worth getting right **One record per violation, not one per evaluation.** A change that trips the same rule on three containers should produce three records with three field paths, not one record with three sentences glued together. Consumers aggregate; they cannot un-glue. **Additive, self-describing fields.** Consumers will read the fields they know and ignore the rest, so adding a field is safe and removing or repurposing one is not. Emitting a version marker on the payload costs nothing and tells a consumer what it is looking at. ## The practical test Ask what a new consumer would have to do to answer a simple question — "show me every change this quarter that was blocked by the memory-limit rule, and which service it was in". If the answer involves a regular expression over message text, the record is missing fields. If it is a filter on two named fields, the payload is doing its job.