Skip to main content

Object Built-ins

FunctionDescriptionOPAWasmSwiftJava
json.filter​

filtered := json.filter(object, paths)

Filters the object. For example: json.filter({"a": {"b": "x", "c": "y"}}, ["a/b"]) will result in {"a": {"b": "x"}}). Paths are not filtered in-order and are deduplicated before being evaluated.

Arguments:
object (object[any: any])

object to filter

paths (any<array[any<string, array[any]>], set[any<string, array[any]>]>)

JSON string paths

Returns:
filtered (object[any: any])

remaining data from object with only keys specified in paths

v0.17.0✓0.0.100.4.0
json.match_schema​

output := json.match_schema(document, schema)

Checks that the document matches the JSON schema. The pattern keyword is enforced using Go's RE2 regex dialect; schemas relying on ECMA-262 features that RE2 does not support (e.g. negative lookahead) will be rejected.

Arguments:
document (any<string, object[any: any]>)

document to verify by schema

schema (any<string, object[any: any]>)

schema to verify document by

Returns:
output (array<boolean, array[object<desc: string, error: string, field: string, type: string>]>)

output is of the form [match, errors]. If the document is valid given the schema, then match is true, and errors is an empty array. Otherwise, match is false and errors is an array of objects describing the error(s).

v0.50.0SDK✗0.4.0
json.patch​

output := json.patch(target, patches)

Patches an object according to RFC6902. For example: json.patch({"a": {"foo": 1}}, [{"op": "add", "path": "/a/bar", "value": 2}]) results in {"a": {"foo": 1, "bar": 2}. The patches are applied atomically: if any of them fails, the result will be undefined. Additionally works on sets, where a value contained in the set is considered to be its path.

Arguments:
target (any)

the object, array or set to patch

patches (array[object<op: string, path: any>[any: any]])

the JSON patches to apply

Returns:
output (any)

result obtained after consecutively applying all patch operations in patches

v0.25.0SDK0.0.100.4.0
json.remove​

output := json.remove(object, paths)

Removes paths from an object. For example: json.remove({"a": {"b": "x", "c": "y"}}, ["a/b"]) will result in {"a": {"c": "y"}}. Paths are not removed in-order and are deduplicated before being evaluated.

Arguments:
object (object[any: any])

object to remove paths from

paths (any<array[any<string, array[any]>], set[any<string, array[any]>]>)

JSON string paths

Returns:
output (object[any: any])

result of removing all keys specified in paths

v0.18.0✓0.0.100.4.0
json.verify_schema​

output := json.verify_schema(schema)

Checks that the input is a valid JSON schema object. The schema can be either a JSON string or an JSON object. The pattern keyword, if present, is compiled using Go's RE2 regex dialect; schemas relying on ECMA-262 features that RE2 does not support (e.g. negative lookahead) will be rejected.

Arguments:
schema (any<string, object[any: any]>)

the schema to verify

Returns:
output (array<boolean, any<null, string>>)

output is of the form [valid, error]. If the schema is valid, then valid is true, and error is null. Otherwise, valid is false and error is a string describing the error.

v0.50.0SDK✗0.4.0
object.filter​

filtered := object.filter(object, keys)

Filters the object by keeping only specified keys. For example: object.filter({"a": {"b": "x", "c": "y"}, "d": "z"}, ["a"]) will result in {"a": {"b": "x", "c": "y"}}).

Arguments:
object (object[any: any])

object to filter keys

keys (any<array[any], object[any: any], set[any]>)

keys to keep in object

Returns:
filtered (object[any: any])

remaining data from object with only keys specified in keys

v0.17.2✓0.0.90.1.0
object.get​

value := object.get(object, key, default)

Returns value of an object's key if present, otherwise a default. If the supplied key is an array, then object.get will search through a nested object or array using each key in turn. For example: object.get({"a": [{ "b": true }]}, ["a", 0, "b"], false) results in true.

Arguments:
object (object[any: any])

object to get key from

key (any)

key to lookup in object

default (any)

default to use when lookup fails

Returns:
value (any)

object[key] if present, otherwise default

v0.17.0✓0.0.10.1.0
object.keys​

value := object.keys(object)

Returns a set of an object's keys. For example: object.keys({"a": 1, "b": true, "c": "d") results in {"a", "b", "c"}.

Arguments:
object (object[any: any])

object to get keys from

Returns:
value (set[any])

set of object's keys

v0.47.0✓0.0.10.1.0
object.remove​

output := object.remove(object, keys)

Removes specified keys from an object.

Arguments:
object (object[any: any])

object to remove keys from

keys (any<array[any], object[any: any], set[any]>)

keys to remove from x

Returns:
output (object[any: any])

result of removing the specified keys from object

v0.17.2✓0.0.90.1.0
object.subset​

result := object.subset(super, sub)

Determines if an object sub is a subset of another object super.Object sub is a subset of object super if and only if every key in sub is also in super, and for all keys which sub and super share, they have the same value. This function works with objects, sets, arrays and a set of array and set.If both arguments are objects, then the operation is recursive, e.g. {"c": {"x": {10, 15, 20}} is a subset of {"a": "b", "c": {"x": {10, 15, 20, 25}, "y": "z"}. If both arguments are sets, then this function checks if every element of sub is a member of super, but does not attempt to recurse. If both arguments are arrays, then this function checks if sub appears contiguously in order within super, and also does not attempt to recurse. If super is array and sub is set, then this function checks if super contains every element of sub with no consideration of ordering, and also does not attempt to recurse.

Arguments:
super (any<array[any], object[any: any], set[any]>)

object to test if sub is a subset of

sub (any<array[any], object[any: any], set[any]>)

object to test if super is a superset of

Returns:
result (boolean)

true if sub is a subset of super, otherwise undefined

v0.42.0SDK0.0.90.1.0
object.union​

output := object.union(a, b)

Creates a new object of the asymmetric union of two objects. For example: object.union({"a": 1, "b": 2, "c": {"d": 3}}, {"a": 7, "c": {"d": 4, "e": 5}}) will result in {"a": 7, "b": 2, "c": {"d": 4, "e": 5}}.

Arguments:
a (object[any: any])

left-hand object

b (object[any: any])

right-hand object

Returns:
output (object[any: any])

a new object which is the result of an asymmetric recursive union of two objects where conflicts are resolved by choosing the key from the right-hand object b

v0.17.2✓0.0.10.1.0
object.union_n​

output := object.union_n(objects)

Creates a new object that is the asymmetric union of all objects merged from left to right. For example: object.union_n([{"a": 1}, {"b": 2}, {"a": 3}]) will result in {"b": 2, "a": 3}.

Arguments:
objects (array[object[any: any]])

list of objects to merge

Returns:
output (object[any: any])

asymmetric recursive union of all objects in objects, merged from left to right, where conflicts are resolved by choosing the key from the right-hand object

v0.37.0✓0.0.10.1.0
  • When keys are provided as an object only the top level keys on the object will be used, values are ignored. For example: object.remove({"a": {"b": {"c": 2}}, "x": 123}, {"a": 1}) == {"x": 123} regardless of the value for key a in the keys object, the following keys object gives the same result object.remove({"a": {"b": {"c": 2}}, "x": 123}, {"a": {"b": {"foo": "bar"}}}) == {"x": 123}.
  • The json string paths may reference into array values by using index numbers. For example with the object {"a": ["x", "y", "z"]} the path a/1 references y. Nested structures are supported as well, for example: {"a": ["x", {"y": {"y1": {"y2": ["foo", "bar"]}}}, "z"]} the path a/1/y1/y2/0 references "foo".
  • The json string paths support ~0, or ~1 characters for ~ and / characters in key names. It does not support - for last index of an array. For example the path /foo~1bar~0 will reference baz in { "foo/bar~": "baz" }.
  • The json string paths may be an array of string path segments rather than a / separated string. For example the path a/b/c can be passed in as ["a", "b", "c"].

Examples​

object.get​

object.get reads a key from an object and returns a default when the key is missing. The second argument can also be a path array to walk nested objects. That is useful for optional labels, annotations, or config keys that callers are allowed to omit.

Reading optional labels with a default

Kubernetes objects and API payloads often omit optional fields. object.get reads a key (or a nested path) and returns a default when it is missing, so the rest of the policy does not need extra existence checks. Using a path array also covers the case where an intermediate field like labels is undefined.

Here, workloads without an env label are treated as dev.

policy.rego
package play

# object.get(object, key, default) — key may also be a path array, which
# still returns the default when an intermediate field (like labels) is missing.
env_of(workload) := object.get(workload, ["labels", "env"], "dev")

# Only production workloads need a team label.
deny contains msg if {
	some w in input.workloads
	env_of(w) == "prod"
	not w.labels.team
	msg := sprintf("production workload %q is missing labels.team", [w.name])
}

envs := {w.name: env_of(w) | some w in input.workloads}
Output
{
  "deny": [
    "production workload \"frontend\" is missing labels.team"
  ],
  "envs": {
    "frontend": "prod",
    "scratch": "dev"
  }
}
Loading...
input.json
{
  "workloads": [
    {
      "name": "frontend",
      "labels": {
        "app": "web",
        "env": "prod"
      }
    },
    {
      "name": "scratch",
      "labels": {
        "app": "jobs"
      }
    }
  ]
}
data.json
{}

Open in OPA Playground