Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

The Dogwood Guide

Complete documentation for the Dogwood policy language — its syntax, its temporal expressions and information providers, its schemas, and the Rust API for evaluating policies.

The guide is organized so the core language comes first, read through the lens of a fixed setup: the event schema, the information providers, and the macro library are all taken as given. The Advanced topics section then covers how each of those fixed inputs is built.

A. Introduction to the language

The core language, assuming the event schema, providers, and macros are given.

  • Introduction — what Dogwood is, the problem it solves, and the concepts you need. Read this first if you are new.
  • Getting started — your first schema, policy, and authorization, end to end, with runnable code.
  • The policy language — the core (Cedar-derived) syntax: the action schema (entity/action declarations and the context.input / context.output convention), permit/forbid, the (principal, action, resource) scope, when/unless conditions, and the full expression language.
  • Temporal expressions — the when temporal { … } sublanguage: reasoning about event history with formerly, previous, since, windows, exists, tp, and the count / sum aggregations.
  • Information providers — consulting values computed on demand: calling a provider as a plain Cedar call inside an ordinary when { … } clause, and how its output composes with a condition.
  • Calling macros — invoking def cedar and def temporal macros: where a call may appear and what shape its arguments take.

B. Advanced topics

Deep dives on the three fixed inputs the core language takes as given, plus MCP schema generation.

  • The event schema — the event-schema DSL (.dwschema): the four selectors, spreads, named fields, nested records, pins, decision kinds, and the default request/response schema.
  • The provider schema — declaring providers: the providers.json format, the Rhai implementation contract (sandbox, host functions, decimal, the net feature), output methods, no-implementation providers, and the guardrails { … } sugar.
  • Macros — defining macros: def cedar / def temporal, the two parameter sigils, hygiene, every rejection rule, and the macro library.
  • Generating the action schema from an MCP manifest — a Dogwood action schema is an MCP tool manifest; the manifest format, the JSON→Cedar type mapping, and the Drupe template.

C. Running Dogwood

  • The command line — the dogwood CLI: validate, replay, lower, check-parse, and the schema subcommands, driven over plain files. The quickest way to check a policy or watch a temporal policy decide across a trace, with no Rust.
  • The API and workflow — the Rust API reference and end-to-end workflow: ServiceSchema/PolicySchema → LoweredPolicySet → Validator → Authorizer → Event → Response.

D. Reference

  • Formal specification — the precise reference: the grammars in BNF, the abstract syntax, and the lowering / validation / authorization rules, each cross-referenced to its source of record.

Runnable examples

Every policy-level example in this guide is a complete, runnable bundle under this crate’s examples/ directory — a policy.dw, its schema.cedarschema, and (for history-dependent examples) a trace.log plus the expected verdict stream, along with any providers.json / macros.dw / event schema the example needs. A test harness checks every bundle on each build (validating each policy, and replaying traces against the expected verdict stream), so a guide example that stops parsing, validating, or replaying as written is a build failure. To run one yourself, see The command line.

To embed the engine rather than drive it over files — building events programmatically and feeding them one at a time to a stateful Authorizer — use the Rust API, walked through end to end in The API and workflow.

Reading order

If you read straight through, this order builds naturally:

  1. Introduction
  2. Getting started
  3. The policy language
  4. Temporal expressions
  5. Information providers
  6. Calling macros

Then reach into the Advanced topics as you need them: the event schema, the provider schema, macros, and MCP schema generation. Integrate from Rust with The API and workflow, and consult the Formal specification as the reference.