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.

$3

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).

$3

Primitive literals:

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

$3

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

$3

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.

$3

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.