More notes on the JSON Interface Specification

We found the following issues and questions while implementing and testing the JSON Response. This is a follow-on to my previous email “Questions and notes on the JSON Interface specification” that was posted here 1/3/14.

Responses and discussion are always welcome.

Thanks,

Glenn

- 3.4.3 The XPathCategory must be the same as the category that the attribute is contained in, which means that the value can be inferred.

(The requirement that XPathCategory == category may come from the Core spec 5.30 section under ContextSelectorId, but I'm not sure.)

Should this be made optional with a default value of the containing category?

This would save a moderate number of characters.

(Side note: I cannot find a complete definition of the “urn:oasis:names:tc:xacml:3.0:data-type:xpathExpression” data type in the Core spec.

There is a partial discussion in A.2, but it does not give an exact definition using "<xs:...>" so it is not clear where the various requirements come from.

For example, where is it stated in the Core or related spec that XPathCategory is required?

Since the JSON is supposed to be equivalent to the XML and the XML is the basis for the Core spec, the JSON requirements are derivative from the XML.

If there is a complete definition anywhere it would be helpful to point to it.)

Recommend: Add a reference to the XPathExpression definition in XML.

Recommend: State that the XPathCategory must match the CategoryId of the category containing the attribute.

Make it Optional with the default being the CategoryId from the containing category.

- 5.2.3 Status does not actually say whether the StatusCode is mandatory or optional.

Recommend: State that the StatusCode is optional (as per the Core spec).

- 5.2.3 StatusDetail

- If the contents "can" contain XML, could it also contain something else? Is this supposed to contain MissingAttribute objects (the only things defined for it in the Core spec)?

If the JSON spec is supposed to ensure equivilence with the Core spec, shouldn't this actually be fully defined in JSON rather than some vague XML?

Recommend: Define this in JSON, including the MissingAttributeDetail object.

IF NOT Defning in JSON:

- Should the generated XML include newlines and indenting?

Spaces and newlines are significant in XML so it may be necessary to state what client and server should expect in this string.

Remember, the server is generating this string which the client needs to comprehend, so this spec must exactly describe the contents or the systems won't inter-operate.

- Should we use shorthand for DataType? This is tricky because this is XML (which is specified in XACML Core without shorthands) being wrapped in JSON (which has shorthands).

We assume that since the format of the contents is XML that it should not use shorthand.

This should be stated explicitly.

Recommend: State that the arbitrary XML MUST (or MUST NOT) use whitespace and state the rules for use of newlines and indentation.

Recommend: State that shorthand notation MUST NOT be used in the XML.

Recommend: State that order is significant in XML even though it is not significant in JSON.

Recommend: Include an example, e.g.:

{

"Response" : [ {

"Status" : {

"StatusCode" : {

"Value" : "urn:oasis:names:tc:xacml:1.0:status:missing-attribute"

"StatusMessage" : "some status message",

"StatusDetail" : "<MissingAttributeDetail><AttributeValue>doh</AttributeValue><AttributeValue>5432</AttributeValue><AttributeValue>meh</AttributeValue><Category>urn:oasis:names:tc:xacml:3.0:attribute-category:action</Category><AttributeId>urn:oasis:names:tc:xacml:2.0:action:purpose</AttributeId><DataType>http://www.w3.org/2001/XMLSchema#string</DataType><Issuer>an Issuer</Issuer></MissingAttributeDetail>"

"Decision" : "Indeterminate"

}]

}

(Opinion: It would be much better to define it in JSON rather than deal with the XML issues.)

- 5.2.4 Child StatusCode: XML spec says StatusCode may contain

<StatusCode> [Any Number]

but the xml definition says

<xs:sequence>

<xs:element ref="xacml:StatusCode" minOccurs="0"/>

</xs:sequence>

which means "Optional", not "Any Number".

We are interpreting this to mean a StatusCode may contain 0 or 1 child StatusCode, not an array of StatusCodes.

The text in 5.2.4 says "sequence of StatusCode objects" which implies an unbounded array and is confusing to the reader.

Recommend: In the sentence starting with "In addition, the StatusCode..." replace "a sequence of StatusCode objects" with "a single child StatusCode object".

- 5.2.5-5.2.8 Obligations and Advice: An example would be nice:

"Obligations" : [ {

"Id" : "urn:oasis:names:tc:xacml:1.0:action:implied-action",

"AttributeAssignment" : [ {

"Issuer" : "obligation-issuer1",

"Value" : "Bart",

"Category" : "urn:oasis:names:tc:xacml:3.0:attribute-category:resource",

"DataType" : "string",

"AttributeId" : "urn:oasis:names:tc:xacml:1.0:subject"

}, {

"Issuer" : "obligation-issuer2",

"Value" : "Ned",

"Category" : "urn:oasis:names:tc:xacml:3.0:attribute-category:resource",

"DataType" : "string",

"AttributeId" : "urn:oasis:names:tc:xacml:1.0:subject"

} ]

}, {

"Id" : "urn:oasis:names:tc:xacml:1.0:subject-category:intermediary-subject",

"AttributeAssignment" : [ {

"Issuer" : "obligation-issuer3",

"Value" : "Maggie",

"Category" : "urn:oasis:names:tc:xacml:3.0:attribute-category:resource",

"DataType" : "string",

"AttributeId" : "urn:oasis:names:tc:xacml:1.0:subject"

}, {

"Issuer" : "obligation-issuer4",

"Value" : "Homer",

"Category" : "urn:oasis:names:tc:xacml:3.0:attribute-category:resource",

"DataType" : "string",

"AttributeId" : "urn:oasis:names:tc:xacml:1.0:subject"

} ]

Recommend: Add an example.

- 5.2.8 AttributeAssignment: Is the DataType always optional or just when the type can be inferred from the JSON representation?

Internally we always have the DataType, so just to be safe we are opting to always include it in the Response.

Also, I don't know how universal this is but I had trouble understanding that while the Values in Attributes objects can be arrays,

the Values in AttributeAssignments can only be single value.

Recommend: State that the DataType is optional when the value is of type boolean, integer, double or string and required otherwise.

Recommend: Add something like this: Unlike the Values in the Attributes which can be arrays, the Value in the AttributeAssignment must be a single value.

- 5.2.9 Attributes (or Category) and the Default Category objects:

When a Request contains one of the standard categories it can be encoded either as an item within the Category array or as a stand-alone higher-level object.

Because a Request may contain multiples of the same Category it can even include some in each. For example

{"Request": {

"Category": [{

"CategoryId": "urn:oasis:names:tc:xacml:1.0:subject-category:access-subject",

"Attribute": [{…, IncludeInResult=true}]

{

"CategoryId": "urn:oasis:names:tc:xacml:1.0:subject-category:access-subject",

"Attribute": [{…, IncludeInResult=true}]

}

}]

"Subject": [{

"Attribute": [{…, IncludeInResult=true}]

{

"Attribute": [{..., IncludeInResult=true}]

]}

}

However the Response has no concept of Default Category objects. Therefore all Attributes are returned in the same way:

{"Response" : [

"Result" : {

"Decision": "Permit",

"Category" : [

{ "CategoryId": "urn:oasis:names:tc:xacml:1.0:subject-category:access-subject",

"Attribute: [

{…, IncludeInResult=true},

{…, IncludeInResult=true}

]

}

]}

Recommend: Add text to 5.2.9 stating that the Default Category objects are not used in the Response

and all Attributes/Category objects are returned in the same way as items in the Category array.

(This would be in addition to saying that the Content and xml:id ("Id") are not included in the Response, as mentioned in my previous mail.)

Also we should state that IncludeInResult is not sent in the Response.

Also would not hurt to state "DataType MUST be included when the value is not of type boolean, integer, double or string."

- 5.2.10 PolicyIdentifier

An example would be helpful. One of our tests produces the following, which I think is correct:

"PolicyIdentifier" : {

"PolicyIdReference" : [ {

"Id" : "idRef1",

"Version" : "1.2.3"

}, {

"Id" : "idRef2_NoVersion"

} ],

"PolicySetIdReference" : [ {

"Id" : "idSetRef1",

"Version" : "4.5.6.7.8.9.0"

}, {

"Id" : "idSetRef2_NoVersion"

} ]

}

Errata:

In my previous mail I said that there cannot be duplicates of the Default Category objects.

While strictly true I now see that multiple instances are allowed by using an array.

Therefore my previous Recommendation that the Category objects be used for multiple instances of the Default Category objects should be ignored.

The following are opinions rather than issues with the specification.

- What to call the list of categories: "Category" vs "Attributes"

While I agree that "Category" is much more meaningful than "Attributes", the fact is that the Core XACML specification uses "Attributes".

I would suggest that most people will not use just the JSON specification but rather will be working with both.

Having different names for the same thing is confusing, especially when you want to talk with someone else in the XACML community and they use the other term.

(We have already run into that here talking about how messages map between XML and JSON, and it just adds difficulty.)

In my opinion this makes life harder without any significant benefit and should be deprecated and changed back to the Core standard.

- Default Category Objects

While the Default Category objects seem simpler to use, they present several difficulties:

- Inconsistent naming with the corresponding objects in the Category array. E.g. access-subject => Subject (without the "access")

- Relationship with the same category objects in the Category array can potentially be confusing.

- These are not symmetrical because they are not used in the Response (when IncludeInResult=true).

- This is something that people using the Core XML interface cannot do and won't understand in discussions, which can be confusing.

The savings in text characters by not having them within the Category array is minimal,

and within the server they have to be converted to the same internal representation as the category objects,

so it is not clear that introducing another non-Core feature in the interface is worth the added complication.

xacml-dev message