open-policy-agent · charlieegan3 · Jun 25, 2025 · Jun 24, 2025 · Jun 25, 2025
diff --git a/docs/docs/policy-reference/_examples/graphs/reachable/config.json b/docs/docs/policy-reference/_examples/graphs/reachable/config.json
@@ -1,6 +1,7 @@
 {
-	"showInput": false,
-	"showData":  false,
-	"showTitles": false,
-	"command": "data.graph_reachable_example.result"
+  "showInput": false,
+  "showData": false,
+  "showTitles": false,
+  "titleSize": 5,
+  "command": "data.graph_reachable_example.result"
 }
diff --git a/docs/docs/policy-reference/_examples/graphs/reachable/intro.md b/docs/docs/policy-reference/_examples/graphs/reachable/intro.md
@@ -0,0 +1,4 @@
+A common class of recursive rules can be reduced to a graph reachability
+problem, so `graph.reachable` is useful for more than just graph analysis.
+This usually requires some pre- and postprocessing. The following example
+shows you how to "flatten" a hierarchy of access permissions.
diff --git a/docs/docs/policy-reference/_examples/graphs/reachable/title.txt b/docs/docs/policy-reference/_examples/graphs/reachable/title.txt
@@ -0,0 +1 @@
+Graph Reachable
diff --git a/docs/docs/policy-reference/_examples/graphs/reachable_paths/config.json b/docs/docs/policy-reference/_examples/graphs/reachable_paths/config.json
@@ -1,6 +1,7 @@
 {
-	"showInput": false,
-	"showData":  false,
-	"showTitles": false,
-	"command": "data.graph_reachable_paths_example.result"
+  "showInput": false,
+  "showData": false,
+  "showTitles": false,
+  "titleSize": 5,
+  "command": "data.graph_reachable_paths_example.result"
 }
diff --git a/docs/docs/policy-reference/_examples/graphs/reachable_paths/intro.md b/docs/docs/policy-reference/_examples/graphs/reachable_paths/intro.md
@@ -0,0 +1 @@
+It may be useful to find all reachable paths from a root element. `graph.reachable_paths` can be used for this. Note that cyclical paths will terminate on the repeated node. If an element references a nonexistent element, the path will be terminated, and excludes the nonexistent node.
diff --git a/docs/docs/policy-reference/_examples/graphs/reachable_paths/title.txt b/docs/docs/policy-reference/_examples/graphs/reachable_paths/title.txt
@@ -0,0 +1 @@
+Graph Reachable Paths
diff --git a/docs/docs/policy-reference/_examples/net/cdir_contains1/config.json b/docs/docs/policy-reference/_examples/net/cdir_contains1/config.json
diff --git a/docs/docs/policy-reference/_examples/net/cdir_contains2/config.json b/docs/docs/policy-reference/_examples/net/cdir_contains2/config.json
diff --git a/docs/docs/policy-reference/_examples/net/cdir_contains3/config.json b/docs/docs/policy-reference/_examples/net/cdir_contains3/config.json
diff --git a/docs/docs/policy-reference/_examples/net/cdir_contains4/config.json b/docs/docs/policy-reference/_examples/net/cdir_contains4/config.json
diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_array_string/config.json b/docs/docs/policy-reference/_examples/net/cidr_contains_array_string/config.json
@@ -0,0 +1,7 @@
+{
+  "showInput": false,
+  "showData": false,
+  "showTitles": false,
+  "titleSize": 5,
+  "command": "data.netcidrcontainsmatches.result"
+}
diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_array_string/intro.md b/docs/docs/policy-reference/_examples/net/cidr_contains_array_string/intro.md
@@ -0,0 +1 @@
+Either (or both) operand(s) may be an array, set, or object.
diff --git a/.../_examples/net/cdir_contains2/policy.rego → ...et/cidr_contains_array_string/policy.rego b/.../_examples/net/cdir_contains2/policy.rego → ...et/cidr_contains_array_string/policy.rego
diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_array_string/title.txt b/docs/docs/policy-reference/_examples/net/cidr_contains_array_string/title.txt
@@ -0,0 +1 @@
+CIDR Match with Array
diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_arrays/config.json b/docs/docs/policy-reference/_examples/net/cidr_contains_arrays/config.json
@@ -0,0 +1,7 @@
+{
+  "showInput": false,
+  "showData": false,
+  "showTitles": false,
+  "titleSize": 5,
+  "command": "data.netcidrcontainsmatches.result"
+}
diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_arrays/intro.md b/docs/docs/policy-reference/_examples/net/cidr_contains_arrays/intro.md
@@ -0,0 +1 @@
+The array/set/object elements may be arrays. In that case, the first element must be a valid CIDR/IP.
diff --git a/.../_examples/net/cdir_contains3/policy.rego → ...ples/net/cidr_contains_arrays/policy.rego b/.../_examples/net/cdir_contains3/policy.rego → ...ples/net/cidr_contains_arrays/policy.rego
diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_arrays/title.txt b/docs/docs/policy-reference/_examples/net/cidr_contains_arrays/title.txt
@@ -0,0 +1 @@
+CIDR Match with Arrays
diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_objects/config.json b/docs/docs/policy-reference/_examples/net/cidr_contains_objects/config.json
@@ -0,0 +1,7 @@
+{
+  "showInput": false,
+  "showData": false,
+  "showTitles": false,
+  "titleSize": 5,
+  "command": "data.netcidrcontainsmatches.result"
+}
diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_objects/intro.md b/docs/docs/policy-reference/_examples/net/cidr_contains_objects/intro.md
@@ -0,0 +1 @@
+If the operand is a set, the outputs are matching elements. If the operand is an object, the outputs are matching keys.
diff --git a/.../_examples/net/cdir_contains4/policy.rego → ...les/net/cidr_contains_objects/policy.rego b/.../_examples/net/cdir_contains4/policy.rego → ...les/net/cidr_contains_objects/policy.rego
diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_objects/title.txt b/docs/docs/policy-reference/_examples/net/cidr_contains_objects/title.txt
@@ -0,0 +1 @@
+CIDR Match with Objects
diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_strings/config.json b/docs/docs/policy-reference/_examples/net/cidr_contains_strings/config.json
@@ -0,0 +1,7 @@
+{
+  "showInput": false,
+  "showData": false,
+  "showTitles": false,
+  "titleSize": 5,
+  "command": "data.netcidrcontainsmatches.result"
+}
diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_strings/intro.md b/docs/docs/policy-reference/_examples/net/cidr_contains_strings/intro.md
@@ -0,0 +1 @@
+If both operands are string values the function is similar to `net.cidr_contains`.
diff --git a/.../_examples/net/cdir_contains1/policy.rego → ...les/net/cidr_contains_strings/policy.rego b/.../_examples/net/cdir_contains1/policy.rego → ...les/net/cidr_contains_strings/policy.rego
diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_strings/title.txt b/docs/docs/policy-reference/_examples/net/cidr_contains_strings/title.txt
@@ -0,0 +1 @@
+CIDR Match with String Ranges
diff --git a/docs/docs/policy-reference/_examples/rego/rule_metadata/config.json b/docs/docs/policy-reference/_examples/rego/rule_metadata/config.json
@@ -1,6 +1,7 @@
 {
-	"showInput": true,
-	"showData":  false,
-	"showTitles": false,
-	"command": "data.example"
+  "showInput": true,
+  "showData": false,
+  "showTitles": false,
+  "titleSize": 5,
+  "command": "data.example"
 }
diff --git a/docs/docs/policy-reference/_examples/rego/rule_metadata/intro.md b/docs/docs/policy-reference/_examples/rego/rule_metadata/intro.md
@@ -0,0 +1,4 @@
+The following policy will deny the given input because:
+
+- the `number` is greater than 5
+- the `subject` does not have the `admin` role
diff --git a/docs/docs/policy-reference/_examples/rego/rule_metadata/title.txt b/docs/docs/policy-reference/_examples/rego/rule_metadata/title.txt
@@ -0,0 +1 @@
+Rule Metadata
diff --git a/docs/docs/policy-reference/_examples/semver/isvalid/config.json b/docs/docs/policy-reference/_examples/semver/isvalid/config.json
@@ -1,6 +1,7 @@
 {
-	"showInput": false,
-	"showData":  false,
-	"showTitles": false,
-	"command": "data.semverisvalid"
+  "showInput": false,
+  "showData": false,
+  "showTitles": false,
+  "titleSize": 5,
+  "command": "data.semverisvalid"
 }
diff --git a/docs/docs/policy-reference/_examples/semver/isvalid/intro.md b/docs/docs/policy-reference/_examples/semver/isvalid/intro.md
@@ -0,0 +1,8 @@
+The `result := semver.is_valid(vsn)` function checks to see if a version
+string is of the form: `MAJOR.MINOR.PATCH[-PRERELEASE][+METADATA]`, where
+items in square braces are optional elements.
+
+:::warning
+When working with Go-style semantic versions, remember to remove the
+leading `v` character, or the semver string will be marked as invalid!
+:::
diff --git a/docs/docs/policy-reference/_examples/semver/isvalid/title.txt b/docs/docs/policy-reference/_examples/semver/isvalid/title.txt
@@ -0,0 +1 @@
+Example of semver.is_valid
diff --git a/docs/docs/policy-reference/_examples/time/time_format/config.json b/docs/docs/policy-reference/_examples/time/time_format/config.json
@@ -1,6 +1,7 @@
 {
-	"showInput": false,
-	"showData":  false,
-	"showTitles": false,
-	"command": "data.time_format"
+  "showInput": false,
+  "showData": false,
+  "showTitles": false,
+  "command": "data.time_format",
+  "titleSize": 5
 }
diff --git a/docs/docs/policy-reference/_examples/time/time_format/intro.md b/docs/docs/policy-reference/_examples/time/time_format/intro.md
@@ -0,0 +1 @@
+In OPA, we can parse a simple YYYY-MM-DD timestamp as follows:
diff --git a/docs/docs/policy-reference/_examples/time/time_format/title.txt b/docs/docs/policy-reference/_examples/time/time_format/title.txt
@@ -0,0 +1 @@
+Timestamp Parsing
diff --git a/docs/docs/policy-reference/_examples/tokens/sign/empty_json/config.json b/docs/docs/policy-reference/_examples/tokens/sign/empty_json/config.json
@@ -1,6 +1,7 @@
 {
-	"showInput": false,
-	"showData":  false,
-	"showTitles": false,
-	"command": "data.jwt.result"
+  "showInput": false,
+  "showData": false,
+  "showTitles": false,
+  "titleSize": 5,
+  "command": "data.jwt.result"
 }
diff --git a/docs/docs/policy-reference/_examples/tokens/sign/empty_json/title.txt b/docs/docs/policy-reference/_examples/tokens/sign/empty_json/title.txt
@@ -0,0 +1 @@
+Symmetric Key with empty JSON payload
diff --git a/docs/docs/policy-reference/_examples/tokens/sign/hmac/config.json b/docs/docs/policy-reference/_examples/tokens/sign/hmac/config.json
@@ -1,6 +1,7 @@
 {
-	"showInput": false,
-	"showData":  false,
-	"showTitles": false,
-	"command": "data.jwt.result"
+  "showInput": false,
+  "showData": false,
+  "showTitles": false,
+  "titleSize": 5,
+  "command": "data.jwt.result"
 }
diff --git a/docs/docs/policy-reference/_examples/tokens/sign/hmac/title.txt b/docs/docs/policy-reference/_examples/tokens/sign/hmac/title.txt
@@ -0,0 +1 @@
+Symmetric Key (HMAC with SHA-256)
diff --git a/docs/docs/policy-reference/_examples/tokens/sign/rsa/config.json b/docs/docs/policy-reference/_examples/tokens/sign/rsa/config.json
@@ -1,6 +1,7 @@
 {
-	"showInput": false,
-	"showData":  false,
-	"showTitles": false,
-	"command": "data.jwt.result"
+  "showInput": false,
+  "showData": false,
+  "showTitles": false,
+  "titleSize": 5,
+  "command": "data.jwt.result"
 }
diff --git a/docs/docs/policy-reference/_examples/tokens/sign/rsa/title.txt b/docs/docs/policy-reference/_examples/tokens/sign/rsa/title.txt
@@ -0,0 +1 @@
+RSA Key (RSA Signature with SHA-256)
diff --git a/docs/docs/policy-reference/_examples/tokens/sign/sign_raw/config.json b/docs/docs/policy-reference/_examples/tokens/sign/sign_raw/config.json
@@ -1,6 +1,7 @@
 {
-	"showInput": false,
-	"showData":  false,
-	"showTitles": false,
-	"command": "data.jwt.result"
+  "showInput": false,
+  "showData": false,
+  "showTitles": false,
+  "titleSize": 5,
+  "command": "data.jwt.result"
 }
diff --git a/docs/docs/policy-reference/_examples/tokens/sign/sign_raw/intro.md b/docs/docs/policy-reference/_examples/tokens/sign/sign_raw/intro.md
@@ -0,0 +1,3 @@
+If you need to generate the signature for a serialized token you an use the
+`io.jwt.encode_sign_raw` built-in function which accepts JSON serialized string
+parameters.
diff --git a/docs/docs/policy-reference/_examples/tokens/sign/sign_raw/title.txt b/docs/docs/policy-reference/_examples/tokens/sign/sign_raw/title.txt
@@ -0,0 +1 @@
+Raw Token Signing
diff --git a/docs/docs/policy-reference/_examples/tokens/verify/cert/config.json b/docs/docs/policy-reference/_examples/tokens/verify/cert/config.json
@@ -1,7 +1,8 @@
 {
-	"showInput": false,
-	"showData":  false,
-	"showTitles": false,
-	"showPlayground": false,
-	"command": "data.jwt"
+  "showInput": false,
+  "showData": false,
+  "showTitles": false,
+  "showPlayground": false,
+  "titleSize": 5,
+  "command": "data.jwt"
 }
diff --git a/docs/docs/policy-reference/_examples/tokens/verify/cert/intro.md b/docs/docs/policy-reference/_examples/tokens/verify/cert/intro.md
@@ -0,0 +1,3 @@
+This example shows a two-step process to verify the token signature and then decode it for
+further checks of the payload content. This approach gives more flexibility in verifying only
+the claims that the policy needs to enforce.
diff --git a/docs/docs/policy-reference/_examples/tokens/verify/cert/title.txt b/docs/docs/policy-reference/_examples/tokens/verify/cert/title.txt
@@ -0,0 +1 @@
+Certificate Verify
diff --git a/docs/docs/policy-reference/_examples/tokens/verify/cert_single/config.json b/docs/docs/policy-reference/_examples/tokens/verify/cert_single/config.json
@@ -1,7 +1,8 @@
 {
-	"showInput": false,
-	"showData":  false,
-	"showTitles": false,
-	"showPlayground": false,
-	"command": "data.jwt"
+  "showInput": false,
+  "showData": false,
+  "showTitles": false,
+  "showPlayground": false,
+  "titleSize": 5,
+  "command": "data.jwt"
 }
diff --git a/docs/docs/policy-reference/_examples/tokens/verify/cert_single/intro.md b/docs/docs/policy-reference/_examples/tokens/verify/cert_single/intro.md
@@ -0,0 +1,4 @@
+This next example shows doing the same token signature verification, decoding, and content checks
+but instead with a single call to `io.jwt.decode_verify`. Note that this gives less flexibility
+in validating the payload content as **all** claims defined in the JWT spec are verified with the
+provided constraints.
diff --git a/docs/docs/policy-reference/_examples/tokens/verify/cert_single/title.txt b/docs/docs/policy-reference/_examples/tokens/verify/cert_single/title.txt
@@ -0,0 +1 @@
+Certificate Verify Single
diff --git a/docs/docs/policy-reference/_examples/tokens/verify/jwks/config.json b/docs/docs/policy-reference/_examples/tokens/verify/jwks/config.json
@@ -1,7 +1,8 @@
 {
-	"showInput": false,
-	"showData":  false,
-	"showTitles": false,
-	"showPlayground": false,
-	"command": "data.jwt"
+  "showInput": false,
+  "showData": false,
+  "showTitles": false,
+  "showPlayground": false,
+  "titleSize": 5,
+  "command": "data.jwt"
 }
diff --git a/docs/docs/policy-reference/_examples/tokens/verify/jwks/intro.md b/docs/docs/policy-reference/_examples/tokens/verify/jwks/intro.md
@@ -0,0 +1,3 @@
+This example shows a two-step process to verify the token signature and then decode it for
+further checks of the payload content. This approach gives more flexibility in verifying only
+the claims that the policy needs to enforce.
diff --git a/docs/docs/policy-reference/_examples/tokens/verify/jwks/title.txt b/docs/docs/policy-reference/_examples/tokens/verify/jwks/title.txt
@@ -0,0 +1 @@
+JWKS Verify
diff --git a/docs/docs/policy-reference/_examples/tokens/verify/jwks_single/config.json b/docs/docs/policy-reference/_examples/tokens/verify/jwks_single/config.json
@@ -1,7 +1,8 @@
 {
-	"showInput": false,
-	"showData":  false,
-	"showTitles": false,
-	"showPlayground": false,
-	"command": "data.jwt"
+  "showInput": false,
+  "showData": false,
+  "showTitles": false,
+  "showPlayground": false,
+  "titleSize": 5,
+  "command": "data.jwt"
 }
diff --git a/docs/docs/policy-reference/_examples/tokens/verify/jwks_single/intro.md b/docs/docs/policy-reference/_examples/tokens/verify/jwks_single/intro.md
@@ -0,0 +1,4 @@
+This next example shows doing the token signature verification, decoding, and content checks
+all in one call using `io.jwt.decode_verify`. Note that this gives less flexibility in validating
+the payload content as **all** claims defined in the JWT spec are verified with the provided
+constraints.
diff --git a/docs/docs/policy-reference/_examples/tokens/verify/jwks_single/title.txt b/docs/docs/policy-reference/_examples/tokens/verify/jwks_single/title.txt
@@ -0,0 +1 @@
+JWKS Single Verify
diff --git a/docs/docs/policy-reference/_examples/tokens/verify/sign/config.json b/docs/docs/policy-reference/_examples/tokens/verify/sign/config.json
@@ -1,6 +1,7 @@
 {
-	"showInput": false,
-	"showData":  false,
-	"showTitles": false,
-	"command": "data.jwt"
+  "showInput": false,
+  "showData": false,
+  "showTitles": false,
+  "titleSize": 5,
+  "command": "data.jwt"
 }
diff --git a/docs/docs/policy-reference/_examples/tokens/verify/sign/intro.md b/docs/docs/policy-reference/_examples/tokens/verify/sign/intro.md
@@ -0,0 +1 @@
+This one demonstrates how to encode the and sign the same token contents as in the example above but with `io.jwt.encode_sign` instead of the `raw` variant.
diff --git a/docs/docs/policy-reference/_examples/tokens/verify/sign/title.txt b/docs/docs/policy-reference/_examples/tokens/verify/sign/title.txt
@@ -0,0 +1 @@
+Sign and Verify
diff --git a/docs/docs/policy-reference/_examples/tokens/verify/sign_raw/config.json b/docs/docs/policy-reference/_examples/tokens/verify/sign_raw/config.json
@@ -1,6 +1,7 @@
 {
-	"showInput": false,
-	"showData":  false,
-	"showTitles": false,
-	"command": "data.jwt"
+  "showInput": false,
+  "showData": false,
+  "showTitles": false,
+  "titleSize": 5,
+  "command": "data.jwt"
 }
diff --git a/docs/docs/policy-reference/_examples/tokens/verify/sign_raw/intro.md b/docs/docs/policy-reference/_examples/tokens/verify/sign_raw/intro.md
@@ -0,0 +1 @@
+This exambles demonstrates how to do this using the `io.jwt.encode_sign_raw` built-in:
diff --git a/docs/docs/policy-reference/_examples/tokens/verify/sign_raw/title.txt b/docs/docs/policy-reference/_examples/tokens/verify/sign_raw/title.txt
@@ -0,0 +1 @@
+Sign and Verify Raw
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		It may be useful to find all reachable paths from a root element. `graph.reachable_paths` can be used for this. Note that cyclical paths will terminate on the repeated node. If an element references a nonexistent element, the path will be terminated, and excludes the nonexistent node.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Either (or both) operand(s) may be an array, set, or object.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		The array/set/object elements may be arrays. In that case, the first element must be a valid CIDR/IP.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		If the operand is a set, the outputs are matching elements. If the operand is an object, the outputs are matching keys.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		If both operands are string values the function is similar to `net.cidr_contains`.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		In OPA, we can parse a simple YYYY-MM-DD timestamp as follows:
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		This one demonstrates how to encode the and sign the same token contents as in the example above but with `io.jwt.encode_sign` instead of the `raw` variant.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		This exambles demonstrates how to do this using the `io.jwt.encode_sign_raw` built-in: