Language Spec request for change: OpenC2 Response kvps Data Type

[Brian Berliner <Brian_Berliner@symantec.com>]

These comments are related to Language Spec PRD-01, page 20 lines 53-54 and page 28 lines 22-28.

 

The current version of the spec has flattened many types of responses in the OpenC2 Response payload, including top-level fields like âstringsâ, which can hold a generic Array of String and âintsâ, which can hold a generic Array of Integers. The spec additionally defines the âkvpsâ field which can hold a generic Array of Key-Value pairs. The limitation with the schema, however, is that these Key-Value pairs are not really generic key-value pairs as the spec implies, but is limited to Values that are exactly of type âstringâ (if you look at the definition for the KVP type on page 28). This restriction greatly limits what can be returned as a generic key-value pair in a response to be whatever can be serialized into a âstringâ value. You can see this demonstrated on page 41 of the spec where the example response for a âquery/propertiesâ request returns the following:

 

{

                "status": 200,

                "kvps": [["battery_percentage", "0.577216"]]

}

 

We see two things happening here. One is that it is actually an âArray of Array of (String, String)â. Which is a bit weird. When most people think about Key-Value pairs in JSON, they are thinking about a Map<String, Object>, where the keys are Strings and the values are any other standard JSON thing (a string, an int, an array (startswith â[â) or an object (startswith â{â). As such, most people would expect, in this example, that the battery_percentage example would return a Real Number instead of a string, so the ânaturalâ thing that Iâd expect to see in âkvpsâ here would look like this:

 

{

                "status": 200,

                "kvps": {

                        âbattery_percentageâ: 0.577216

                }

}

 

No arrays, just a Map<String, Object>, where the Object in this case is Number. A side-effect of changing this from âJSON stringâ to âJSON objectâ, is that the actuator can return richer data more naturally if desired, like so:

 

{

                "status": 200,

                "kvps": {

                        âbattery_percentageâ: {

âcurrentâ: 0.577216,

âcharged_atâ: 1547506988,

âstatusâ: 12,

âmodeâ: âhighâ

âvisible_on_displayâ: true

                }

}

 

Since âkvpsâ is currently only <String, String>, there is no way to effectively communicate this kind of rich response without adding string serializations to everything (or serializing the JSON sub-objects themselves into Strings and back, which is never desirable). So, I would propose that âkvpsâ can simply hold a âMap<String, Objectâ instead of âArray of Array of (String, String)â.

 

I was instructed to send this proposal to the TC mailing list as opposed to creating a GitHub issue directly, but my desire is that we have a discussion/resolution on this matter before the next Public Review period of the Language Spec.

 

Cheers,

 

                -Brian