releases/docs/glossary.yaml

ground-value:
  title: "Ground Value"
  short: |
    A "ground value" is any value that doesn't contain variables
  long: |
    A "ground value" is any value that doesn't contain variables - essentially a
    concrete, known value like `true`, `"hello"`, `42`, or `["a", "b"]`. This is in
    contrast to expressions with variables like `x` or `input.user`, or composite
    values containing variables like `{"foo": y}` where `y` gets bound during evaluation.
    For a formal definition, see
    [ground term](https://en.wikipedia.org/wiki/Ground_expression#ground_term).

scalar-values:
  title: "Scalar Values"
  short: |
    Simple, single values in Rego including strings, numbers, booleans, and null
  long: |
    Scalar values are the simplest type of data in Rego. They represent single,
    indivisible values and include four types: strings (like `"hello"`), numbers
    (like `42` or `3.14`), booleans (`true` or `false`), and `null`. These are in
    contrast to composite values like arrays or objects that contain multiple elements.

composite-values:
  title: "Composite Values"
  short: |
    Collections that contain multiple values: arrays, sets and objects
  long: |
    Composite values are collections that group multiple values together. Rego supports
    three types of composite values: arrays (ordered lists like `[1, 2, 3]`),
    sets (unordered collections of unique values like `{1, 2, 3}`), and
    objects (key-value mappings like `{"name": "Alice", "age": 30}`).
    These can contain any combination
    of scalar values, other composite values, variables, or references.

comprehensions:
  title: "Comprehensions"
  short: |
    Syntax for building arrays, objects, or sets from queries
  long: |
    Comprehensions provide a way to build composite values from sub-queries,
    similar to list comprehensions in Python and other languages.
    Rego supports three types: array
    comprehensions `[x | condition]`, object comprehensions `{key: value | condition}`,
    and set comprehensions `{x | condition}`. They consist of a head (the expression
    to include in the result) and a body (the conditions that must be true).
    For example, `[name | sites[i].name == name]` creates an array from site names.

unification:
  title: "Unification"
  short: |
    Using the `=` operator to find variable bindings that make expressions true
  long: |
    Unification (`=`) combines assignment and comparison in a single operation. Unlike
    assignment (`:=`) which requires the right side to be a known value, or comparison
    (`==`) which requires both sides to be known, unification can work with unknown
    variables on either side. Rego will find values for variables that make the
    unification true. For example, `[x, "world"] = ["hello", y]` will bind `x` to
    `"hello"` and `y` to `"world"`. This is useful for pattern matching
    and destructuring complex data structures.

virtual-documents:
  title: "Virtual Documents"
  short: |
    Documents generated by OPA rules, as opposed to base documents loaded from external sources
  long: |
    Virtual documents are generated by OPA when evaluating rules, in contrast to base
    documents which are loaded from external sources. When you define a rule like
    `allow := true if { ... }`, OPA creates a virtual document at `data.package.allow`.
    Virtual documents exist only during evaluation and represent the computed results
    of your policy logic. They form OPA's "virtual document tree" alongside base data.

base-documents:
  title: "Base Documents"
  short: |
    Raw data loaded into OPA from external sources like JSON files or APIs
  long: |
    Base documents are the raw data that OPA loads from external sources such as JSON
    files, APIs, or request bodies. This includes both the `data` document (containing
    static policy data) and the `input` document (containing request-specific data).
    Base documents form the foundation for policy evaluation and are static input data,
    unlike virtual documents which are generated by rules. For example, loading a
    JSON file with `{"users": ["alice", "bob"]}` creates a base document accessible
    as `data.users`, while request data becomes available as `input.*`. You can list
    base documents used by a query with `opa deps` (see [CLI documentation](/docs/cli#deps)).

rule-head:
  title: "Rule Head"
  short: |
    The part of a rule that defines its name, value, and type (before the rule body)
  long: |
    The rule head is the part of a rule that comes before the rule body and defines
    what the rule produces. It specifies the rule's name, its value (if any), and
    whether it generates a complete document, partial set, or partial object. Examples:
    `allow := true` (complete document), `users contains name` (partial set), or
    `permissions[user] := perms` (partial object). The head determines how the rule
    contributes to the virtual document tree.

rule-body:
  title: "Rule Body"
  short: |
    The conditions and expressions that must be true for a rule to apply
  long: |
    The rule body contains the conditions and expressions that must all evaluate to
    true for the rule to produce its result. It's enclosed in curly braces and consists
    of one or more expressions separated by semicolons or newlines. For example:
    `{ input.user == "admin"; input.method == "GET" }`. When OPA evaluates a rule,
    it searches for variable bindings that make all expressions in the body true.