Clarifying intended usage of object.get for defensive policies

[vaish123-fullstck]

Hi folks,

While learning Rego, I spent some time experimenting with object.get and wanted to sanity-check my understanding before proposing any documentation changes.

From hands-on testing, it seems object.get is primarily intended for:

• defensive access (avoiding undefined errors),
• safely handling missing or optional fields,
• and supporting deep/nested lookups via path arrays.

I personally understood this only after trial & error and running small local examples.
Reading the current docs, it wasn’t immediately obvious to me:

• when to prefer object.get over direct access (input.foo.bar),
• or that it’s meant to prevent undefined access in dynamic inputs.

Before opening any PR, I wanted to ask:

• Is this the intended mental model for object.get?
• Would maintainers welcome a small example or clarification in the docs, or is this considered implicit knowledge?

Happy to follow whatever guidance makes most sense here.
Thanks!

cc @charlieegan3

[charlieegan3]

Hey, thanks for opening the discussion here. it would be nice to get an example of the path functionality in object.get documented on this page: https://www.openpolicyagent.org/docs/policy-reference/builtins/object

Generally we like examples to be based on 'real' rego tasks, do you have an example from your domain that might make sense to others?

[vaish123-fullstck]

Thanks for the clarification.

A real use-case I’ve encountered while learning Rego is defensive access to user attributes derived from auth/JWT input, where fields may be optional.

For example:

role := object.get(input.user, ["profile", "role"], "guest")

This allows policies to safely handle missing user, profile, or role fields while keeping the intent explicit.

If this sounds useful, I can draft a small PlaygroundExample for the object builtins page based on this pattern.

[vaish123-fullstck]

That's a fair point, @anderseknert—in my last example, the 'undefined' behavior of a direct reference did achieve the same result.

The real value I’m seeing is for rule continuity. If I use a direct reference and the path is missing, the entire rule stops. With object.get, I can provide an explicit fallback (like a default ["guest"] list) so that subsequent logic can still execute.

For example, this allows a policy to successfully grant 'guest' access even if the identity data is completely missing from the input:

package example

import future.keywords.if
import future.keywords.in

default allow := false

# allowing the 'in' check to run even if the path is missing.
allow if {
    roles := object.get(input, ["request", "context", "identity", "claims", "roles"], ["guest"])
    "guest" in roles
}

If I focus the documentation example on this 'Defined Fallback' pattern—specifically for handling missing nested data without terminating the rule—would that be a more useful addition?"

[anderseknert]

Better! Although preferably used in a rule that isn't named allow, suggesting any user without roles assigned will be granted access.

user_is_guest if {
    "guest" in object.get(input, ["request", "context", "identity", "claims", "roles"], ["guest"])
}

# could then do something like
allow if {
    input.request.path[0] == "public"
    user_is_guest
}

Although for cases like this, using default assignment is IMHO the better choice.

default user_roles := ["guest"]

user_roles := input.request.context.identity.claims.roles

allow if {
    input.request.path[0] == "public"
    "guest" in user_roles
}

Perhaps better to use an example where the value is used for something more than a boolean condition, and where you want evaluation to go on with the default value used. Something like this, maybe?

deny contains reason if {
    some user in input.users

    email := object.get(user, "email", "no email address")
    not endswith(email, "@acmecorp.com")

    reason := concat(" ", ["User must have AcmeCorp email address, got", email])
}

Side notes:

• If you're using OPA 1.0 or later, you don't need those future imports
• If you're on an earlier OPA version than 1.0, use import rego.v1 instead of import future.xxx
• Use Regal. It's a great tool for learning Rego!

[vaish123-fullstck]

That makes perfect sense, using the fallback in the output makes the documentation's intent much clearer.

I’ve drafted a scenario involving API Tiers. It demonstrates how object.get prevents a rule from failing when a tier claim is missing, allowing the policy to explicitly treat the user as free and provide a descriptive error message.

I’ve also updated it to rego.v1 as suggested:

package example

import rego.v1

# This example shows how object.get provides a fallback value
# to ensure evaluation continues when optional metadata is missing.

deny contains reason if {
    some user in input.users

    # Safely retrieve the account tier, defaulting to "free" if missing
    tier := object.get(user, ["auth", "claims", "tier"], "free")

    # Logic continues using the fallback value
    tier == "free"
    input.request.method == "POST"

    # The fallback value is used in the final denial message
    reason := concat(" ", ["POST requests are not allowed for account tier:", tier])
}

I've verified this in the Playground. When the tier claim is missing, object.get ensures the deny message is still generated with the free fallback, whereas a direct reference would have caused the rule to fail silently.

Does this example do the job for the built-ins page?

[anderseknert]

Please don’t use an LLM to engage in a conversation with me. That is both against our stated policy and any sense of decency. Should you want to carry on this conversation and potentially contributing to the docs, it’ll have to be as your own self.

[charlieegan3]

For reference, our AI policy is documented here: https://www.openpolicyagent.org/docs/contrib-code#ai-guidelines