Upgrading to 0.20

Oso’s 0.20 release is larger than usual as it includes a number of new features around authorization modeling, enforcement, and data filtering.

To migrate to 0.20 from 0.15, the previous stable release, follow the steps in this guide.

Parenthesize or operations

The or operator has had its precedence lowered to be consistent with other programming languages. Existing policies using or should be updated where necessary to group or operations using parentheses:

To migrate, rewrite:

foo(a, b, c) if a and b or c;


foo(a, b, c) if a and (b or c);

We have temporarily made policies that combine and and or without parentheses raise warnings in order to avoid silent changes. To silence the warning, add parentheses.

Consolidate loadFile() calls into a single loadFiles() call

As of 0.20, all Polar policies must be loaded in one fell swoop. To facilitate this, Oso.loadFile() has been deprecated and replaced with Oso.loadFiles() , which loads multiple Polar policy files at once.


Calling loadFile(), loadFiles(), or loadStr() more than once is now an error.

Continued use of loadFile() will result in deprecation warnings printed to the console. loadFile() will be removed in a future release.

To migrate, rewrite:



oso.loadFiles(new String[] {"main.polar", "repository.polar"})

Migrating from Polar Roles to the new resource block syntax

The 0.20 release introduces resource blocks for expressing role-based (RBAC) and relationship-based (ReBAC) access control logic in a concise, readable syntax.

For a taste of the new resource block syntax, see the Build Role-Based Access Control (RBAC) guide.

The previous Polar Roles feature has been removed, and we encourage all users to upgrade to the new syntax, which supports a superset of the functionality of the previous feature.

If you are using Polar Roles with a previous version of Oso and want to upgrade to the 0.20 release, please reach out via Slack or schedule a 1-on-1 with an engineer from the core team.

Migrate from isAllowed() to authorize()

The 0.20 release introduces Oso.authorize() , a new method that supplants Oso.isAllowed() as the preferred API for resource-level enforcement.

The methods' return values are different: isAllowed() returns a boolean and expects you to translate false into an authorization failure, but authorize() raises an Oso authorization error, which you can translate into your own error type.

To migrate, rewrite:

if (!oso.isAllowed("Ariadne", "assist", "Theseus")) {
    // handle authorization failure (probably by raising an error)


try {
    oso.authorize("Ariadne", "assist", "Theseus");
} catch (ForbiddenException | NotFoundException e) {
    // handle failures (probably by raising your own error types)

Set up a 1x1 with an Oso Engineer

Our team is happy to help you get started with Oso. If you'd like to learn more about using Oso in your app or have any questions about this guide, schedule a 1x1 with an Oso engineer.

Was this page useful?