Allowl Language

Overview

Allowl provides the ability to process logical queries based on facts about a user or contents of a wallet. This page describes the grammar of an Allowl query and the capabilities of this language.

The language takes its name from the concept of an "Allow List" which can be used to gate access to services. The potential uses for the language extend beyond this basic purpose.

Query And Result

Allowl takes a query as input and yeilds a result. Both the query and result are JSON objects that encapsulate a JSON expression. See the Allowl Query page for details on issuing a query via the REST API.

Query

Result

Expression

Evaluation Of Expressions

Allowl expressions are always valid JSON. Expressions that appear in queries may contain JSON values that refer to Allowl operations. When evaluated, these expressions may trigger substitutions to different values. If the original expression does not contain any reference to an Allowl operation, it will retain its literal JSON value when evaluated.

For example, the expression "Hello, world!" is a valid JSON string which does not contain any reference to an Allowl operation. Therefore, if it is provided as a query, it will produce a result with the same literal value.

{"query": "Hello, world!"}

{"result": "Hello, world!"}

Allowl Operations

An expression that can evaluate to something different from its literal self must contain a reference to at least one of the following types of Allowl operations:

• Reading An Envirionment Variable
• Calling A Macro
• Calling A Function

Environment_Variable

Environment Variables take the form of a JSON string value prefixed with the dollar sign '$' character. A limited number of these variables are defined by the system and there is no provision for a user of the language to define more of them.

Runtime_Environment_Variable

The string "$runtime" can serve as an environment variable by evaluating to a JSON object describing the runtime environment of the Allowl service. For example:

{"query": "$runtime"}

{"result": {
  "version": "proto-5",
  "vendor": "Vatom, Inc."
}}

If the envirionment variable refers to a JSON object, a property of that environment variable can be read via the dot '.' operator as in the following example:

{"query": "$runtime.vendor"}

{"result": "Vatom, Inc."}

It_Environment_Variable

The environment variable referenced via the string "$it" plays a special role in accessing behind-the-scenes intermediate values during certain operations. It is particularly useful in the following macros:

• Boolean_Macro_Any – Is expression B true for any element of A?
• Array_Macro_Filter – Filters the elements of an array
• Macro_Select – Selects the property of an object

Their documentation includes details for using the It_Environment_Variable in specific cases.

Macro

Macros take the form of a JSON object with either one or two properties. The first of these properties is a key-value pair in which the key identifies the macro by name and the value expression represents a parameter. Depending on the macro, a second property containing another parameter may either be required or optionally allowed.

The Boolean Macros page documents eleven macros that always evaluate to boolean.
The Other Macros page documents four macros that can evaluate to non-boolean values.

Macro_Name

Macro_Second_Parameter_Name

Function

Functions take the form of a JSON object with at least two properties. The first property is a key-value pair containing the key "fn" representing a Function and a value giving the name of the function. The remaining properties are key-value pairs corresponding to named parameters that the particular function expects. All functions evaluate to an array result.

The Functions page documents the five built-in Allowl functions.

Function_Name

Parameter_Name

Credits

Grammar consistency testing and generation of images representing elements of the Allowl grammar were aided by Gunther Rademacher's open source Railroad Diagram Generator program. An online version is hosted at bottlecaps.de/rr/. The software was used with permission and according to its Apache License terms.