Policy Versions

A policy version is an immutable snapshot of the approved rules within a policy at a given point in time. Versions are the unit of deployment — you don’t deploy individual rules, you deploy a version.

Why version?

Versioning lets you control exactly which set of rules is active in each environment. It enables progressive rollout, comparison between rule sets, and instant rollback if something goes wrong.

---

Creating a Version

To create a version:

1. Open the policy and click Versions in the toolbar
2. Click Create Version
3. Enter a version number in semantic versioning format (e.g., 1.0.0, 1.1.0, 2.0.0)
4. Optionally add a label describing the changes (e.g., “Added break-glass rules”)
5. Click Create

The version captures a snapshot of all rules currently in Approved status. Rules in Draft or other statuses are not included.

Prerequisites

• The policy must have at least one primary resource configured in its entity types
• The policy must contain at least one rule in Approved status

---

Version Lifecycle

Every version follows a linear lifecycle:

DRAFT ──→ VALIDATED ──→ PUBLISHED ──→ DEPRECATED

DRAFT

The initial state when a version is created. The snapshot has been captured but not yet verified.

Available actions: Validate, Delete

VALIDATED

The version has passed syntax and consistency checks. It is ready to be deployed to an environment.

Available actions: Deploy, Export, Compare, Delete (if not deployed)

PUBLISHED

The version has been deployed to at least one environment. Publication happens automatically on the first deployment — there is no manual “Publish” action.

Available actions: Deploy (to other environments), Export, Compare

Caution

Published versions cannot be deleted. This ensures that deployed rule sets always remain traceable.

DEPRECATED

The version is marked as outdated. A newer version should be used going forward. Deprecated versions can still be deployed (e.g., for rollback purposes) but signal that they are superseded.

Available actions: Deploy, Export, Compare

---

Actions by Status

Action	DRAFT	VALIDATED	PUBLISHED	DEPRECATED
Validate	✅	—	—	—
Deploy to environment	—	✅	✅	✅
Export (Rego / Cedar)	—	✅	✅	✅
Compare with another version	—	✅	✅	✅
Delete	✅*	✅*	—	—

* Only if the version has no active deployments.

---

Validating a Version

Validation runs syntax and consistency checks against the captured rule snapshot. To validate:

1. Open the Versions dialog
2. Click Validate on a DRAFT version
3. If validation succeeds, the version moves to VALIDATED status
4. If validation fails, error details are displayed

Validation is a prerequisite for deployment.

---

Comparing Versions

You can compare any two versions of the same policy side by side to understand what changed.

1. Open the Versions dialog
2. Click Compare and select the two versions
3. The comparison view shows:
   • Added rules — rules present in the target version but not in the source
   • Removed rules — rules present in the source but not in the target
   • Modified rules — rules present in both but with changed fields (with a diff of the specific changes)
   • Unchanged count — number of rules identical in both versions

This is useful before promoting a version to a higher environment, or when investigating a rollback.

---

Exporting a Version

Versions in VALIDATED, PUBLISHED, or DEPRECATED status can be exported as policy engine-ready files:

Format	File Extension	Target Engine
Rego	.rego	Open Policy Agent (OPA)
Cedar Schema	.json	Amazon Verified Permissions (AVP)
Cedar Policies	.cedar	Amazon Verified Permissions (AVP)

To export, click the download button on a version card and select the desired format. The file is downloaded directly to your machine.

Note

Exported files are generated from the immutable version snapshot. They will always produce the same output regardless of any subsequent rule changes in the policy.

---

Version Numbering

Big ACL uses semantic versioning (SemVer) for version numbers:

MAJOR.MINOR.PATCH

• MAJOR — Increment for breaking changes to your authorization logic (e.g., new deny rules that restrict previously allowed access)
• MINOR — Increment for backward-compatible additions (e.g., new permit rules for a new feature)
• PATCH — Increment for minor corrections (e.g., fixing a condition typo)

The version number is informational — Big ACL does not enforce SemVer semantics. Choose a convention that works for your team and apply it consistently.