Making the Core Syntax Agnostic

[steven-legg]

This is a test case for rewriting the core specification to be syntax agnostic. I chose the policy description because it is non-trivial. As I was finishing this up DMLex was published, which also aims to be syntax agnostic and went a similar way. Here it is for comparison:

https://docs.oasis-open.org/lexidma/dmlex/v1.0/csd04/dmlex-v1.0-csd04.html#idm218

A preamble is required to describe the abstract model in the absence of a preferred schema language. It would naturally fit into the start of Section 5. It was necessary to invent a Parts property for the JSON representation to correspond to the <xs:choice minOccurs="0" maxOccurs="unbounded"> particle in the XML Schema.

---

5 Structures

The structures in XACML are described here in abstract terms. The concrete representations of these structures are defined for a variety of syntaxes each in a separate profile.

Object type

The XACML structures are objects that each conform to a specific object type. Objects of the same kind conform to a specific, named object type, which describes a set of properties that an object of the type is permitted to have and for each property whether it is required or optional.

A property has a unique name (unique among the object's properties) and a value, where the value conforms to a specific type, either a simple type, an object type, or a sequence of such values.

Simple types

The simple types are:

• String : A sequence of characters that may be constrained to a particular pattern.

• URI : A sequence of characters representing a Uniform Resource Identifier according to RFC 3986.

• Boolean : Either true or false.

• Integer : An integer number that may be constrained to a particular range.

Examples of concrete representations

In the JSON representation, an object maps to a JSON object and a property of that object maps to a JSON member (a name/value pair). An object type is formally defined by a JSON subschema.

In the XML representation, a property corresponds to an element or XML attribute, an object corresponds to element content and an object type is formally defined by an XML Schema complex type.

5.1 Policy

The value of a Policy property is an object of the PolicyType object type, which describes a policy.

A policy is an aggregation of rules and other policies. Policies MAY be included in an enclosing PolicyType object either directly using the Policy property or indirectly using the PolicyReference property. If the values of PolicyReference properties are in the form of URLs, then these references MAY be resolvable.

A Policy property may be evaluated, in which case the evaluation procedure defined in [Section 7.12] SHALL be used.

A PolicyType object contains the following properties:

PolicyId [Required]

• Contains a URI identifying the policy. It is the responsibility of the PAP to ensure that no two policies visible to the PDP have the same identifier. This MAY be achieved by following a predefined URN or URI scheme. If the policy identifier is in the form of a URL, then it MAY be resolvable.

Version [Required]

• Contains a String value indicating the version number of the policy. The value must match the SemVer pattern.

CombiningAlgId [Required]

• Contains a URI value identifying the combining algorithm by which the Policy, Rule, CombinerParameters, PolicyCombinerParameters and RuleCombinerParameters properties MUST be combined. Standard combining algorithms are listed in [Appendix G]. Standard combining algorithm identifiers are listed in [Appendix F.9].

MaxDelegationDepth [Optional]

• Type: Integer. Description: If present, limits the depth of delegation which is authorized by this policy. See the delegation profile [XACMLAdmin].

Description [Optional]

• Type: String. Description: A free-form description of the policy.

PolicyIssuer [Optional]

• Set of Attributes of the issuer of the policy. The interpretation of the PolicyIssuer property is explained in the separate administrative policy profile [XACMLAdmin].

PolicyDefaults [Optional]

• A set of default values applicable to the policy. The scope of the PolicyDefaults property SHALL be the enclosing PolicyType object.

Target [Optional]

• Type: Object. Description: The Target property defines the applicability of a policy to a set of decision requests. If the Target property matches the request context, then the PolicyType object MAY be used by the PDP in making its authorization decision. See [Section 7.12].

• The Target property MAY be declared by the creator of the PolicyType object or it MAY be computed from the Target properties of the referenced Policy properties the Condition properties of the referenced Rule properties, either as an conjunction or as a disjunction.

ObligationExpressions [Optional]

• Contains a set of obligation expressions that MUST be evaluated into obligations by the PDP. See [Section 7.18] for a description of how the set of obligations to be returned by the PDP shall be determined. The resulting obligations MUST be fulfilled by the PEP in conjunction with the authorization decision. If the PEP does not understand or cannot fulfill any of the obligations, then it MUST act according to the PEP bias. See [Section 7.2].

AdviceExpressions [Optional]

• Contains a set of advice expressions that MUST be evaluated into advice by the PDP. See [Section 7.18] for a description of how the set of advice to be returned by the PDP shall be determined. The resulting advice MAY be safely ignored by the PEP in conjunction with the authorization decision.

Parts [Optional]

• An ordered sequence of PolicyPartType objects.

Each PolicyPartType object contains exactly one of the following properties:

Policy [Optional]

• Type: PolicyType. Description: A policy that is included in this policy. A policy whose target matches the decision request MUST be considered. A policy whose target property does not match the decision request SHALL be ignored.

PolicyReference [Optional]

• Type: Object. Description: A reference to a policy that MUST be included in this policy. If the PolicyReference is a URI, then it MAY be resolvable. A policy whose target matches the decision request MUST be considered. A policy whose target does not match the decision request SHALL be ignored.

VariableDefinition [Optional]

• Common variable definition that can be referenced from anywhere in a contained policy or rule where an expression can be found.

Rule [Optional]

• A rule that MUST be combined with the other Rules and Policies declared in the enclosing policy, according to the combining algorithm identified in the CombiningAlgId property. A rule whose condition matches the decision request MUST be considered. A rule whose condition does not match the decision request SHALL be ignored.

CombinerParameters [Optional]

• Contains parameters for the combining algorithm. It is up to the specific combining algorithm to interpret them and adjust its behavior accordingly.

PolicyCombinerParameters [Optional]

• Contains parameters that are associated with a particular Policy or PolicyReference property within the policy. It is up to the specific combining algorithm to interpret them and adjust its behavior accordingly.

RuleCombinerParameters [Optional]

• Contains parameters that are associated with a particular Rule property within the policy. It is up to the specific combining algorithm to interpret them and adjust its behavior accordingly.

---

The XML Schema definitions for Policy and PolicyType would appear in a separate profile for the XML representation.

---

5.1 Policy

A Policy property is represented in XML as a <Policy> element. The <Policy> element is of PolicyType complex type.

<xs:element name="Policy" type="xacml:PolicyType"/>
<xs:complexType name="PolicyType">
   <xs:sequence>
      <xs:element ref="xacml:Description" minOccurs="0"/>
      <xs:element ref="xacml:PolicyIssuer" minOccurs="0"/>
      <xs:element ref="xacml:PolicyDefaults" minOccurs="0"/>
      <!-- Parameters if the policy is parameterized, more info in issue #4 -->
      <xs:element ref="xacml:Parameter" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element ref="xacml:Target" minOccurs="0"/>
      <xs:choice minOccurs="0" maxOccurs="unbounded">
         <xs:element ref="xacml:Policy"/>
         <xs:element ref="xacml:PolicyReference"/>
         <xs:element ref="xacml:Rule"/>
         <xs:element ref="xacml:CombinerParameters"/>
         <xs:element ref="xacml:PolicyCombinerParameters"/>
         <xs:element ref="xacml:RuleCombinerParameters"/>
         <xs:element ref="xacml:VariableDefinition"/>
      </xs:choice>
      <xs:element ref="xacml:ObligationExpressions" minOccurs="0"/>
      <xs:element ref="xacml:AdviceExpressions" minOccurs="0"/>
   </xs:sequence>
   <xs:attribute name="PolicyId" type="xs:anyURI" use="required"/>
   <xs:attribute name="Version" type="xacml:VersionType" use="required"/>
   <xs:attribute name="CombiningAlgId" type="xs:anyURI" use="required"/>
   <xs:attribute name="MaxDelegationDepth" type="xs:integer" use="optional"/>
</xs:complexType>

The PolicyPartType is represented as an anonymous <choice> element information item in the XML Schema and the Parts property is not visibly represented as an element in the XML representation.

---

The JSON Schema definitions for Policy and PolicyType would appear in a separate profile for the JSON representation.

Take this with a grain of salt. I haven't fully grokked JSON Schema yet.

---

5.1 Policy

A Policy property is represented in JSON as a member with the name Policy.

{
  "Policy": {
    "type": "object",
    "properties": {
      "PolicyId": {
        "type": "string",
        "format": "uri"
      },
      "Version": {
        "type": "string",
        "format": "VersionType"
      },
      "CombiningAlgId": {
        "type": "string",
        "format": "uri"
      },
      "MaxDelegationDepth": {
        "type": "integer",
        "minimum": 0
      },
      "Description": {
        "$ref": "#/$defs/Description"
      },
      "PolicyIssuer": {
        "$ref": "#/$defs/PolicyIssuer"
      },
      "PolicyDefaults": {
        "$ref": "#/$defs/PolicyDefaults"
      },
      "Target": {
        "$ref": "#/$defs/Target"
      },
      "Parts": {
        "type": "array",
        "items": {
          "$ref": "#/$defs/PolicyPartType"
        }
      },
      "ObligationExpressions": {
        "$ref": "#/$defs/ObligationExpressions"
      },
      "AdviceExpressions": {
        "$ref": "#/$defs/AdviceExpressions"
      }
    },
    "required": { "PolicyId", "Version", "CombiningAlgId" }
  }
},
{
  "PolicyPartType": {
    "type": "object",
    "oneOf": [
      { "$ref": "#/$defs/Policy" },
      { "$ref": "#/$defs/PolicyIdReference" },
      { "$ref": "#/$defs/CombinerParameters" },
      { "$ref": "#/$defs/PolicyCombinerParameters" },
      { "$ref": "#/$defs/RuleCombinerParameters" },
      { "$ref": "#/$defs/VariableDefinition" },
      { "$ref": "#/$defs/Rule" }
    ]
  }
}

[cdanger]

I did a few changes:

• Added that a property value can also be a sequence of values (multi-valued) in addition to simple type and object type (we can say array of values if you prefer). This is to be consistent with the Policy properties that you defined as a set of something (PolicyIssuer, AdviceExpressions, ObligationExpressions, CombinerParameters, etc.), also Parts is defined as an ordered sequence of something. (I prefer the terms sequence or array in general because a set is more restrictive as it cannot have duplicates in type theory; or we could explicitly define the set as a particular type of sequence in the model.)
• Added a reference to the RFC for the URI type.
• Added a pattern for the Version property based on semantic versioning (best practice) which is better that the current pattern (\d+\.)*\d+ defined in XACML 3.0 VersionType in my opinion, because it allows meaningless sequences of zeros 00000... and does not support semantic versioning.
• Added type String explicitly for Description property, type Integer for MaxDelegationDepth
• Renamed PolicyIdReference to PolicyReference according to Flatten the policy hierarchy #11 and Simplify policy and policy set references and versioning #16

A few other suggestions:

• Replace AdviceExpressions and ObligationExpressions with NoticeExpression according to Simplify the policy language model (XML schema) - Merge Obligation/Advice(Expression)s into one element #6
• Consider simplifying the xxxCombinerParameters model according to Simplify combiner parameters #14
• Mention that a PolicyReference can have a policy ID, version (pattern) and argument expressions if it is parameterized, as in Flatten the policy hierarchy #11
• Add the policy Parameters property (optional) for parameterized policies according to Parameterized Policies and Policy references (allowing to pass Variables to referenced policies) [UPDATES #9] #4 and Flatten the policy hierarchy #11 .
• Parts sounds a bit catch-all / too generic as a property name (everything is a part). Since this is essentially a sequence of combined elements/parameters, we may call it something like CombiningSequence. My only concern with that name is the VariableDefinitions which are not actually combined (by the combining algorithm) but still used in the evaluation of the combined elements. If we move the VariableDefinitions before/outside the Parts as optional Policy property - since (I quote) they can be referenced from anywhere, it doesn't matter where they are declared - then the Parts are only policies, rules and combiner parameters, which are all inputs to the combining algorithm. In that case, we may call it CombinerInputs or CombinerArgs or CombinedElements or something alike.

[steven-legg]

• Added that a property value can also be a sequence of values (multi-valued) in addition to simple type and object type (we can say array of values if you prefer). This is to be consistent with the Policy properties that you defined as a set of something (PolicyIssuer, AdviceExpressions, ObligationExpressions, CombinerParameters, etc.), also Parts is defined as an ordered sequence of something. (I prefer the terms sequence or array in general because a set is more restrictive as it cannot have duplicates in type theory; or we could explicitly define the set as a particular type of sequence in the model.)

It is the core spec that used "set" and I just copied the descriptions from there. It is more correct to say "sequence of" for most if not all of these cases for the reason you have given. I prefer "sequence of" over "array of" because it is more neutral (JSON has arrays, XML does not).

[steven-legg]

• Added type String explicitly for Description property, type Integer for MaxDelegationDepth

My goal was to see if I could reasonably separate out the syntax from the semantics and wasn't overly concerned with improving the XACML 3.0 text or addressing any of the enhancements we have in mind. Yes, the type of the properties should be explicit. I would have gone with less colons, e.g:

MaxDelegationDepth [Optional]

• If present, an Integer that limits the depth of delegation authorized by this policy. See the delegation profile [XACMLAdmin].

Description [Optional]

• A free-form String description of the policy.

[steven-legg]

• Parts sounds a bit catch-all / too generic as a property name (everything is a part).

I agree. It's a placeholder. I needed to name it something and didn't have a pleasing alternative. Something that relates to these being inputs to the combining algorithm would be appropriate. I'd avoid CombinerArgs since we have another use in mind for something called arguments. I'd avoid CombinedElements for not being syntax-neutral. Maybe CombinerInputs or CombinedItems.

[cdanger]

• Added type String explicitly for Description property, type Integer for MaxDelegationDepth

My goal was to see if I could reasonably separate out the syntax from the semantics and wasn't overly concerned with improving the XACML 3.0 text or addressing any of the enhancements we have in mind. Yes, the type of the properties should be explicit. I would have gone with less colons, e.g:

MaxDelegationDepth [Optional]

* If present, an `Integer` that limits the depth of delegation authorized by this policy. See the delegation profile [XACMLAdmin].

Description [Optional]

* A free-form `String` description of the policy.

Yes sure, probably too many colons, I was a bit lazy when I did that, but you can change the form as you wish.

[cdanger]

• Parts sounds a bit catch-all / too generic as a property name (everything is a part).

I agree. It's a placeholder. I needed to name it something and didn't have a pleasing alternative. Something that relates to these being inputs to the combining algorithm would be appropriate. I'd avoid CombinerArgs since we have another use in mind for something called arguments. I'd avoid CombinedElements for not being syntax-neutral. Maybe CombinerInputs or CombinedItems.

That works too for me (probably a slight preference for CombinerInputs).

[steven-legg]

@cdanger, since you dived in to make improvements can I assume that you think this approach to presenting the structures in the XACML core is a good way forward?

[cdanger]

Well, I've been thinking about UML modeling (class diagrams) as an alternative. What appeals to me is that you have a standard graphical representation and you can use a proper UML modeling tool to create and save the UML diagram(s) of the data model to standard XMI format (XML Media Interchange). Then in theory, from the XMI, you can generate the XML/JSON schemas using XSLT. That's the dream at least.

[cdanger]

Another interesting alternative which seems similar to the DMLex but more formally specified (with a JSON schema): JADN (JSON Abstract Data Notation). This is the (UML-based) abstract modeling language proposed and followed by the OpenC2 TC for their agnostic model. They published a note on how to do Information modeling with JADN.

[steven-legg]

JADN is heading in the right direction but it has some limitations. It doesn't define a mapping to XML Schema. It doesn't have a concept of derived structured types so even if it had an XSD mapping that mapping would be quite different to our current XSD. I might be wrong but JADN does not seem to allow recursive nesting, so we could not have policies nested in policies in any mapping.

[cdanger]

JADN is heading in the right direction but it has some limitations. It doesn't define a mapping to XML Schema. It doesn't have a concept of derived structured types so even if it had an XSD mapping that mapping would be quite different to our current XSD.

Yes, but can you do it with the DMLex approach? For the XSD mapping, it will be hard to find that "out-of-box" I think. Still, if we have a JSON representation, we can use a XSLT 3.0 stylesheet to map to the XSD. Regarding the support of defining derived types, indeed it would be great. At least the UML modeling alternative can do that.

I might be wrong but JADN does not seem to allow recursive nesting, so we could not have policies nested in policies in any mapping.

I think you're right, it doesn't, according to 2.1 and 3.3.6, I didn't check that :-( . So let's drop the JADN option for now.