In Rego, what do complete, partial set and partial object rules each define?

### The rule head decides the shape of the document Rego rules do not return values to a caller; each one **defines a document** at `data.<package>.<rule name>`. What that document *is* — a single value, a set, or an object — is decided entirely by the shape of the rule head. There are three, and every gate you will ever write picks among them. **Complete rule** — `name := value if { body }` ```rego default allow := false allow := true if { count(input.resource_changes) == 0 } ``` A complete rule defines **at most one value**. If no body succeeds, the document is undefined and the path yields no result — unless a `default` declaration supplies a fallback. If the head omits `:= value`, the value is `true` when the body succeeds. The hard constraint: across all of its bodies and all variable bindings, a complete rule may produce only one value. Two successes with *different* values is a conflict error at evaluation time, not a merge and not a first-wins. **Partial set rule** — `name contains value if { body }` ```rego violation contains addr if { some rc in input.resource_changes addr := rc.address rc.change.after.machine_type == "n1-standard-1" } ``` Every successful evaluation of the body adds one element. Duplicates collapse — it is a set. It can never conflict, because adding the same element twice is a no-op. Crucially, a partial rule is **always defined**: if nothing matches, the path holds an empty set, not undefined. Over the wire a set serialises as a JSON array. **Partial object rule** — `name[key] := value if { body }` ```rego violation[addr] := reason if { some rc in input.resource_changes addr := rc.address reason := "machine family not in catalogue" } ``` Each success inserts one key/value pair, and the result is an object. Like a set it is always defined — an empty object when nothing matches. Unlike a set it *can* conflict: if two successful bindings insert the same key with two different values, the engine raises a conflict error, the same class of failure a complete rule hits when it is over-defined. Choose a key that is unique per match — a resource address, not a resource type. ### `if` and `contains` are not decoration In current Rego, `if` is required between a rule head and its body; a head followed by a brace block with no `if` is a parse error. `contains` is required to declare a partial set. Both keywords exist because the older syntax was ambiguous: `p[x] { ... }` could be read as a set of `x` or as the start of an object, and readers guessed wrong. With the keywords, the head alone tells you the document's shape. `if` also permits a single-expression body without braces: `allow if input.trusted`. ### Choosing a shape for the caller The shape is a contract with whatever queries the path, so pick by what that caller must do: | Caller needs | Shape | What the query path returns | |---|---|---| | a yes/no gate decision | complete rule with `default` | a single boolean, always defined | | a list of human-readable failures | partial set | an array of messages, empty when clean | | per-resource attribution | partial object | `{"<address>": "<reason>", ...}` | The third is the one that upgrades a gate from "something failed" to "these two resources failed, for these reasons" without the caller parsing strings out of a flat list — and it is one query, not one per resource. One further constraint: a rule name defines exactly one document, so all definitions of that name inside a package must agree on shape. A complete `violation` and a `violation contains ...` in the same package is a compile error, not a union.