README

Members of the OASIS eXtensible Access Control Markup Language (XACML) create and manage technical content in this TC GitHub repository ( https://github.com/oasis-tcs/xacml-spec ) as part of the TC's chartered work (the program of work and deliverables described in its charter).

OASIS TC GitHub repositories, as described in GitHub Repositories for OASIS TC Members' Chartered Work, are governed by the OASIS TC Process, IPR Policy, and other policies, similar to TC Wikis, TC issues tracking instances, etc. While they make use of public GitHub repositories, these TC GitHub repositories are distinct from OASIS Open Repositories, which are used for development of open source licensed content.

Description

The OASIS XACML Technical Committee is developing ACAL (Attribute-Centric Authorization Language) v1.0, the successor to XACML 3.0. ACAL separates policy semantics from serialization syntax, enabling the same authorization policies to be expressed in XML (XACML v4.0), JSON (JACAL v1.0), or YAML (YACAL v1.0). This repository contains the specifications, schemas, and supplementary artifacts for all three representations. Requests for modification can be made via GitHub Issues.

Specification Family

Specification	Short name	Role
ACAL Core v1.0	ACAL	Format-agnostic abstract model, processing rules, conformance
ACAL Core – XML Representation Profile v4.0	XACML v4.0	XML serialization of ACAL
ACAL Core – JSON Representation Profile v1.0	JACAL v1.0	JSON serialization of ACAL
ACAL Core – YAML Representation Profile v1.0	YACAL v1.0	YAML serialization of ACAL

Key Changes from XACML 3.0

• Policy absorbs PolicySet: nested policies use a single Policy type with a CombinerInput sequence; PolicySet is eliminated
• Target simplification: the AnyOf / AllOf / Match structure is replaced by a plain boolean Apply expression — the same language as Condition
• NoticeExpression: ObligationExpression and AdviceExpression are unified into a single NoticeExpression type with an IsObligation flag
• Attribute DataType: DataType is declared once per Attribute, not per value, preventing mixed-type bags
• Short identifiers (ShortIdSet): user-defined URI aliases reduce verbosity; a standard ACAL identifier set covers all built-ins
• QuantifiedExpression: ForAny, ForAll, Map, and Select enable iteration over attribute value bags
• Bundle: portable container for policies, shared variable definitions, and identifier sets
• Identifier namespace: standard identifiers move from urn:oasis:names:tc:xacml: to urn:oasis:names:tc:acal:
• XPath moved to a profile: XPath-based AttributeSelector and functions are in the separate ACAL XPath Profile; a new JSONPath Profile is also defined

For a complete description of changes with worked examples in all three representations, see the ACAL Adoption and Implementation Guide.

Contributions

As stated in this repository's CONTRIBUTING file, contributors to this repository are expected to be Members of the OASIS XACML TC, for any substantive change requests. Anyone wishing to contribute to this GitHub project and participate in the TC's technical activity is invited to join as an OASIS TC Member. Public feedback is also accepted, subject to the terms of the OASIS Feedback License, as noted in the LICENSE file.

Open-source Community Contributions

A separate GitHub public organization (ACAL Open Source Community) was created at the initiative of the OASIS ACAL TC to support development of open source resources related to the TC work and the ACAL/XACML standard in general.

While this Github organization remains associated with the sponsor TC, its development priorities, leadership, intellectual property terms, participation rules, and other matters of governance are separate and distinct from the OASIS TC Process and related policies.

Licensing

Please see the LICENSE file for description of the license terms and OASIS policies applicable to the TC's work in this GitHub project. Content in this repository is intended to be part of the XACML TC's permanent record of activity, visible and freely available for all to use, subject to applicable OASIS policies, as presented in the repository LICENSE file.

Further Description of this Repository

See this repository's CONTRIBUTING file for information on how to participate in the TC's work.

Contact

Please send questions or comments about OASIS TC GitHub repositories to Project Administration. For questions about content in this repository, please contact the TC Chair or Co-Chairs as listed on the the XACML TC's home page.

Repository content description

• ACAL Core (agnostic model) artifacts:

  • ACAL Core Specification
  • ACAL Core - JSON Representation Profile (JACAL) artifacts:
    • Specification;
    • JSON schema;
    • Reference ShortIdSet (short identifiers) provided as an example.
  • ACAL Core - XML Representation Profile (XACML) artifacts:
    • Specification;
    • XML schema using W3C XML Schema 1.1 standard;
    • Schematron schema to be combined with a XML-Schema-1.0 version of the above XML schema, which may be generated by the XSD 1.1-to-1.0 conversion XSLT stylesheet mentioned later below;
    • Reference ShortIdSet (short identifiers) provided as an example.

• ACAL JSONPath Profile artifacts:

  • Specification;
  • ACAL JSONPath - JSON Representation (JACAL) artifact(s):
    • JSON schema.
  • ACAL JSONPath - XML Representation Profile (XACML) artifact(s):
    • XML schema;

• ACAL XPath Profile artifacts:

  • Specification;
  • ACAL XPath - JSON Representation (JACAL) artifact(s):
    • JSON schema.
    • Reference ShortIdSet (short identifiers) provided as an example.
  • ACAL XPath - XML Representation Profile (XACML) artifact(s):
    • XML schema;
    • Reference ShortIdSet (short identifiers) provided as an example.

• XSD 1.1-to-1.0 conversion XSLT: XSLT stylesheet for creating an XML schema 1.0 version of an XML-schema-1.1-defined XSD (removing the XML-Schema-1.1-specific elements).

• pandoc directory: files specifically used for HTML/PDF generation with Pandoc (CSS stylesheets, pandoc templates, Lua filters, scripts, etc.);

• published directory: latest published (to OASIS) documents and related files (e.g. XML/JSON schemas), as part of the last release.

• Supplementary documents:

  • ACAL Adoption and Implementation Guide: informative guide covering the changes from XACML 3.0, cross-representation examples, migration checklist, and conformance overview.

FAQ (Frequently Asked Questions)

How to validate XACML documents with the XACML schemas

Case 1: your implementation supports the latest XML Schema standard 1.1

Since XACML 4.0, XACML schemas exist in XSD version 1.1 to provide more advanced validation and especially an equivalence for the UML constraints (OCL) defined in ACAL agnostic model, in form of XSD 1.1 assertions (xs:assert). One way to validate against a XSD 1.1 schema is to use Apache Xerces2 Java XML Parser, more specifically its binary distribution called Xerces2 Java 2.12.2 (XML Schema 1.1).

Download the binary distribution zip or tar.gz depending on your OS, then unzip it to a folder, say xerces-2_12_2-xml-schema-1.1.

Then (based on Apache Xerces2 Java XML Parser's issue 1726), change your working directory to the root of this repository where the XACML schemas are located.

In order to validate a XACML document, say MyPolicy.xml, run the following command line (you may omit -a ./acal-xpath-xml-v4.0-schema.xsd (resp. a ./acal-jsonpath-xml-v4.0-schema.xsd) if your XACML document does not use the XPath (resp. JSONPath) Profile):

# Tested with Java 21 LTS
$ java -cp "xerces-2_12_2-xml-schema-1.1/*" jaxp.SourceValidator -i MyPolicy.xml -a ./acal-core-xml-v4.0-schema.xsd -a ./acal-xpath-xml-v4.0-schema.xsd -a ./acal-jsonpath-xml-v4.0-schema.xsd -f -fx -xsd11

Case 2: your implementation supports only XML Schema 1.0

As an alternative to the XSD 1.1 core schema (with XSD 1.1 assertions) previously mentioned, implementers that only support XSD 1.0 may use an XSD 1.0 version of the core schema - obtained by filtering out all the schema elements with attribute vc:minVersion="1.1" according to the XML Schema Versioning standard (e.g. using a XSLT stylesheet) - in combination with the core Schematron schema, which provides an equivalent for XSD 1.1 assertions.

Here is an example of how to do that with the XML schema 1.0-only version of Xerces2 Java 2.12.3 (instead of the XML Schema 1.1 one) for the XML schema 1.0 validation and Schxslt2 for the Schematron validation.

1. Download and unzip the XML schema 1.0 version of Xerces2, then download Schxslt2's XSLT stylesheet:

   $ wget https://dlcdn.apache.org//xerces/j/binaries/Xerces-J-bin.2.12.2.tar.gz -P /tmp
   $ pushd tmp; tar xvzf Xerces-J-bin.2.12.2.tar.gz; popd
   $ wget https://codeberg.org/SchXslt/schxslt2/raw/branch/main/src/main/resources/content/transpile.xsl -P /tmp

2. Generate (once and for all validations) the XSD 1.0 version of the core schema using the XSLT stylesheet xsd1.1-to-1.0.xslt with Saxon HE (tested with v12.5) as the XSLT engine:

   # Tested with Java 21 LTS
   $ java -jar saxon-he-12.5.jar -xsl:xsd1.1-to-1.0.xsl -s:acal-core-xml-v4.0-schema.xsd -o:/tmp/acal-core-xml-v4.0-schema-xsd1.0.xsd

3. Generate (once and for all validations) - from the Schematron schema - the XSLT stylesheet that will be processed by the XSLT engine to do the actual Schematron validation of XML documents. Here is an example of generation with Schxslt2:

   # Tested with Java 21 LTS
   $ java -jar saxon-he-12.5.jar -xsl:/tmp/transpile.xsl -s:acal-core-xml-v4.0-schematron.sch -o:/tmp/acal-core-xml-v4.0-schematron.xsl

4. In order to validate a XACML document, say MyPolicy.xml, against both the XSD 1.0 and Schematron schemas, run the following command lines:

   # Tested with Java 21 LTS
   $ java -cp "/tmp/xerces-2_12_2/*" jaxp.SourceValidator -a /tmp/acal-core-xml-v4.0-schema-xsd1.0.xsd -a acal-xpath-xml-v4.0-schema.xsd -a acal-jsonpath-xml-v4.0-schema.xsd -f -i MyPolicy.xml
   $ java -jar saxon-he-12.5.jar -xsl:/tmp/acal-core-xml-v4.0-schematron.xsl MyPolicy.xml

   This last command will output a Schematron Validation Report (SVRL).

How to validate JACAL (JSON) documents with the JACAL schemas ?

JACAL is the JSON representation of ACAL, in other words the JSON variant of XACML. JACAL core model is defined by the Core JSON schema, corresponding to ACAL core model. Certain structures of the core model (ACAL structured Datatypes) are extensible and may have standard extensions already defined in ACAL Profiles, e.g. the JSONPath and XPath Profiles which extend the AttributeSelectorType among others. Depending on whether your ACAL implementation supports such Profiles or not, the way to validate JACAL documents properly against the JSON schema(s) differs. Let us go other the different cases. For each case, we'll show an example of command-line to validate a JACAL (JSON) document using Sourcemeta's open source JSON schema CLI.

Case 1: the implementation does not support any Profile or extension to ACAL model, only the core model:

In this case, you simply use JACAL core schema for validation. Here is an example of jsonschema validate command that validates a JACAL document in a file policy.json:

$ jsonschema validate acal-core-json-v1.0-schema.json policy.json

Case 2: the implementation supports one or more Profiles extending the ACAL core model (i.e. extending JACAL core schema):

Each extensible type FooType has a JSON subschema FooTypeTree defined in the core schema as follows (using the special keyword $dynamicRef introduced in JSON schema Draft 2020-12 specification):

Core schema:

"FooTypeTree": { "$dynamicRef": "#FooTypeExtensions" }

This enables you to extend FooType with the concrete subtypes from the JACAL Profiles you want to support, by defining a matching $dynamicAnchor in your implementation-specific schema (the core schema must be imported last):

New schema for a particular implementation supporting two ACAL Profiles extending FooType:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "urn:my:implementation:specific:combining:schema",
    "$defs": {
        "SupportedFooTypeExtensions": {
            "$dynamicAnchor": "FooTypeExtensions",
            "anyOf": [
                {
                    "$ref": "urn:some:profile:schema#/$defs/SomeFooSubTypeTree"
                },
                {
                    "$ref": "urn:some:other:profile:schema#/$defs/SomeOtherFooSubTypeTree"
                }
            ]
        },
        ...
    },
    "$ref": "urn:oasis:names:tc:jacal:1.0:core:schema"
}

This schema is also called a combining schema as it combines the core schema with the specific Profiles' to be supported by your implementation.

We provide two concrete examples of combining schemas on this Github repository to illustrate this case and get you started using JACAL Profiles:

1. Example 1: let's say you want to support JSONPath-based AttributeSelectors, i.e. the AttributeSelectorType extensions from the JSONPath Profile's. In this case, you may use the example of combining schema for JSONPath Profile support for your implementation. This schema makes a reference ($ref) to the core schema and JSONPath Profile's schema.

   To use this schema, the previous JSON schema validation command is modified as follows:

   $ jsonschema validate --resolve acal-core-json-v1.0-schema.json --resolve acal-jsonpath-json-v1.0-schema.json examples/acal-core-json/jacal-root-schema-example-using-jsonpath-profile-only.json policy.json

2. Example 2: you want to support both JSONPath and XPath based AttributeSelectors, i.e. JSONPath and XPath Profiles, then you may use the example of combining schema for JSONPath and XPath Profile support. This schema makes a reference ($ref) to the core schema, JSONPath Profile's schema and XPath Profile's schema.

   To use this schema, the previous JSON schema validation command is modified as follows:

   $ jsonschema validate --resolve acal-core-json-v1.0-schema.json --resolve acal-jsonpath-json-v1.0-schema.json --resolve acal-xpath-json-v1.0-schema.json examples/jacal-root-schema-example-using-xpath-and-jsonpath-profiles.json policy.json

How to validate YACAL (YAML) documents with the YACAL schemas?

YACAL is the YAML representation of ACAL. Validation requires two steps: structural validation using the YACAL structural schema (a JSON Schema Draft 2020-12 document serialized in YAML), and higher-order constraint checking using the YACAL constraint catalog.

Step 1: Structural validation

Use any YAML 1.2 parser combined with a JSON Schema Draft 2020-12 validator. Parse the YACAL document to a YAML data model, then validate against the structural schema. For implementations that support only one ACAL Core Profile, use the core-only structural schema directly:

$ <your-yaml-json-schema-validator> acal-core-yaml-v1.0-structure.schema.yaml policy.yaml

For implementations that support profiles (XPath, JSONPath), use the corresponding composition example schema as the root schema, referencing the core and profile schemas:

$ <your-yaml-json-schema-validator> \
    yacal-root-structure-example-using-xpath-and-jsonpath-profiles.schema.yaml \
    policy.yaml

The composition example schemas in this repository (yacal-root-structure-example-*.schema.yaml) illustrate how to combine the core schema with one or more profile schemas for common deployment scenarios.

Step 2: Constraint validation

Apply the constraint catalog (acal-core-yaml-v1.0-constraints.yaml) using a constraint processor compatible with the catalog's format. The constraint catalog captures higher-order rules (uniqueness, scoped references, cycle detection) that are normative in ACAL Core but are not expressible purely in JSON Schema.

How to convert a JACAL document to XACML 4.0?

The XACML TC will provide an example of JACAL-to-XACML conversion tool as a reference, on this repository. In the meantime, you may apply the following mapping rules:

For each JSON property P with value V in the JACAL document,

1. If and only if P is defined in the JACAL (JSON) schema as single-valued (not a JSON array), then
   1. If P's type is a primitive type other than the unrestricted string type, map to an XML attribute P="escaped_V" where escaped_V is V possibly modified after escaping XML special characters. (Unrestricted String means it is defined as "type": "string" only, without any further restriction, e.g. no "format" or "pattern" assertion in particular.)
   2. Else if P's type is simply (unrestricted) string, map to an XML element <P>escaped_V</P> defined in the XACML 4.0 namespace. (In JACAL core schema, only the Description and StatusMessage properties are single-valued unrestricted Strings.)
   3. Else if P's type is object (JSON object), map to the XML element <P> and, for each sub-property P_n of the object, re-apply these same mapping rules (recursively) to P_n and add the result XML attribute/element to <P> as a child node. The order of child elements must match the order defined in the XACML schema.
2. Else (P is a JSON array) for each JSON value V_n (n=0, 1,...) of P, create an XML element <P> with the following XML attributes and/or child nodes:
   1. If V_n is primitive, the only child node is a text node whose content is V_n possibly modified after applying XML character escaping rules. No XML attribute.
   2. Else if V_n is a JSON object, the attributes and child elements are the results of re-applying the full mapping rules to each property P_n of this object. The order of child elements must match the order defined in the XACML schema for the corresponding <P> element.
   3. Else (V_n is a JSON array) reject as invalid (JSON arrays of arrays are not allowed).