Rego Policy Schema¶

Overview¶

This topic explains the Open Policy Agent (OPA) Rego policy used for application compatibility validation. The policy validates application dependencies and update eligibility before installation or updates can proceed.

What is OPA Rego?¶

Open Policy Agent (OPA) is a policy engine that enables policy-based control across your applications. Rego is the declarative policy language used by OPA to define rules and policies.

Key Characteristics¶

Declarative: You describe what should be true, not how to compute it
Rule-based: Policies are expressed as rules that evaluate to true or false
Data-driven: Decisions are made by evaluating input data against defined rules

File Structure¶

The Rego policy is divided into two main sections:

User Configuration¶

This is the only section users need to modify. It contains three configuration areas:

Application-to-Application Dependency Configuration¶

Defines which application(s) your app depends on and the version requirements.

Use app_dependency_config as an array. Each array item represents one dependency application. This allows you to define one or multiple dependency apps in the same configuration.

Field Descriptions:

APPLICATION_NAME: Display name of the dependency (e.g., "Databus")
APPLICATION_ID: Unique identifier (UUID), refer Getting Application ID
ALLOW_VERSION_GREATER_THAN: Versions strictly greater than this value are allowed
WARN_VERSION_EQUALS: Exact version that triggers a warning
BLOCK_VERSION_LESS_THAN: Versions strictly less than this value are blocked

If your application depends on multiple applications, add multiple objects to the app_dependency_config array. Each object defines the rules for one dependency application.

For an example with multiple dependency applications in array format, see Use Case 1a: Multiple Application Dependencies.

For a complete example configuration, see Use Case 1: Application-to-Application Dependency.

App Update Configuration¶

Defines which versions of your own app can update to the latest version.

Field Descriptions:

ALLOW_UPDATE_FROM_GREATER_THAN: Versions strictly greater than this value are allowed to update
WARN_UPDATE_FROM_EQUALS: Exact version that triggers a warning during update
BLOCK_UPDATE_FROM_LESS_THAN: Versions strictly less than this value are blocked from updating

For a complete example configuration, see Use Case 2: Application Update.

NOTICE

If any rule returns BLOCK, the final result is BLOCK, regardless of other results.

User-Facing Messages¶

Customizable messages shown to users during validation and these messages will be displayed in the IEM UI.

Available Placeholders:

{APPLICATION_NAME}: Name of the application
{INSTALLED_VERSION}: Current version on the device
{MINIMUM_REQUIRED_VERSION}: Required minimum version

Policy Execution Engine¶

The core policy logic that should not be modified by users. This section contains the rule engine and decision logic.

Key Rego Concepts and Keywords¶

package: Defines the namespace for organizing policy rules (e.g., package com.siemens.defaultruleset)
import: Imports external libraries and built-in functions (e.g., import rego.v1 provides semantic versioning functions)
:=: Assignment operator used to create variables, constants, and data structures
default: Sets a fallback value that is used when no other rules match the given conditions
if: Introduces conditional logic where all conditions in the rule body must evaluate to true
input: Built-in variable containing input data passed from external systems for policy evaluation
[item | source; conditions]: Array comprehension syntax for filtering and transforming data collections
[_]: Wildcard iterator used to traverse all elements in an array or object
semver.is_valid(): Validates that a version string follows semantic versioning format (e.g., "1.2.3")
semver.compare(): Compares two semantic versions, returning -1, 0, or 1 for less than, equal, or greater than
count(): Returns the number of elements in an array or object
concat(): Joins an array of strings with a specified separator into a single string
replace(): Substitutes placeholder text with actual values in string templates
else: Creates a chain of alternative rules that are evaluated in order until one matches

How the Policy Works¶

Scenario 1: Fresh Installation¶

When installing an app for the first time:

Check Application to Application Dependency: Validates that required dependency apps are installed with compatible versions
No Application Update Check: Skipped (app not previously installed)

Scenario 2: Application Update¶

When updating an existing app:

Check Application to Application Dependency: Validates dependencies
Check Application Update Eligibility: Validates the installed version can update to the new version

Common Use Cases¶

Use Case 1: Application-to-Application Dependency¶

Goal: Ensure Databus version greater than 3.2.2 is installed.

Configuration:

app_dependency_config := [
    {
        "APPLICATION_NAME": "Databus",
        "APPLICATION_ID": "d0e61067a4ad41aa9381b6c38774ec72",
        "ALLOW_VERSION_GREATER_THAN": "3.2.2",
        "WARN_VERSION_EQUALS": "3.2.2",
        "BLOCK_VERSION_LESS_THAN": "3.2.2"
    }
]

Outcomes:

Databus 3.3.0 installed → ALLOW
Databus 3.2.2 installed → WARN
Databus 3.2.1 installed → BLOCK
Databus not installed → BLOCK

Use Case 1a: Multiple Application Dependencies¶

Goal: Ensure both Databus and S7Connector are installed with compatible versions.

Configuration:

app_dependency_config := [
    {
        "APPLICATION_NAME": "Databus",
        "APPLICATION_ID": "d0e61067a4ad41aa9381b6c38774ec72",
        "ALLOW_VERSION_GREATER_THAN": "3.3.2",
        "WARN_VERSION_EQUALS": "3.3.2",
        "BLOCK_VERSION_LESS_THAN": "0.0.1"
    },
    {
        "APPLICATION_NAME": "S7Connector",
        "APPLICATION_ID": "e0e61067a4ad41aa9381b6c38774ec72",
        "ALLOW_VERSION_GREATER_THAN": "3.3.1",
        "WARN_VERSION_EQUALS": "3.3.1",
        "BLOCK_VERSION_LESS_THAN": "0.0.1"
    }
]

Outcomes:

Databus 3.3.3 and S7Connector 3.3.2 installed → ALLOW
Databus 3.3.2 and S7Connector 3.3.2 installed → WARN
Databus not installed or S7Connector 0.0.0 installed → BLOCK

In this example, both dependencies are checked during validation. If any dependency returns BLOCK, the final result is BLOCK.

Use Case 2: Application Update¶

Goal: Ensure smooth app updates by warning users or blocking upgrades from versions that are too old, as they may contain incompatible data.

Configuration:

app_update_config := {
    "ALLOW_UPDATE_FROM_GREATER_THAN": "3.0.12",
    "WARN_UPDATE_FROM_EQUALS": "3.0.12",
    "BLOCK_UPDATE_FROM_LESS_THAN": "3.0.11"
}

Outcomes:

Updating from 3.1.0 → ALLOW
Updating from 3.0.12 → WARN
Updating from 3.0.10 → BLOCK (requires fresh installation)