Policy Decision Language

This repository contains a small rule language for evaluating JSON-like data.

Syntax Guide

Rules must be prefixed with allow if or deny if.

Data Model

Rules evaluate against a JSON-like object (the "root"). Paths access nested fields using dot notation:

• subject.id
• resource.tags
• context.date

Arrays can be checked with has (see below).

Literals

Primitive literals:

• Strings: "..." or '...'
• Numbers: integers or decimals (7, -3, 3.14)
• Booleans: true, false
• Dates: YYYY-MM-DD (treated as UTC dates)

Operators

Comparison operators:

• is (equality)
• greater_than (numbers or dates)
• less_than (numbers or dates)
• contains (string contains substring)
• starts_with (string prefix)
• ends_with (string suffix)
• has (arrays; value or object match)

Logical operators:

• not
• and
• or

Precedence (highest to lowest):

1. Parentheses ( ... )
2. not
3. and
4. or

has Semantics

has supports two forms:

1. Array of primitive values:

resource.tags has "internal"

2. Array of objects: evaluate the inner expression with each element as the root:

  subject.relations has (
  role is "employee"
  and subject.type is "entity"
)

The has expression is true if any array element matches.

Examples

Basic comparisons:

allow if subject.id is "123"
allow if resource.classification less_than 7
allow if context.date greater_than 2025-12-11

String operators:

allow if resource.type contains "file"
allow if resource.type starts_with "fi"
allow if resource.type ends_with "le"

Logical composition:

allow if (subject.active is true and subject.type is "entity") or action.name is "share"

Full sample:

allow if (
  subject.id is "123"
  and not subject.type is "entity"
  or (
      subject.active is false
      and subject.relations has (
          role is "employee"
          and subject.type is "entity"
        )
    )
)
and (action.name is "share" and action.scopes has "read")
and resource.classification less_than 7
and resource.tags has "internal"
and context.date greater_than 2025-12-11

Usage

Exports:

• parse(input) -> AST
• validate(ast, data) -> { valid, errors }
• evaluate(ast, data) -> true/false/null
• evaluateAll(rules, data) -> true/false
• findRules(data, rules) -> array of PDL strings

Scripts

• npm run build:grammar compiles grammar.ne into grammar.js
• npm run test:pdl runs the PDL test harness

Notes

• Missing paths cause validation errors.
• Type mismatches (e.g. greater_than with a non-number/non-date) cause validation errors.
• Dates are parsed as UTC midnight and compared by timestamp.
• allow if returns true when the condition is true, otherwise null.
• deny if returns false when the condition is true, otherwise null.
• evaluateAll returns false if any rule evaluates to false or if all rules evaluate to null.
• evaluateAll returns true if there is at least one true and no false.
• findRules returns the subset of rules that reference at least one existing path in the provided data.
• You can use https://kuselan84.github.io/policy-dl-web/ to compose your rules interactively.
• Minimal PDP server that evaluates JSON to rules is at https://github.com/kuselan84/policy-dl-pdp.