Docs/Policies/Structure

Policy Structure

Complete reference for MAPL policy syntax. Policies are JSON documents that define what resources an identity can access and what constraints apply.

Basic Structure

A MAPL policy is a JSON document with the following structure:

policy.json

{
  "policy_id": "unique-identifier",
  "name": "Human-readable name",
  "version": "1.0",
  "description": "Detailed description",
  "scope": "global | company | bu | team | user | app",
  "extends": "parent-policy-id",

  "resources": ["resource-patterns"],
  "denied_resources": ["denial-patterns"],

  "attestations": ["attestation-requirements"],

  "constraints": {
    "rate_limit": 100,
    "parameters": { /* per-resource constraints */ },
    "denied_parameters": { /* blocked patterns */ },
    "attestations": { /* attestation metadata */ }
  }
}

Core Fields

policy_idrequired

Unique identifier for this policy. Convention: {scope}:{name}

Examples:

company:acme - Organization-level policy
bu:finance - Business unit policy
team:analysts - Team policy
user:alice - User policy
app:trading-service - Service agent policy

nameoptional

Human-readable display name for the policy. Used in UIs and logs.

Example: "Trading Team Policy"

extendsoptional

Parent policy ID to inherit from. Child policies can only further restrict, never expand permissions.

Example: "extends": "team:engineering"

scopeoptional

Policy level in the hierarchy. Helps with validation and tooling.

globalcompanybuteamuserapp

global is the root. The bottom level ("caller") can be eitheruser (human users) or app (service agents).

resourcesrequired

Array of operation patterns this policy allows access to. In MAPL, resources ARE operations.

"resources": [
  "llm:openai/chat.completions",
  "llm:anthropic/*",
  "tool:database/query"
]

denied_resourcesoptional

Explicit blocks that override allows. Denials always win in conflicts.

"denied_resources": [
  "admin:**",
  "*.secret",
  "*.password"
]

Resource Patterns & Wildcards

MAPL supports hierarchical resource naming with wildcards for flexible pattern matching:

Pattern	Meaning	Matches
llm:openai/chat.completions	Exact match	Only that specific operation
llm:openai/*	Single-level wildcard	chat.completions, embeddings
llm:openai/**	Multi-level wildcard	All OpenAI ops at any depth
llm:**	All LLMs	Any provider, any operation
**	Everything	All resources (use with caution!)

Why Resources ARE Operations

In traditional systems you have resource + action (e.g., /etc/passwd + read). In MAPL, the resource path includes the operation: llm:openai/chat.completions. This eliminates M×N rule explosion and makes wildcards work naturally.

Constraints Object

The constraints object contains parameter validations, denial patterns, and attestation metadata:

constraints structure

"constraints": {
  "rate_limit": 100,  // requests per minute

  "parameters": {
    "llm:openai/chat.completions": {
      "model": ["gpt-3.5-turbo", "gpt-4"],
      "max_tokens": {"max": 2000},
      "temperature": {"type": "number", "range": [0.0, 1.0]}
    }
  },

  "denied_parameters": {
    "llm:**": {
      "prompt": ["*DROP TABLE*", "*rm -rf*"]
    }
  },

  "attestations": {
    "trade_approved": {
      "approval_criteria": "role:manager",
      "timeout": 300,
      "time_to_live": 3600
    }
  }
}

See Parameter Constraints for detailed constraint type reference.

Attestations Array

The attestations field specifies required proofs before an operation can proceed. Supports conditional syntax:

"attestations": [
  "identity_verified",                              // Always required
  "trade_approved::{params.amount > 5000}",         // Conditional
  "manager_override::{params.priority == 'urgent'}" // Conditional
]

See Attestations for detailed documentation on internal, external, and conditional attestations.

Complete Example

user-alice.json

{
  "policy_id": "user:alice",
  "version": "1.0",
  "description": "Alice - Financial Analyst",
  "scope": "user",
  "extends": "team:analysts",

  "resources": [
    "llm:openai/chat.completions",
    "tool:database/query",
    "tool:calculator/*"
  ],

  "denied_resources": [
    "admin:**",
    "*.secret",
    "data:executive/*"
  ],

  "attestations": [
    "identity_verified",
    "manager_approval::{params.amount > 10000}"
  ],

  "constraints": {
    "rate_limit": 50,
    "parameters": {
      "llm:openai/chat.completions": {
        "model": ["gpt-3.5-turbo"],
        "max_tokens": {"max": 500},
        "temperature": {"type": "number", "max": 0.7}
      },
      "tool:database/query": {
        "limit": {"type": "integer", "max": 1000}
      }
    },
    "attestations": {
      "manager_approval": {
        "approval_criteria": "role:manager",
        "timeout": 300,
        "time_to_live": 3600,
        "one_time": true
      }
    }
  }
}

Policy Structure

Basic Structure

Core Fields

Resource Patterns & Wildcards

Why Resources ARE Operations

Constraints Object

Attestations Array

Complete Example

Next Steps

Writing Policies

Inheritance

Parameter Constraints

Advanced Patterns