# Policy Structure Overview

This document outlines the format and structure of a Cerbos policy representing permissions and roles for API resources.

## API Version
The schema defines the API version to ensure backward compatibility and structured development.

- **apiVersion**: The constant must align with `api.cerbos.dev/v1`.

## Metadata
Use this section to define metadata such as descriptions and identifiers related to the policy:

- **description**: A brief overview of the policy.
- **disabled**: A boolean flag indicating if the policy is currently active.

## Principal Policy
The principal policy provides definitions for user roles and their access rights.

### Structure of Principal Policy
- **principal**: Identifies the principal entity (user, group, etc.).
- **version**: Version of the principal policy.

#### Example:
```json
{
  "principal": "user123",
  "rules": [
    {
      "resource": "resourceName",
      "actions": ["read", "write"]
    }
  ],
  "scope": "global"
}
```

## Resource Policy
The resource policy defines the actions and controls associated with specific resources.

### Structure of Resource Policy
- **resource**: Identifies the resource being controlled (e.g., a database, file).
- **rules**: Outlines specific access rules for the resource.

#### Example:
```json
{
  "resource": "document",
  "rules": [
    {
      "actions": ["view", "edit"],
      "effect": "EFFECT_ALLOW"
    }
  ]
}
```

## Role Definitions
Define roles and their inheritance to facilitate a structured access control mechanism.

### Structure of Role Definition
- **name**: The name of the role.
- **parentRoles**: A list defining any parent roles this role inherits from.

#### Example:
```json
{
  "name": "admin",
  "parentRoles": ["user"]
}
```

## Variables
Variables provide a mechanism to define dynamic elements within policies, allowing for flexible policies that can adapt to various contexts.

### Structure of Variables
- **import**: Specifies variables that are imported from other schemas or definitions.
- **local**: Defines local variables that may be used within the policy as permissions.

### Conclusion
This structured overview provides a path for creating detailed and robust access policies using the Cerbos framework, thus ensuring that defined permissions adhere to organizational security policies.