OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

xacml-dev message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [xacml-dev] Questions and notes on the JSON Interface specification

The trend is the client side does more and more. Not just as you said the most of the use cases are server to server. Yes, JSON is not just for _javascript_. But _javascript_ is one of the most popular languages used for client side coding. It is not a big deal for the spec to mention _javascript_? The _javascript_ can be used as the spec's test language or reference implementation language.
Best Regard

From: "GRIFFIN, GLENN (GLENN)" <glenngriffin@research.att.com>
To: David Brossard <david.brossard@axiomatics.com>
Cc: "xacml-dev@lists.oasis-open.org" <xacml-dev@lists.oasis-open.org>
Sent: Thursday, January 9, 2014 11:57 AM
Subject: RE: [xacml-dev] Questions and notes on the JSON Interface specification

Hi David,
Thank you for your detailed reply.  I have one general comment, a couple of new issues, and some responses inline.
My general comment is that JSON is not _javascript_.  According to http://json.org/
“JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages,
including C, C++, C#, Java, _javascript_, Perl, Python, and many others. These properties make JSON an ideal data-interchange language.”
Note the words “language independent” and “interchange” (i.e.. between systems).
Yes, it was initially derived from _javascript_, but that web page lists dozens of languages that have supporting libraries, so _javascript_ is only one of many possible languages that this XACML JSON spec must be implementable in.  Also, anything system-internal (e.g. _javascript_’s “-0”) should only be specified in terms of what is sent on the interface, not the internal representation.
This specification is titled “Request / Response Interface based on JSON and HTTP for XACML 3.0 Version 1.0”.  The most important word there is “Interface” because there are two parties involved.
                - a Client, which might be a browser but is actually more likely to be a server of some kind that is trying to handle an action on behalf of their user, and
                - a Server that gets the Request and generates the Response.
While this is guess, it seems likely that the most common use-case for this interface is in a RESTful interface between servers rather than between a browser and a server.  In a typical N-tier architecture the browser pages are relatively light-weight and rely on a server for the business logic, and it would probably be that server that makes the REST/JSON Request to the PEP, not the Browser.  Therefore most of the time _javascript_ would not be used on either end.
In my case, I am building the server-side of this interface, i.e. reading/parsing the Request and generating the Response JSON strings.  I happen to be using Java for implementation, but I could just as well be using C++ or any other language.  This means that every time this spec says “_javascript_” I do not know what it means. Personally I do know _javascript_ so I can usually make a guess, but the point of an interface specification is that I (the reader) am not supposed to guess.  Every time I guess at the meaning it is a potential problem for interoperability with someone who guesses differently.
This is why I believe that anything related to _javascript_ needs to be removed from this document.  If necessary some things could be demoted to non-normative text or put into a “_javascript_ Implementation” section, but the standard specified in the body of the document must be fully implementable in any language.
End of general comment (or rant, as the case may be). 
New Questions discovered in the last couple of days:
- How are Duplicates to be handled?
                The specific case that started this question was, can there be multiple of the same “Default Category” objects, as in:
{ “Request” : {
                “Subject” : {…},
                “Subject” : {…},
                The same thing can be said as:
{ “Request” : {
                “Category” : [
                                { “CategoryId” : “…subject”, … },
                                { “CategoryId” : “…subject”, … }
                which is used for Multiple Decisions.
                There is no problem with the second format because the “duplicate” objects are separate items in the Array.
                Since the second form is allowed, one could infer that the first form is also legal.  However, JSON apparently does not specify what to do with duplicates.  Unfortunately, at least one major parser (Jackson for Java) either throws an error on duplicates or keeps only the last one seen.  This means that we would be unable to accept and correctly process the form with multiple “Subject” objects.
                This also raises the question, what about other objects and members?  Can there be duplicates of them?
Recommendation:  State clearly that objects and members MUST NOT be duplicated in the JSON string.
Recommendation:  Also state explicitly that the “Default Category objects” must not have multiple instances in the Request, and if you need to send multiple instances you must put them in the Category array.
- Default value for XPathVersion
                The XML <RequestDefaults> and <XPathVersion> are both optional, meaning they may be not there, meaning the default value is effectively null.
                By stating that XPathVersion has a Default value, this requires that the receiver of the Request fill in that default value, which makes this not equivalent to the XML.
                We had to ignore (i.e. violate) this part of the spec to make our internal representations eqivilent.
Recommendation: Change the spec to match the XML by saying XPathVersion is optional with no default value.  If the XML version does not need a default value, then no default should be needed just because the Request happened to arrive coded as a JSON string rather than an XML string.
- Do we need to say that the order of members within objects in the JSON string is not important?  I believe that this is true.
Additional comments inline.
From: David Brossard [mailto:david.brossard@axiomatics.com]
Sent: Thursday, January 09, 2014 6:24 AM
Cc: xacml-dev@lists.oasis-open.org
Subject: Re: [xacml-dev] Questions and notes on the JSON Interface specification
Hi Glenn,
First of all, many thanks for a great job on the proofread and my apologies for letting so many mistakes slip through.
See my comments inline.
On Fri, Jan 3, 2014 at 6:23 PM, GRIFFIN, GLENN (GLENN) <glenngriffin@research.att.com> wrote:
The following questions are based on the following document:
Request / Response Interface based on JSON and HTTP for
XACML 3.0 Version 1.0
Working Draft 15
02 September 2013
Any answers to these questions would be appreciated.
- 3.4.2 This appears to contradict the DataType row in the table in section 4.2.4, which says that inference on a list of values cannot be done.
                Since both are normative text, please clarify what is expected:
                                - The receiver MUST infer the DataType for lists of values as per 3.4.2 (see next comment), OR
                                - The receiver MUST NOT infer the DataType for lists of values (as per section 4.2.4.)
Yes, you are right. Section 4.2.4 currently read:
  • In the case of an array of values, the DataType cannot be inferred from the values in the array and the DataType JSON property must be specified.
But it should read
  • In the case of an array of values, inference works as described in section 3.4.2.
- 3.4.2 If the DataType for a list of values must be inferred, what is the complete list of inferences that is required and that is optional?
                This section mentions one example but does not identify the complete set.
                The conditions under which inference is possible and/or required need to be specified.
                Also the words "may not be possible" and "for example" in normative text is confusing.               
Inference is neither optional or required. The list of possible inferences and mapping from a _javascript_ datatype to a XACML datatype is specified in section 3.4.1. We could add a statement in 3.4.2 that says:
Inference for an array of values works according to the inference rules as set in 3.4.1. If a given datatype cannot be inferred and there is no datatype specified then the array of values will be considered as an array of #string.
  • If an array of values contains an integer and a double, then the inference will make the array an array of double.
  • Any other combination of values will make the inference fail
 I understand the word “Inference” in this context to mean “the process of trying to figure out the data type”.  If Inference (i.e. the action of inferring) is not optional and not required, what is it?  Can I, as the server implementer, say “No Inference will be done on Arrays”?  Wouldn’t that make (the action of) Inference optional?
The bottom line question is, should the sender expect the server to attempt to figure out the DataType on arrays if it is not given?  I think you are saying yes, which makes Inference required, right?
Recommendation: State that the server MUST attempt to infer the DataType of arrays.
I found 3.4.1 hard to understand because it confuses the XACML data type with the JSON data type and talks about inference failing without stating the consequence of that failure.
Recommendation:  In the table in 3.4.1 replace the column labeled “Mapping/Inference Rule” with two columns:
                JSON Data Type – for XACML string=string, XACML integer=integer, double=double, Boolean=Boolean, all others are string
                Inferred Data Type – ditto
Since the values in the two columns are identical it may not be strictly  necessary to have both, but having two columns clearly shows the input and output for the inference logic.
This also eliminates the confusing phrase “inference failing” which could mean either  “just pass it as a string” or “Request returns Indeterminate”.
We also have a special case where the DataType is given as double and the value is a JSON integer.
Recommendation:  In the notes at the end of 3.4.1 add the following:
                If the attribute has an explicitly given DataType of double and the value is a JSON integer, the value MUST be converted to a double.
(Alternative: include this in the table row for integer under the Inferred Data Type column.)
For Arrays, I believe that you cannot say it “will be considered as an array of #string” since some of the values might be JSON integer, Boolean or double.
Recommendation:  Use something like the following text to be very explicit in how all cases must be handled:
                If the DataType member is specified on the array and the JSON data type of any item in the array cannot be inferred to be the same XACML DataType by the rules in 3.4.1 the Request must return Indeterminate.
                If the array has no DataType member specified, each item’s XACML DataType must be determined based on its JSON data type and the Inference rules in 3.4.1.  The DataType for the array will then be inferred as follows:
                                - If all items have the same inferred XACML DataType, then that DataType is the DataType for the array.
                                - If the items are a mix of integer and double DataTypes, then the DataType for the array is double and all integer items must be converted to double.
                                - Any other combination MUST cause the Request to return Indeterminate.
(Note: if you do not want to talk about the Request returning Indeterminate, then the phrase “Parsing of the JSON must fail” would work, but not “Inference Fails” since that does not say what the consequence of that is.)
- 3.4.4 says we MUST "handle" the special values NaN, INF, -INF, 0 and -0.  Several points here:
                - Should these _javascript_-only values be in this inter-system specification that can be implemented in any language on either server or client? 
                                Should this section say instead: "These values must never be included in a Request or Response."?
                - It is not stated how the server is supposed to "handle" NaN, INF and -INF values received in a Request. 
                                The text says that those values are passed as quoted strings like this:
                                                "DataType" : "integer",
                                                "Value" : "NaN"
                                We need to know what the server is supposed to do when it receives this string in a Request.
                                (As a point of reference, Java does not have an equivalent to "NaN", "INF", or "-INF".)
                - Is the server ever supposed to generate these values in a Response object?  Under what circumstances would that occur?
                - Likewise, what is a non-_javascript_ client (e.g. a PAP built using Java or C++) to do if it receives these values in a Response?
Very good point: should we exclude these values from the specification and say that only valid numerical values are accepted? A XACML server would likely not accept such a request anyway and return an error (e.g. HTTP 500)
This must still be handled by the server implementation elegantly anyway because nothing prevents a user from crafting a "malicious" XACML request with an attribute of type integer and value "forty-two". The parsing of the request would fail. 
The allowed values for integer fields are defined in the reference [XMLDatatypes], so this section is not needed. That reference covers the “forty-two” example as well, since that is an illegal value according to the XML spec.
By the way, I think that the response from the server would be HTTP 200 OK with a body containing a JSON XACML Response object with a Result with Status = Indeterminate.
(The HTTP transport worked fine, the server got and parsed the message but there was something bad in the message contents.)
If you feel it is important to mention these values explicitly they should be put into a separate “_javascript_ Mapping” section with the statement that they must not be sent on the interface.
- 4.2.2 For CategoryId the default value says:
                "None – the identifier used in the XML representation shall be used in its JSON representation except where shorthand notations have been defined."
                Are there shorthand notations defined for CategoryId? 
                If so, where are they listed?
                If not, should the reference to shorthand notations be removed?
Good point again. I suggest we introduce a section (the existing section moves to that defines a shorthand definition for standard XACML categories:
  • urn:oasis:names:tc:xacml:3.0:attribute-category:resource --> Resource
  • urn:oasis:names:tc:xacml:3.0:attribute-category:action --> Action
  • urn:oasis:names:tc:xacml:3.0:attribute-category:environment --> Environment
  • urn:oasis:names:tc:xacml:1.0:subject-category:access-subject --> Subject
  • urn:oasis:names:tc:xacml:1.0:subject-category:recipient-subject  --> RecipientSubject
  • urn:oasis:names:tc:xacml:1.0:subject-category:intermediary-subject  --> IntermediarySubject
  • urn:oasis:names:tc:xacml:1.0:subject-category:codebase  --> Codebase
  • urn:oasis:names:tc:xacml:1.0:subject-category:requesting-machine  --> RequestingMachine
Note that this is in line with the default object names for the 4 default categories, Resource, Action, Environment, and Subject.
Yes, I agree that we need such a section.
While the names you suggest are in line with the Default Category object names, that naming plan is inconsistent with the way that shorthand names are defined for the DataTypes.
We prefer the consistency of the DataType shorthands because they are easy to handle programmatically (just cut off everything before the last colon or hash-mark).  That is how I am initializing my internal map of shorthand-to-Identifier conversion and it works nicely.  Changing the name (capitalization, removing text) makes it much harder since each mapping has to be hard-coded explicitly.
By the way, perhaps the names of the Default Category objects should be re-visited and made consistent with the DataType shorthands (i.e. use lower case).
- 4.2.4 The (normative) table definition says the Property name is "AttributeId" but all the examples use "Id".
                For backward compatibility with systems that are implementing earlier versions of this spec, perhaps both should be allowed, but this is currently a discrepancy.
This is clearly a mistake. Early on in the spec, I wrote that we should try to keep the same object names to element names to avoid people having to learn yet another nomenclature. This means that AttributeId is a better name. But then it makes the JSON a little bigger for no good reason which in turn means that id is a better name. I suppose the name "id" was not used in the XML spec because id is a reserved attribute name.
If we do decide to keep "Id" as in the examples instead of "AttributeId" as in the table, we should make sure all objects that have used AttributeId (e.g. AttributeAssignment) are updated accordingly.
I checked my own implementation and I use "AttributeId".
I prefer “AttributeId” because it is clearer.  The extra 9 chars/attribute shouldn’t kill us, especially compared with the over-all savings wrt XML.  Also the Category object has a field named “Id” which is not a conflict because of scope but can make it harder for people to read the raw JSON when they have to.
However there is existing code that uses “Id”, so I would like to see the spec say “AttributeId” with “Id” for the same purpose being deprecated.  Can we do that?
- 4.2.4 says that Value can be of type "Number".  Where is "Number" type defined?  Does it include hexBinary and base64Binary?
                Did this really mean "integer, double"?
                Does the statement "Single instance or array of Data Types listed in 3.4.1" mean the same thing, or is something else intended?
Number is a reference to the _javascript_ number datatype as defined in http://www.w3schools.com/js/js_datatypes.asp. This table shows the _javascript_ datatypes. A _javascript_ number maps to either of an integer or a double in XACML. 
Now that I read the spec again, I am not sure I like the statement Array of String and Number where the String values represent a numerical value. Either we have an array of string or we have an array of numerical values but not a mix. That would be too expensive to process. Is that what you meant with "single instance or array..."? I couldn't see that phrase in WD15.
Yes, that is what I meant.  I was not referencing WD15.
I really think we should not reference the _javascript_ definitions.  Based on my screed at the top of this mail, I believe that the “type” column needs to be changed to “XACML DataType” since that is what is being defined by this spec.  The values then become “Single value or array.  See 3.4.1 and 3.4.2”.
- 4.2.4 Can the array of Attribute objects be empty?  I.E:
                "Attribute": []
Yes, that's allowed according to the XACML spec. 
- 5.1 and 5.2 9 Attributes in the Response: What does "respects" mean in 5.2.9? 
                Is this intended to mean "Identical to"?  The class diagrams for the Request and Response are different:
                - Request calls the object "Category", Response calls it "Attributes" (plural) - Are they different?   If they represent the same data, shouldn't they be the same?
                - Request uses the field "CategoryId", Response calls it "Category".  Should they be the same?
All very good points. I can only apologize for being sloppy. We decided early on that the name Attributes was confusing and that we should rename it to Category instead. We renamed it in the Request but not in the response. We should actually also rename it in the response. This is one place where we break away from the XACML term to introduce a JSON-specific term.
Essentially a request is an array of Attributes which in turn contains an array of Attribute. A response can contain the attributes sent in the request and therefore needs the same representation.
So, here, we should reword and say "identical to", decide on CategoryId or Category, and decide to call Attributes Category in the Response to be in line with the Request. 
One more point – the XML spec says that the Response Attributes/Category can contain the Content and xml:id sent in the input.  These seem to us to be useless in the output and would just make it bigger.  In the case of Content, considerably bigger.  Should we say in the JSON spec that they are not included in the Response?
Minor points:
- 3.4.1 This spec is for inter-system communication where sender and receiver may be using different processing languages. 
                The normative description of the format should be written in terms of a standard, not in terms of a single language (e.g. _javascript_).
That's what the original XACML specification is for. The XACML specification is neutral. This is an adaptation to JSON (and therefore _javascript_). 
                Also, the description of the "Mapping/Inference Rule" is confusing because all of the data types except boolean, integer and double are received as JSON quoted strings,
That's true. The idea is to avoid having to specify a data type. In my experience, most of our customers use string anyway. If they don't then they can specify the datatype which will be encoded as JS strings of course. 
                and according to the first line in this table strings are inferred to be Strings.  Perhaps the other data types should say something like "Received and processed as JSON string"?
True. Where would you add this statement? 
See my suggestion in the discussion on Inference.
- The example shows an Attribute with a single object, not an array of objects.  To avoid confusion it should be:
                "Attribute": [ {....
- Example in is missing ending </Catalog> in both XML and Base64 versions.
- Many examples are missing objects, which can lead to confusion.  For example should be:
                { "Request" : {
                                                "Content\" : \"<?xml version=\\\"1.0\\\"?><catalog> ....
Regarding the examples, I had the ambition to regenerate examples from my code rather than write them by hand as was the case in this version.
Many many thanks for this thorough read-through. I'll work on a new version to fix these ASAP. It'd be great to plan an interop at some point too. Are you implementing your own JSON wrapper? If so, in what language?
Not sure what you mean by a JSON wrapper.  I’m building a Request parser that converts to our internal Java objects and a Response generator that takes our Java objects and creates the corresponding JSON string.

David Brossard, M.Eng, SCEA, CSTP
Product Manager
+46(0)760 25 85 75
Axiomatics AB
Skeppsbron 40
S-111 30 Stockholm, Sweden
LinkedIn: http://www.linkedin.com/companies/536082
Web: http://www.axiomatics.com/
Twitter: http://twitter.com/axiomatics

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]