docs: add examples for numbers, types, and uuid builtins by VedantMadane · Pull Request #9042 · open-policy-agent/opa

VedantMadane · 2026-08-18T16:31:49Z

Adds interactive policy-reference examples for numbers (abs, ceil/floor/round, min/max), types (type_name, is_string), and uuid.rfc4122.

Fixes #3786

netlify · 2026-08-18T16:34:27Z

✅ Deploy Preview for openpolicyagent ready!

Name	Link
🔨 Latest commit	`473a96e`
🔍 Latest deploy log	https://app.netlify.com/projects/openpolicyagent/deploys/6a89a1e69be436000823feed
😎 Deploy Preview	https://deploy-preview-9042--openpolicyagent.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

charlieegan3

Hi, thanks for this, please review the comments and push changes as new commits. Please avoid rebasing to aid reviewing.

charlieegan3 · 2026-08-19T10:52:58Z

@@ -0,0 +1,5 @@
+{
+  "cpu_units": 250,


This one is a bit strange.

charlieegan3 · 2026-08-19T10:54:13Z

+free_gib := floor(input.free_bytes / (1024 * 1024 * 1024))
+
+# Nearest whole percent for a utilization gauge.
+util_pct := round(input.used / input.total * 100)


🤨 input.used / input.total * 100 is still 70

charlieegan3 · 2026-08-19T10:55:17Z

@@ -0,0 +1,5 @@
+<!-- markdownlint-disable MD041 -->
+
+`ceil`, `floor`, and `round` convert fractional values to whole numbers.


Generally examples are for a single built in.

charlieegan3 · 2026-08-19T10:56:13Z

+package play
+
+# Clamp requested replicas into [min_allowed, max_allowed].
+clamped := min([input.max_allowed, max([input.min_allowed, input.requested])])


Please review how your examples appear in the UI, this line is too long really.

charlieegan3 · 2026-08-19T10:57:04Z

+
+deny contains msg if {
+        type_name(input.replicas) != "number"
+        msg := sprintf("replicas must be a number, got %s", [type_name(input.replicas)])


should use string interpolation in head

charlieegan3 · 2026-08-19T10:57:47Z

+
+`type_name` returns the Rego type of a value as a string (`"string"`,
+`"number"`, `"object"`, and so on). It is useful when input may arrive with
+the wrong JSON type and you want a clear deny message.


Might be nice to link to schema validation functions too here.

charlieegan3 · 2026-08-19T10:58:53Z

@@ -0,0 +1,5 @@
+<!-- markdownlint-disable MD041 -->
+
+`is_string` (and the related `is_*` helpers) test a value's type and return a


Same, a link to schema validation functions is a good idea.

charlieegan3 · 2026-08-19T11:00:52Z

@@ -0,0 +1,3 @@
+package play
+
+request_id := uuid.rfc4122(sprintf("%s/%s", [input.tenant, input.name]))


please visually check line lengths in UI, run make dev in docs

Shortened lines across policy definitions to ensure clean rendering without horizontal scrollbars in the playground UI.

charlieegan3 · 2026-08-19T11:02:17Z

+
+`uuid.rfc4122` generates a random RFC 4122 UUID. The string argument is a
+**cache key** within a single policy evaluation: the same key returns the same
+UUID for the duration of that decision, which is useful for synthetic request


the same key returns the same UUID for the duration of that decision

I think we need an example that shows that

Updated the example policy to explicitly demonstrate that calling uuid.rfc4122 with the same key returns the exact same UUID within the evaluation (same_key_match == true), while different keys yield distinct UUIDs.

Add interactive policy-reference examples for abs, ceil/floor/round, min/max, type_name, is_string, and uuid.rfc4122. Skip golden output for non-deterministic uuid.rfc4122. Address review: fix description (same key within a single evaluation), update example policy for same-key caching vs distinct keys, shorten playground lines, remove UTF-8 BOM from MDX files. Fixes open-policy-agent#3786 Signed-off-by: Vedant Madane <6527493+VedantMadane@users.noreply.github.com>

charlieegan3 · 2026-08-20T08:51:46Z

Hi there, please can we avoid force pushing while I review? it makes my life harder as I need to review the entire diff again each time.

charlieegan3 · 2026-08-20T08:55:36Z

@@ -0,0 +1,3 @@
+{
+  "request_id": "7f1aa7a5-4d88-4ab5-aa0b-2c48e9ff07cc"
+}


Outdated, please update.

charlieegan3 · 2026-08-20T08:57:30Z

+
+# Different key returns a different UUID:
+other_id := uuid.rfc4122("req-2")
+diff_key_match := req_id1 == other_id


This example would be better if it showed a real use case like returning a request ID in a real policy decision in. The policy can still be trivial, but it should be more than just "here is some rego that runs the function".

These examples are meant to highlight good use cases for functions and show pseudo realistic examples to help guide users when selecting functions to use in their policies.

charlieegan3 · 2026-08-20T08:59:46Z

+deny contains msg if {
+	type_name(input.replicas) != "number"
+	got := type_name(input.replicas)
+	msg := sprintf("replicas must be a number, got %s", [got])


Please see

#9042 (comment)

let's avoid calling type_name twice in the same rule too.

charlieegan3 · 2026-08-20T09:02:31Z

@@ -0,0 +1,5 @@
+<!-- markdownlint-disable MD041 -->
+
+`is_string` (and the related `is_*` helpers) test a value's type and return a


is_ functions are not "helpers", they are built in functions.

charlieegan3 · 2026-08-20T09:04:00Z

@@ -0,0 +1,6 @@
+{
+  "labels": {
+    "app": "checkout",


this example would be more 'real' if it looked a bit like a k8s resource but and the labels/annotations were bools, and not strings.

I'd use label/annnot like public-egress: true or similar boolean key/value.

Updated to a realistic Kubernetes resource example where an unquoted boolean annotation (public-egress: true) is flagged by is_string.

charlieegan3 · 2026-08-20T09:05:29Z

+package play
+
+# Clamp requested replicas between minimum and maximum bounds.
+clamped := min([


This is another example it'd be nice to have as more of a policy rather than some rego that just runs the function. can you think of a policy use case that involves clamping?

Updated to a policy that clamps requested replicas between high-availability minimums (min_replicas := 2) and cost limits (max_replicas := 10).

charlieegan3 · 2026-08-20T09:06:20Z

+{
+  "expected": 100,
+  "observed": 97,
+  "tolerance": 5


tolerance should likely be in the policy, not the input, otherwise this example is mostly ok.

Moved olerance := 5 into the policy rule body.

- Update is_string example to validate Kubernetes annotations with boolean values - Update min/max example to clamp replicas within policy bounds - Move tolerance threshold into policy body for abs example Signed-off-by: Vedant Madane <6527493+VedantMadane@users.noreply.github.com>

VedantMadane · 2026-08-21T07:23:48Z

Thanks for the feedback @charlieegan3! I have addressed all review comments in an incremental commit (no force pushing/rebasing). Ready for another look.

charlieegan3 · 2026-08-24T09:47:12Z

-`abs` returns the absolute value of a number. Policies often use it when a
-delta may be negative but only the magnitude matters for a threshold check.
+`abs` returns the absolute value of a number. Policies often use it when
+comparing an observed metric against an expected baseline where deviation


I'd rather the term 'value', not metric here.

charlieegan3 · 2026-08-24T09:47:51Z

@@ -1,5 +1,4 @@
 {
  "expected": 100,


it still seems strange to me that the expected is part of the input here, exp and tolerance seem to me like part of the policy.

charlieegan3 · 2026-08-24T09:48:31Z

@@ -1 +1 @@
-Normalize a signed delta with abs
+Enforce measurement tolerance with abs


Enforce measurement tolerance with abs

This is quite... abstract. These examples are meant to be grounded in real use cases to aid understanding.

charlieegan3 · 2026-08-24T09:49:44Z

@@ -1 +1 @@
-Clamp a replica count with min and max
+Clamp replica limits with min and max


Min and Max are actually not in the numbers group, they are in aggregates

e.g.

package play example := min(["z", "2", "a", "1"])

charlieegan3 · 2026-08-24T09:52:12Z

+deny contains msg if {
+	some key, val in input.metadata.annotations
+	not is_string(val)
+	msg := sprintf("annotation %q must be a string value", [key])


Please use string interpolation.

charlieegan3 · 2026-08-24T09:58:09Z

Hi there, I have left some more comments on the new edits.

I have addressed all review comments in an incremental commit

There are still ~10 comments I'd hoped for a response or input on. Please have another look.

charlieegan3 · 2026-08-24T09:59:19Z

We are up to 33 comments here and 3 rounds of review. Let's try and make the next one the final one as this ought to be a relatively simple change. 🙏

charlieegan3 requested changes Aug 19, 2026

View reviewed changes

VedantMadane force-pushed the docs/builtin-examples-numbers-types-uuid branch from 7309b2b to e5e17f1 Compare August 20, 2026 07:18

charlieegan3 reviewed Aug 20, 2026

View reviewed changes

VedantMadane added 2 commits August 21, 2026 07:09

Merge branch 'main' into docs/builtin-examples-numbers-types-uuid

8d90ff2

VedantMadane force-pushed the docs/builtin-examples-numbers-types-uuid branch from b7fc32e to 473a96e Compare August 22, 2026 13:19

charlieegan3 reviewed Aug 24, 2026

View reviewed changes

		@@ -0,0 +1,5 @@
		<!-- markdownlint-disable MD041 -->

		`ceil`, `floor`, and `round` convert fractional values to whole numbers.

		@@ -0,0 +1,5 @@
		<!-- markdownlint-disable MD041 -->

		`is_string` (and the related `is_*` helpers) test a value's type and return a

		@@ -0,0 +1,3 @@
		package play

		request_id := uuid.rfc4122(sprintf("%s/%s", [input.tenant, input.name]))

		@@ -1 +1 @@
		Normalize a signed delta with abs
		Enforce measurement tolerance with abs

		@@ -1 +1 @@
		Clamp a replica count with min and max
		Clamp replica limits with min and max

Uh oh!

Conversation

VedantMadane commented Aug 18, 2026

Uh oh!

netlify Bot commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for openpolicyagent ready!

Uh oh!

charlieegan3 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

charlieegan3 commented Aug 20, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

VedantMadane commented Aug 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

charlieegan3 commented Aug 24, 2026

Uh oh!

charlieegan3 commented Aug 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

netlify Bot commented Aug 18, 2026 •

edited

Loading