Opa Knowledge Patch

Open Policy Agent Knowledge Patch

Load this skill when migrating Rego to v1, upgrading an OPA deployment, embedding OPA in Go, building bundles, or investigating changed evaluation, testing, plugin, security, and observability behavior.

Treat the application's manifests, configuration, policies, tests, and observed runtime behavior as primary evidence. Use the references below for changed defaults, compatibility traps, corrected behavior, and newly available APIs.

Reference index

Breaking changes and migration hazards

Migrate Rego v1 syntax deliberately

Rules with bodies require if, multi-value rules require contains, and in, every, if, and contains are keywords. Imports that shadow or duplicate other imports fail compilation, as do variables or rules named input or data. Use a current binary to check and rewrite legacy source:

opa check --v0-v1
opa check --v0-v1 --strict
opa fmt --write --v0-v1
regal lint

During a mixed-version bundle rollout, upgrade bundle producers before consumers. Keep policies v0-compatible while v0 consumers remain, and use --v0-compatible whenever a v1 consumer loads a bundle whose producer could not record a Rego version.

Make assignment inputs independently safe

The right side of := must be safe before assignment. A later constraint on the assigned variable does not make the source variable safe:

allow if {
	y = 7
	x := y
	x == 7
}

Rewrite policies that relied on x := y; x = 7, which now fails with rego_unsafe_var_error. Explicit reference iteration such as some k; v := obj[k] remains valid.

Keep partial rule kinds consistent

Do not define one name as both a partial set and a partial object. Rename one rule or make all definitions produce the same kind:

p contains "item" if true
p["key"] := "value" if true

These definitions can no longer coexist.

Re-test corrected evaluation paths

Upgrades can change results for policies affected by earlier implementation bugs. Pay particular attention to:

• partial evaluation involving default functions, every, nested comprehensions, copy propagation, or internal residual variables;
• Wasm evaluation of reference-head rules;
• overlapping indexed array and scalar rules;
• graph.reachable_paths, which now returns all reachable paths;
• two-variable membership over sets; and
• arithmetic or formatting of integers larger than 64 bits.

Adapt server and integration assumptions

opa run --server binds to localhost unless --addr is explicit:

opa run --server --addr 0.0.0.0:8181

OPA server routing uses http.ServeMux, so Go integrations coupled to the old router may need changes. HTTP servers also enforce a 32-second ReadHeaderTimeout. Validate clients and intermediaries that send headers slowly.

Startup now warns about unknown configuration keys. Inspect those warnings, including Config.Warnings in Go embedders, so misspellings such as decision_log do not remain unnoticed.

Update external protocol assumptions

Outbound HTTP requests use this product token:

User-Agent: Open-Policy-Agent/<version> (<os>, <arch>)

Update exact-match log filters and WAF rules. Compile API deployments emitting PostgreSQL filters must also use the corrected SQL encoder before allowing dynamic reference keys to influence identifier positions.

High-value Rego capabilities

Use expression interpolation

Prefix a quoted template with $ and place expressions in braces. Undefined expressions render as <undefined> rather than making the rule undefined:

message := $"User {input.username} has role {input.role}"

Opt in to improved negation semantics

Import future.keywords.not whenever a policy uses not and should place all compiler-expanded parts of a composite expression inside the negated body:

import future.keywords.not

allow if {
	not blocked(input.user)
}

Unlike older future-keyword imports under Rego v1, this import selects changed behavior: undefined nested input or calls make not succeed.

Use newer data helpers

• array.flatten flattens nested arrays; require at least 1.13.1 because 1.13.0 mishandles single-item arrays.
• uri.parse returns RFC 3986 components and uri.is_valid reports malformed inputs.
• strings.split_n selects the first n fields for positive n, the last abs(n) fields for negative n, all available fields when the magnitude is too large, and an empty array for zero.
• time.parse_duration_ns accepts days, weeks, and years.
• json.match_schema accepts array-rooted documents; recursive schemas, $ref within allOf, and pattern validation are supported.

High-value operations guidance

Check bundles and preserve compatibility metadata

Use opa check --bundle to detect conflicts between base documents and virtual documents. For mixed-version bundles, recheck per-module Rego version selection and overlapping file_rego_versions patterns. API-created bundles receive a default Rego version when one is omitted.

Optimized bundle entrypoints must contain at least a package and rule:

opa build -O=1 -e=authz/allow .

Control testing and formatting changes

Tests run in parallel by default; use --parallel=1 for order-sensitive suites. Parameterized tests can generate named cases in the test-rule head, and test output may be streamed. Coverage reports now use source ranges and track inline heads and conjunctions, so rebaseline location and total expectations after upgrading.

Use 1.18.2 or later before accepting formatter diffs in the 1.18 line. It restores intended one-line formatting for single-item collections while retaining fixes for comment-adjacent with clauses.

Prefer patched point releases

Use the patched point release called out for a release line when relying on distributed binaries or images. Several point releases restore missing capability files or logs, fix shutdown hangs and memory leaks, correct formatting or built-in behavior, and rebuild with Go standard-library security fixes. Self-built artifact security depends on the selected Go toolchain.

Working method

1. Determine the deployed OPA version, distribution source, Rego mode, and bundle producer versions from project evidence.
2. Read the topic reference that matches the change under investigation.
3. Apply version-specific guidance only where the project's version and mode make it relevant.
4. Re-run policy checks, tests, bundle validation, and integration tests that exercise corrected behavior.
5. Inspect startup warnings, logs, metrics, and decision output for changed configuration or result shapes.