-
Notifications
You must be signed in to change notification settings - Fork 1
JACAL Introduction
The Attribute-Centric Authorization Language (ACAL) is an OASIS standard for expressing attribute-based access control (ABAC) authorization policies. It defines how authorization decisions are made: given a description of a request — who is asking, what they want to do, and what they want to do it to — an ACAL-compliant policy decision point (PDP) evaluates policies expressed in ACAL and returns a decision of Permit, Deny, NotApplicable, or Indeterminate.
ACAL is policy-language agnostic. The core specification defines the authorization model in terms of an abstract data model and evaluation semantics, independent of any serialization format. Representation profiles — currently JSON (JACAL) and YAML (YACAL) — map the abstract model to concrete syntax. This guide covers the JSON representation exclusively.
The central insight of ACAL's authorization model is that decisions should be driven by attributes — structured facts about the subject, the action, the resource, and the environment — rather than by identity alone or by roles hardcoded into application logic. A policy expresses conditions over attributes; the PDP evaluates those conditions against the attribute values present in a request. This keeps authorization logic centralized, testable, and independent of the applications that invoke it.
ACAL is the direct successor to XACML 3.0, the OASIS eXtensible Access Control Markup Language. XACML 3.0 established the foundational ideas that ACAL inherits: a structured request context organized by attribute categories (subject, action, resource, environment), a function library for expressing conditions, combining algorithms for composing rule and policy outcomes, and an obligation mechanism for attaching side-effect requirements to decisions.
ACAL updates and extends this foundation in several important ways.
The abstract data model is no longer tied to XML, making ACAL
representation-neutral by design. The obligation mechanism is unified
under the NoticeExpression construct, which covers both obligations
and advice in a single, consistent framework. Short identifiers provide
a first-class alias mechanism for reducing URI verbosity in policy
documents. The evaluation model is refined and clarified throughout,
with tighter semantics for Indeterminate propagation and combining
algorithm behavior.
For practitioners familiar with XACML, the policy structure and
evaluation semantics will feel familiar. The attribute categories, the
Apply/AttributeDesignator/Value expression tree, and the combining
algorithms all have direct XACML counterparts. The main adjustment is
becoming comfortable with the abstract model's notation before reading
the JACAL-specific JSON syntax.
For practitioners coming to attribute-based authorization for the first time, ACAL is a well-specified, production-oriented starting point that avoids the accumulation of historical design choices that can make legacy XACML documents difficult to work with.
JACAL (the JSON representation of ACAL) serializes the ACAL abstract
model as JSON, governed by a JSON Schema Draft 2020-12 document with
the identifier urn:oasis:names:tc:jacal:1.0:core:schema. Every
JACAL document is one of four root types, each wrapped in a
discriminator key: {"Policy": {...}}, {"Bundle": {...}},
{"Request": {...}}, or {"Response": {...}}.
The schema uses additionalProperties: false throughout, which means
any unrecognized property name causes validation failure. This is an
intentional design decision: strict validation at schema level prevents
silently ignored typos from causing subtle authorization bugs. All
property names in JACAL documents are PascalCase, following the ACAL
abstract model's naming conventions.
Identifiers in JACAL documents — function names, attribute category
names, data type names, combining algorithm names, and application-
defined attribute identifiers — are expressed as URIs. ACAL defines a
Short Identifier mechanism that allows a policy, request, or
response to declare a ShortIdSetReference pointing to a named alias
set. Once declared, aliases replace full URIs wherever an identifier
appears. For example, urn:oasis:names:tc:acal:1.0:function:string-equal
becomes {acal:string-equal}, and a custom attribute URI like
urn:example:jacal:website:subject:account-type becomes
{ex:subject:account-type}. The JACAL-Short-ID-Expression chapter presents
all ten example policies in short-ID form and defines the guide's shared
identifier set.
Every authorization decision in ACAL is computed from a set of attribute values organized into four standard categories.
The subject category (formally access-subject) describes the
entity requesting access. Typical subject attributes include user
identifiers, roles, organizational memberships, clearance levels, and
account status. An ACAL subject can be a human user, an API client, an
AI agent, or any other requestor.
The action category describes what operation is being requested.
The standard attribute is action-id, whose value is an
application-defined string such as "view", "edit", "invoke", or
"connect". Additional action attributes can describe the context of
the operation.
The resource category describes the object to which access is being requested. Resource attributes typically include identifiers, types, classification labels, ownership information, and any domain-specific facts attached to the data or service being protected.
The environment category captures contextual information not attached to the subject, action, or resource specifically — the current time, whether an emergency state has been declared, network properties, and similar runtime signals.
A policy author writes rules that express conditions over attributes
drawn from these four categories. The PDP evaluates those conditions
against the attribute values present in each incoming request. If all
conditions in a rule's Condition expression evaluate to true, the
rule's Effect (Permit or Deny) fires. The policy's combining
algorithm then determines the final decision from the collection of
rule outcomes.
ACAL defines four possible decision outcomes.
Permit means the request is authorized. The PDP may accompany a
Permit decision with Notice items (obligations and advice) that the
enforcement point is expected to act on.
Deny means the request is not authorized. The PDP may similarly accompany a Deny decision with notices.
NotApplicable means no applicable policy was found for the request.
In most production deployments, the enforcement point treats
NotApplicable as Deny by using the deny-unless-permit combining
algorithm, which ensures that the absence of an explicit Permit always
results in Deny.
Indeterminate means evaluation could not be completed — typically
because a required attribute was absent from the request (MustBePresent
was true and the attribute was missing), or because an expression
produced a type error. Under deny-unless-permit, Indeterminate is
also treated as Deny, which is the correct secure default: if the PDP
cannot make a confident Permit determination, access should be refused.
All ten example policies in this guide use deny-unless-permit. The
implications of this choice — particularly the behavior of
MustBePresent — are discussed in the Policy Authoring Patterns and
Pitfalls chapter.
This guide is a practical introduction to writing JACAL authorization policies. It is intended for developers and solution architects who need to express authorization requirements for real systems, and who want to understand the JACAL policy structure and evaluation model through worked examples rather than through the formal specification alone.
The guide is organized around ten policy examples drawn from common application domains: web content access, administrative portals, multi-tenant SaaS, API gateways, financial approval workflows, healthcare record access, emergency overrides with audit obligations, AI agent tool authorization, and external endpoint anti-spoof validation. Each example introduces one or more new JACAL patterns and discusses the design decisions behind the policy structure.
The guide does not cover policy administration, attribute sourcing pipeline design, Policy Sets and Bundles, or delegation — all of which depend on PDP implementation specifics or are advanced topics beyond the scope of an introductory authoring guide.
Architecture and Evaluation Flow explains how the PDP/PEP/PIP components interact at runtime, the lifecycle of an authorization request, and the semantics of combining algorithms and decision outcomes.
Policy Authoring Patterns and Pitfalls covers the key design
decisions and common mistakes in JACAL policy authoring: attribute
modeling, the bag-versus-singleton distinction, MustBePresent
semantics, function argument order, and secure default strategies.
JACAL Requests and Responses describes the structure of the JSON documents exchanged between the PEP and the PDP: how attributes are presented in a request, and how decisions, status, and obligations are returned in a response. Three complete request/response exchanges are shown using the first example policy as a vehicle.
Authoring Your First Policy walks step-by-step through designing and writing a JACAL policy from scratch: identifying attribute categories, choosing functions, building the condition expression tree, and verifying the policy with test scenarios.
Examples 1–10 are the heart of the guide. Each chapter presents one policy, explains the authorization model it implements, shows the complete JACAL policy document, walks through decision scenarios, and discusses implementation considerations.
Short ID Expression presents all ten example policies rewritten using short ID aliases, together with the guide's shared identifier set.
The guide also includes four reference chapters: Combining Algorithms explains all standard algorithms and when to choose each; Attribute Sourcing describes the PEP/PIP/PDP attribute data flow and how to diagnose missing-attribute problems; Common Mistakes catalogs frequent authoring errors with wrong-versus-right examples; and Glossary defines all key terms used across the guide.
This guide is a companion to, not a replacement for, the ACAL and JACAL specifications. The normative definitions of all data types, evaluation semantics, combining algorithm behavior, and conformance requirements are in those documents.
When something in this guide raises a question about exact semantics —
for example, how string-equal behaves when one argument is a
multi-valued bag, or what the precise propagation rules are for
Indeterminate through an and expression — the specifications are
the authoritative reference. The JACAL JSON Schema is also a valuable
companion: because it uses additionalProperties: false throughout,
validating a policy document against the schema is a reliable first
diagnostic step when a document does not behave as expected.
- Introduction
- Architecture and Evaluation Flow
- Patterns and Pitfalls
- Requests and Responses
- Authoring Your First Policy