Policy Capabilities

The capabilities define the built-in functions and other language features that policies may depend on.

OpaDotNet allows you to define OPA capabilities during compilation in three ways, all of them configured via CompilationParameters:

using OpaDotNet.Wasm;
using OpaDotNet.Compilation.Abstractions;
using OpaDotNet.Compilation.Cli;

CapabilitiesVersion option

Defines capabilities used to validate policies against a specific version of OPA.

For example:

var compiler = new RegoCliCompiler();

var parameters = new CompilationParameters
{
    // Validate policies against built-ins available in OPA v0.53.1.
    CapabilitiesVersion = "v0.53.1",
    Entrypoints = ["example/hello"],
};

await using var policy = await compiler.CompileBundleAsync("quickstart", parameters, cancellationToken);

Is equivalent to the following command:

opa build -t wasm -b ./quickstart -e example/hello --capabilities v0.53.1

Custom capabilities file

Defines capabilities file used to validate policies against.

var compiler = new RegoCliCompiler();

var parameters = new CompilationParameters
{
    // Validate policies against built-ins defined in the capabilities file only.
    CapabilitiesFilePath = Path.Combine("builtins", "capabilities.json"),
    Entrypoints = ["custom_builtins/zero_arg"],
};

Important

Capabilities file applicable only to policy bundles.

Note

Capabilities file used on its own replaces the whole list of available built-ins, so it must declare every built-in the policy uses, including operators like = (eq). To only add built-ins atop of standard ones use merged capabilities.

Is equivalent to the following command:

opa build -t wasm -b ./builtins -e custom_builtins/zero_arg --capabilities builtins/capabilities.json

Merged capabilities

If you want to add capabilities (for example, custom built-in functions) atop of standard capabilities you can use both options described above:

var compiler = new RegoCliCompiler();

var parameters = new CompilationParameters
{
    // Built-ins from OPA v0.53.1 capabilities...
    CapabilitiesVersion = "v0.53.1",

    // ...merged with built-ins defined in the capabilities file.
    CapabilitiesFilePath = Path.Combine("builtins", "capabilities.json"),
    Entrypoints = ["custom_builtins/zero_arg"],
};

await using var policy = await compiler.CompileBundleAsync("builtins", parameters, cancellationToken);

In this case OpaDotNet will merge v0.53.1 capabilities with capabilities defined in capabilities.json file.

Important

Merged capabilities applicable only to policy bundles.