How Are Policies Defined in CoSec? The JSON Schema Explained

CoSec defines authorization policies as JSON documents that must validate against the CoSec Policy Schema in schema/cosec-policy.schema.json, requiring metadata fields like category, tenantId, and type alongside an array of statements that specify actions, effects, and optional conditions.

The ahoo-wang/cosec repository implements a policy-based access control (PBAC) system where authorization rules are declared as structured JSON documents. Understanding how policies are defined in CoSec requires examining the JSON Schema that governs every policy document, from global conditions to individual statement evaluation. This schema-driven approach ensures type safety and consistent validation across all authorization decisions.

The CoSec Policy Schema Structure

At the core of CoSec's authorization model lies schema/cosec-policy.schema.json, which mandates specific fields for every policy document. According to the schema definition, a valid policy must include metadata properties that identify the rule set and operational scope.

Required Policy Metadata

The schema defines seven top-level fields that control policy identification and execution:

• id: An optional unique identifier for the policy (string)
• category: A required string for logical grouping of related policies
• name: A required human-readable label for the policy
• description: A required string documenting the policy's purpose
• tenantId: A required string identifying the tenant that owns the policy
• type: A required enumeration limited to global, system, or custom as defined in the schema at lines 51-57
• condition: An optional global condition referencing condition.schema.json that must evaluate to true before any statements are processed
• statements: A required array of statement objects that contain the actual access control rules

Policy Statements and Access Rules

The statements array contains the executable authorization logic. Each statement object in the array follows the definition specified in schema/cosec-policy.schema.json lines 35-40 and supports fine-grained access control through action and effect definitions.

Statement Structure

Every statement within the array must conform to the following structure:

• name: An optional string label for debugging and documentation
• effect: The authorization result, defaulting to allow but supporting deny as defined in the schema's definitions/effect reference (lines 65-68)
• action: A required reference to action.schema.json specifying the resource or API operation being protected
• condition: An optional reference to condition.schema.json that refines when the statement applies

The schema requires at least the action field to be present in every statement (lines 75-78).

External Schema References

CoSec modularizes complex logic through separate schema files. The condition and action definitions live outside the main policy schema, enabling reusable expressions across multiple policies.

According to the source code, condition.schema.json defines logical expressions for attribute matching and role checks, while action.schema.json specifies flexible action patterns including resource-based and API-based operations. These schemas are referenced through JSON Schema $ref pointers in the main policy definition.

Practical Policy Examples

The repository includes test fixtures that demonstrate valid policy structures. Located at cosec-core/src/test/resources/cosec-policy/test-policy.json, these examples illustrate real-world authorization patterns.

Minimal Custom Policy

A basic policy allowing read access to documents:

{
  "category": "demo",
  "name": "DemoPolicy",
  "description": "Demonstrates a simple allow rule",
  "tenantId": "tenant-123",
  "type": "custom",
  "statements": [
    {
      "name": "AllowRead",
      "effect": "allow",
      "action": {
        "type": "resource",
        "resource": "document",
        "operation": "read"
      }
    }
  ]
}

Policy with Global and Statement Conditions

A system-level policy restricting delete operations to admin users from specific IP ranges:

{
  "category": "secure",
  "name": "SecurePolicy",
  "description": "Only users in group 'admin' may delete",
  "tenantId": "tenant-XYZ",
  "type": "system",
  "condition": {
    "type": "equals",
    "lhs": "${request.ip}",
    "rhs": "10.0.0.0/8"
  },
  "statements": [
    {
      "name": "AllowDeleteIfAdmin",
      "effect": "allow",
      "action": {
        "type": "resource",
        "resource": "document",
        "operation": "delete"
      },
      "condition": {
        "type": "contains",
        "lhs": "${principal.groups}",
        "rhs": "admin"
      }
    },
    {
      "effect": "deny"
    }
  ]
}

Summary

• CoSec policies are JSON documents validated against schema/cosec-policy.schema.json in the ahoo-wang/cosec repository
• Required fields include category, name, description, tenantId, type, and the statements array
• The type field must be one of global, system, or custom as enforced by the schema
• Statements contain the actual authorization logic through action specifications and effect determinations (allow/deny)
• Optional condition fields at both the policy and statement levels support attribute-based access control (ABAC) patterns
• Complex conditions and actions are defined in separate schema files (condition.schema.json and action.schema.json) for modularity

Frequently Asked Questions

What is the CoSec Policy Schema?

The CoSec Policy Schema is a JSON Schema definition located at schema/cosec-policy.schema.json that dictates the structure and validation rules for all authorization policies in the CoSec framework. It enforces required metadata fields and defines the relationship between policies, statements, conditions, and actions.

What are the required fields for a CoSec policy?

Every CoSec policy must include category, name, description, tenantId, type, and statements. The type field accepts only global, system, or custom values. While the id field is optional, the condition field at the policy level is optional but recommended for global access constraints.

How do conditions work in CoSec policies?

Conditions in CoSec follow the definitions in condition.schema.json and evaluate logical expressions against request attributes. A policy-level condition acts as a global gate that must pass before any statements are evaluated, while statement-level conditions determine whether that specific rule applies to the current request. Both support expressions like equality checks, containment operations, and attribute matching.

Where can I find example CoSec policies?

Production-ready examples exist in the repository at cosec-core/src/test/resources/cosec-policy/test-policy.json. These test fixtures demonstrate valid policy structures including complex conditionals and multi-statement configurations that developers can reference when authoring their own authorization rules.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}