1"use strict";(self.webpackChunkopa_website=self.webpackChunkopa_website||[]).push([[6699],{28453:(e,n,r)=>{r.d(n,{R:()=>o,x:()=>l});var a=r(96540);const i={},s=a.createContext(i);function o(e){const n=a.useContext(s);return a.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function l(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:o(e.components),a.createElement(s.Provider,{value:n},e.children)}},91147:(e,n,r)=>{r.r(n),r.d(n,{assets:()=>h,contentTitle:()=>d,default:()=>f,frontMatter:()=>c,metadata:()=>a,toc:()=>x});const a=JSON.parse('{"id":"policy-reference/index","title":"Policy Reference","description":"This page is a reference for details of the Rego language and its syntax. See","source":"@site/docs/policy-reference/index.md","sourceDirName":"policy-reference","slug":"/policy-reference/","permalink":"/docs/policy-reference/","draft":false,"unlisted":false,"tags":[],"version":"current","sidebarPosition":1,"frontMatter":{"title":"Policy Reference","sidebar_label":"Overview","sidebar_position":1},"sidebar":"docsSidebar","previous":{"title":"Policy Language","permalink":"/docs/policy-language"},"next":{"title":"contains","permalink":"/docs/policy-reference/keywords/contains"}}');var i=r(74848),s=r(28453),o=r(20454),l=r(56347);r(96540);function t(e){(0,o.A)(e);var n=(0,l.zy)(),r=n.hash.replace("#","").split("-");if(3==r.length&&"builtin"==r[0]){var a="/docs/policy-reference/builtins/"+r[1]+n.hash;return(0,i.jsx)(l.rd,{to:a})}return(0,i.jsx)("div",{})}const c={title:"Policy Reference",sidebar_label:"Overview",sidebar_position:1},d=void 0,h={},x=[{value:"Assignment and Equality",id:"assignment-and-equality",level:2},{value:"Lookup",id:"lookup",level:2},{value:"Arrays",id:"arrays",level:3},{value:"Objects",id:"objects",level:3},{value:"Sets",id:"sets",level:3},{value:"Iteration",id:"iteration",level:2},{value:"Arrays",id:"arrays-1",level:3},{value:"Objects",id:"objects-1",level:3},{value:"Sets",id:"sets-1",level:3},{value:"Advanced",id:"advanced",level:3},{value:"For All",id:"for-all",level:2},{value:"Rules",id:"rules",level:2},{value:"Constants",id:"constants",level:3},{value:"Conditionals (Boolean)",id:"conditionals-boolean",level:3},{value:"Conditionals",id:"conditionals",level:3},{value:"Incremental",id:"incremental",level:3},{value:"Ordered (Else)",id:"ordered-else",level:3},{value:"Functions (Boolean)",id:"functions-boolean",level:3},{value:"Functions (Conditionals)",id:"functions-conditionals",level:3},{value:"Reference Heads",id:"reference-heads",level:3},{value:"Tests",id:"tests",level:2},{value:"Built-in Functions",id:"built-in-functions",level:2},{value:"Reserved Names & Keywords",id:"reserved-names--keywords",level:2},{value:"Grammar",id:"grammar",level:2}];function u(e){const n={a:"a",admonition:"admonition",code:"code",em:"em",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",ul:"ul",...(0,s.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(t,{}),"\n",(0,i.jsxs)(n.p,{children:["This page is a reference for details of the Rego language and its syntax. See\nthe guided ",(0,i.jsx)(n.a,{href:"./policy-language",children:"Policy Language"})," page for a walked introduction.\nThere are also detailed sections for\n",(0,i.jsx)(n.a,{href:"./policy-reference/builtins",children:"built-in functions"})," as well as examples for\nspecific keywords such as\n",(0,i.jsx)(n.a,{href:"./policy-reference/keywords/contains",children:(0,i.jsx)(n.code,{children:"contains"})}),",\n",(0,i.jsx)(n.a,{href:"./policy-reference/keywords/if",children:(0,i.jsx)(n.code,{children:"if"})})," and\n",(0,i.jsx)(n.a,{href:"./policy-reference/keywords/default",children:(0,i.jsx)(n.code,{children:"default"})}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"assignment-and-equality",children:"Assignment and Equality"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:'# assign variable x to value of field foo.bar.baz in input\nx := input.foo.bar.baz\n\n# check if variable x has same value as variable y\nx == y\n\n# check if variable x is a set containing "foo" and "bar"\nx == {"foo", "bar"}\n\n# OR\n\n{"foo", "bar"} == x\n'})}),"\n",(0,i.jsx)(n.h2,{id:"lookup",children:"Lookup"}),"\n",(0,i.jsx)(n.h3,{id:"arrays",children:"Arrays"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:'# lookup value at index 0\nval := arr[0]\n\n # check if value at index 0 is "foo"\n"foo" == arr[0]\n\n# find all indices i that have value "foo"\n"foo" == arr[i]\n\n# lookup last value\nval := arr[count(arr)-1]\n\n# with keywords\nsome 0, val in arr # lookup value at index 0\n0, "foo" in arr # check if value at index 0 is "foo"\nsome i, "foo" in arr # find all indices i that have value "foo"\n'})}),"\n",(0,i.jsx)(n.h3,{id:"objects",children:"Objects"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:'# lookup value for key "foo"\nval := obj["foo"]\n\n# check if value for key "foo" is "bar"\n"bar" == obj["foo"]\n\n# OR\n\n"bar" == obj.foo\n\n# check if key "foo" exists and is not false\n
1obj.foo\n\n# check if key assigned to variable k exists\nk := "foo"\nobj[k]\n\n# check if path foo.bar.baz exists and is not false\nobj.foo.bar.baz\n\n# check if path foo.bar.baz, foo.bar, or foo does not exist or is false\nnot obj.foo.bar.baz\n\n# with keywords\no := {"foo": false}\n# check if value exists: the expression will be true\nfalse in o\n# check if value for key "foo" is false\n"foo", false in o\n'})}),"\n",(0,i.jsx)(n.h3,{id:"sets",children:"Sets"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:'# check if "foo" belongs to the set\na_set["foo"]\n\n# check if "foo" DOES NOT belong to the set\nnot a_set["foo"]\n\n# check if the array ["a", "b", "c"] belongs to the set\na_set[["a", "b", "c"]]\n\n# find all arrays of the form [x, "b", z] in the set\na_set[[x, "b", z]]\n\n# with keywords\n"foo" in a_set\nnot "foo" in a_set\nsome ["a", "b", "c"] in a_set\nsome [x, "b", z] in a_set\n'})}),"\n",(0,i.jsx)(n.h2,{id:"iteration",children:"Iteration"}),"\n",(0,i.jsx)(n.h3,{id:"arrays-1",children:"Arrays"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:"# iterate over indices i\narr[i]\n\n# iterate over values\nval := arr[_]\n\n# iterate over index/value pairs\nval := arr[i]\n\n# with keywords\nsome val in arr # iterate over values\nsome i, _ in arr # iterate over indices\nsome i, val in arr # iterate over index/value pairs\n"})}),"\n",(0,i.jsx)(n.h3,{id:"objects-1",children:"Objects"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:"# iterate over keys\nobj[key]\n\n# iterate over values\nval := obj[_]\n\n# iterate over key/value pairs\nval := obj[key]\n\n# with keywords\nsome val in obj # iterate over values\nsome key, _ in obj # iterate over keys\nsome key, val in obj # key/value pairs\n"})}),"\n",(0,i.jsx)(n.h3,{id:"sets-1",children:"Sets"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:"# iterate over values\nset[val]\n\n# with keywords\nsome val in set\n"})}),"\n",(0,i.jsx)(n.h3,{id:"advanced",children:"Advanced"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:"# nested: find key k whose bar.baz array index i is 7\nfoo[k].bar.baz[i] == 7\n\n# simultaneous: find keys in objects foo and bar with same value\nfoo[k1] == bar[k2]\n\n# simultaneous self: find 2 keys in object foo with same value\nfoo[k1] == foo[k2]; k1 != k2\n\n# multiple conditions: k has same value in both conditions\nfoo[k].bar.baz[i] == 7; foo[k].qux > 3\n"})}),"\n",(0,i.jsx)(n.h2,{id:"for-all",children:"For All"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:"# assert no values in set match predicate\ncount({x | set[x]; f(x)}) == 0\n\n# assert all values in set make function f true\ncount({x | set[x]; f(x)}) == count(set)\n\n# assert no values in set make function f true (using negation and helper rule)\nnot any_match\n\n# assert all values in set make function f true (using negation and helper rule)\nnot any_not_match\n"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:"# with keywords\nany_match if {\n some x in set\n f(x)\n}\n\nany_not_match if {\n some x in set\n not f(x)\n}\n"})}),"\n",(0,i.jsx)(n.h2,{id:"rules",children:"Rules"}),"\n",(0,i.jsxs)(n.p,{children:["In the examples below ",(0,i.jsx)(n.code,{children:"..."})," represents one or more conditions."]}),"\n",(0,i.jsx)(n.h3,{id:"constants",children:"Constants"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:"a := {1, 2, 3}\nb := {4, 5, 6}\nc := a | b\n"})}),"\n",(0,i.jsx)(n.h3,{id:"conditionals-boolean",children:"Conditionals (Boolean)"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:"# p is true if ...\np := true { ... }\n\n# OR\n# with keywords\np if { ... }\n\n# OR\np { ... }\n"})}),"\n",(0,i.jsx)(n.h3,{id:"conditionals",children:"Conditionals"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:"# with keywords\ndefault a := 1\na := 5 if { ... }\na := 100 if { ... }\n"})}),"\n",(0,i.jsx)(n.h3,{id:"incremental",children:"Incremental"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:"# a_set will c
1ontain values of x and values of y\na_set[x] { ... }\na_set[y] { ... }\n\n# alternatively, with keywords\na_set contains x if { ... }\na_set contains y if { ... }\n\n# a_map will contain key->value pairs x->y and w->z\na_map[x] := y if { ... }\na_map[w] := z if { ... }\n"})}),"\n",(0,i.jsx)(n.h3,{id:"ordered-else",children:"Ordered (Else)"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:"# with keywords\ndefault a := 1\na := 5 if { ... }\nelse := 10 if { ... }\n"})}),"\n",(0,i.jsx)(n.h3,{id:"functions-boolean",children:"Functions (Boolean)"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:"# with keywords\nf(x, y) if {\n ...\n}\n\n# OR\n\nf(x, y) := true if {\n ...\n}\n"})}),"\n",(0,i.jsx)(n.h3,{id:"functions-conditionals",children:"Functions (Conditionals)"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:'# with keywords\nf(x) := "A" if { x >= 90 }\nf(x) := "B" if { x >= 80; x < 90 }\nf(x) := "C" if { x >= 70; x < 80 }\n'})}),"\n",(0,i.jsx)(n.h3,{id:"reference-heads",children:"Reference Heads"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:'# with keywords\nfruit.apple.seeds = 12 if input == "apple" # complete document (single value rule)\n\nfruit.pineapple.colors contains x if x := "yellow" # multi-value rule\n\nfruit.banana.phone[x] = "bananular" if x := "cellular" # single value rule\nfruit.banana.phone.cellular = "bananular" if true # equivalent single value rule\n\nfruit.orange.color(x) = true if x == "orange" # function\n'})}),"\n",(0,i.jsxs)(n.p,{children:["For reasons of backwards-compatibility, partial sets need to use ",(0,i.jsx)(n.code,{children:"contains"})," in\ntheir rule heads, i.e."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:'fruit.box contains "apples" if true\n'})}),"\n",(0,i.jsx)(n.p,{children:"whereas"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:'fruit.box[x] if { x := "apples" }\n'})}),"\n",(0,i.jsxs)(n.p,{children:["defines a ",(0,i.jsx)(n.em,{children:"complete document rule"})," ",(0,i.jsx)(n.code,{children:"fruit.box.apples"})," with value ",(0,i.jsx)(n.code,{children:"true"}),".\nThe same is the case of rules with brackets that don't contain dots, like"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:'box[x] if { x := "apples" } # => {"box": {"apples": true }}\nbox2[x] { x := "apples" } # => {"box": ["apples"]}\n'})}),"\n",(0,i.jsxs)(n.p,{children:["For backwards-compatibility, rules ",(0,i.jsx)(n.em,{children:"without"})," if and without ",(0,i.jsx)(n.em,{children:"dots"})," will be interpreted\nas defining partial sets, like ",(0,i.jsx)(n.code,{children:"box2"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"tests",children:"Tests"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rego",children:"# it's common for tests to have a _test in their package name\npackage foo.bar_test # contains tests for package foo.bar\n\n# define a rule that starts with test_, these will be run with opa test\ntest_NAME { ... }\n\n# override input.foo value using the 'with' keyword to mock different inputs\ndata.foo.bar.deny with input.foo as {\"bar\": [1,2,3]}}\n"})}),"\n",(0,i.jsx)(n.admonition,{type:"tip",children:(0,i.jsxs)(n.p,{children:["Please see ",(0,i.jsx)(n.a,{href:"./policy-testing",children:"Policy Testing"})," for an in depth look into writing\nand running Rego tests with OPA."]})}),"\n",(0,i.jsx)(n.h2,{id:"built-in-functions",children:"Built-in Functions"}),"\n",(0,i.jsxs)(n.p,{children:["Rego's built-in functions offer policy authors tools for common policy\noperations like JWT validation, signature verification, among many others.\nThe reference documentation for these functions can be found under\n",(0,i.jsx)(n.a,{href:"./policy-reference/builtins",children:"Built-in Functions"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"reserved-names--keywords",children:"Reserved Names & Keywords"}),"\n",(0,i.jsx)(n.p,{children:"The following words are reserved and cannot be used as variable names or rule\nnames:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"and"})," (",(0,i.jsx)(n.a,{href:"./policy-reference/keywords/logical#and",children:"Examples"}),")"]}),"\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.code,{children:"as"})}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"contains"})," (",(0,i.jsx)(n.a,{href:"./policy-reference/keywords/contains",children:"Examples"}),")"]}),"\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.code,{children:"data"})}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"default"})," (",(0,i.jsx)(n.a,{href:"./policy-reference/keywords/default",children:"Examples"}),")"]}),"\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.code,{children:"else"})}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"every"})," (",(0,i.jsx)(n.a,{href:"./policy-reference/keywords/every",children:"Examples"}),")"]}),"\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.code,{children:"false"})}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"if"})," (",(0,i.jsx)(n.a,{href:"./policy-reference/keywords/if",children:"Examples"}),")"]}),"\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.code,{children:"in"})}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"import"})," (",(0,i.jsx)(n.a,{href:"./policy-reference/keywords/import",children:"Examples"}),")"]}),"\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.code,{children:"input"})}),"\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.code,{children:"package"})}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"not"})," (",(0,i.jsx)(n.a,{href:"./policy-reference/keywords/not",children:"Examples"}),")"]}),"\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.code,{children:"null"})}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"or"})," (",(0,i.jsx)(n.a,{href:"./policy-reference/keywords/logical#or",children:"Examples"}),")"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"some"})," (",(0,i.jsx)(n.a,{href:"./policy-reference/keywords/some",children:"Examples"}),")"]}),"\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.code,{children:"true"})}),"\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.code,{children:"with"})}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"grammar",children:"Grammar"}),"\n",(0,i.jsx)(n.p,{children:"Rego\u2019s syntax is defined by the following grammar:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ebnf",children:'module = package { import } policy\npackage = "package" ref\nimport = "import" ref [ "as" var ]\npolicy = { rule }\nrule = [ "default" ] rule-head { rule-body }\nrule-head = ( ref | var ) ( rule-head-set | rule-head-obj | rule-head-func | rule-head-comp )\nrule-head-comp = [ assign-operator term ] [ "if" ]\nrule-head-obj = "[" term "]" [ assign-operator term ] [ "if" ]\nrule-head-func = "(" rule-args ")" [ assign-operator term ] [ "if" ]\nrule-head-set = "contains" term [ "if" ] | "[" term "]"\nrule-args = term { "," term }\nrule-body = [ "else" [ assign-operator term ] [ "if" ] ] ( "{" query "}" ) | literal\nquery = literal { ( ";" | ( [CR] LF ) ) literal }\nliteral = ( some-decl | expr | logical-expr | "not" ( expr | "{" query "}" | "(" logical-expr ")" ) ) { with-modifier }\nlogical-expr = logical-operand ( "and" | "or" ) logical-operand { ( "and" | "or" ) logical-operand }\nlogical-operand = [ "not" ] ( term | expr-call | expr-infix | expr-parens | unary-expr | "{" query "}" | "(" logical-expr { with-modifier } ")" )\nwith-modifier = "with" term "as" term\nsome-decl = "some" term { "," term } { "in" expr }\nexpr = term | expr-call | expr-infix | expr-every | expr-parens | unary-expr\nexpr-call = var [ "." var ] "(" [ expr { "," expr } ] ")"\nexpr-infix = expr infix-operator expr\nexpr-every = "every" var { "," var } "in" ( term | expr-call | expr-infix ) "{" query "}"\nexpr-parens = "(" expr ")"\nunary-expr = "-" expr\nmembership = term [ "," term ] "in" term\nterm = ref | var | scalar | array | object | set | membership | array-compr | object-compr | set-compr\narray-compr = "[" term "|" query "]"\nset-compr = "{" term "|" query "}"\nobject-compr = "{" object-item "|" query "}"\ninfix-operator = assign-operator | bool-operator | arith-operator | bin-operator\nbool-operator = "==" | "!=" | "<" | ">" | ">=" | "<="\narith-operator = "+" | "-" | "*" | "/" | "%"\nbin-operator = "&" | "|"\nassign-operator = ":=" | "="\nref = ( var | array | object | set | array-compr | object-compr | set-compr | expr-call ) { ref-arg }\nref-arg = ref-arg-dot | ref-arg-brack\nref-arg-brack = "["
1( scalar | var | array | object | set | "_" ) "]"\nref-arg-dot = "." var\nvar = ( ALPHA | "_" ) { ALPHA | DIGIT | "_" }\nscalar = string | NUMBER | TRUE | FALSE | NULL\nstring = STRING | raw-string | template-string\ntemplate-string = "$" ( \'"\' { CHAR-\'"\' | template-expr } \'"\' | "`" { CHAR-"`" | template-expr } "`" )\ntemplate-expr = "{" ( ref | var | scalar | array | object | set | array-compr | object-compr | set-compr | expr-call | expr-infix | expr-parens | unary-expr ) "}"\nraw-string = "`" { CHAR-"`" } "`"\narray = "[" term { "," term } "]"\nobject = "{" object-item { "," object-item } "}"\nobject-item = ( scalar | ref | var ) ":" term\nset = empty-set | non-empty-set\nnon-empty-set = "{" term { "," term } "}"\nempty-set = "set(" ")"\n'})}),"\n",(0,i.jsxs)(n.p,{children:["The grammar defined above makes use of the following syntax. See ",(0,i.jsx)(n.a,{href:"https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form",children:"the Wikipedia page on EBNF"})," for more details:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{children:"[] optional (zero or one instances)\n{} repetition (zero or more instances)\n| alternation (one of the instances)\n() grouping (order of expansion)\nSTRING JSON string\nNUMBER JSON number\nTRUE JSON true\nFALSE JSON false\nNULL JSON null\nCHAR Unicode character\nALPHA ASCII characters A-Z and a-z\nDIGIT ASCII characters 0-9\nCR Carriage Return\nLF Line Feed\n"})})]})}function f(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(u,{...e})}):u(e)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.