KPath Matching

Overview

A number of operations (including INAP/CAMEL, MAP, OSD, PI, DIAMETER and various DB operations) have built-in support for Pass/Fail checks by defining an array of tests within the operation.

The kpath attribute is a top-down navigation string which is used to navigate from the top-level of a structure to find the value to check. Each segment of a KPath is separated by the full stop . character.

e.g. returned.rows.[2].a

If the key that you need to match contains a full stop (e.g. if you are dealing with statistics counter names) then place a backslash in front of the full stop to “escape” it.

e.g. statistics.num\.started.[0]

When using kpaths in JSON the escape character itself needs escaping,

e.g. [ “kpath”: “statistics.num\\.started.[0]”, “value”: 3 ]

Segments are processed left to right as follows:

OBJECT Segments

A named segment e.g. returned expects that the current element in the navigation is an OBJECT.

• If the specified segment name is present as a key in the OBJECT then navigation will move to the next KPath segment and will continue processing within the corresponding OBJECT value.

• If the specified segment name is not a key in the OBJECT then the navigation will stop and the matched value is considered null (equivalent to Perl undef).

Note: Unexpected Single-Element arrays are an exception, as described below.

ARRAY Index Segments

A segment in square brackets such as [2] expects that the current element in the navigation is an ARRAY.

• If the specified segment index is present within the ARRAY/ARRAY then navigation will move to the next KPath segment and will continue processing within the corresponding ARRAY/ARRAY value.

• If the specified index does not exist in the ARRAY then the navigation will stop and the matched value is considered null (equivalent to Perl undef).

Note: Missing Single-Element arrays are an exception, as described below.

ARRAY of Hash Filtering

A segment specifying a key=value in square brackets e.g. [TAG=23] expects that the current element in the navigation is an ARRAY of OBJECTs.

• The current ARRAY will be filtered by examining each OBJECT in the ARRAY and matching it if and only if the OBJECT has the specified property with the specified value.

Processing will then continue with the remainder of the KPath, using the filtered ARRAY in place of the original array.

Scalar to ARRAY Splitting

A segment specifying a split function with a single quoted parameter e.g. split(',') expects that the current element in the navigation is a SCALAR value.

• The current SCALAR will be split into parts using the provided fixed separator character(s) to give an ARRAY with one or more elements.

Processing will then continue with the remainder of the KPath, using the new ARRAY in place of the original SCALAR.

Default Value

A segment specifying a default function with a single quoted string or integer parameter e.g. default(‘steve’) or default(10) will test if the current element in the navigation is defined or undefined.

• If the current element in the navigation is undefined, the KPath will stop processing and will return the default value as the matched result.

• If the current element in the navigation is defined, the KPath will advance to the next KPath segment, and use that to consider the current element.

Missing Single-Element ARRAY

If the current KPath segment is [0] (expecting ARRAY/ARRAY), but the navigation context is a scalar or OBJECT , then the segment [0] will be silently discarded and processing will proceed with the next segment.

This convention is required in order to handle returned NCC Provisioning Interface (PI) where the syntax for a returned scalar value is identical to the syntax for a returned single-element array.

Unexpected Single-Element ARRAY

The converse is also true. If the current KPath segment is a named segment (expecting ARRAY) but the navigation context is a single-element ARRAY, then the filter will navigate into the single array element and will continue attempting to match the same named segment.

Again, this is done in order to allow matching of ambiguous PI results.

Examples

Consider the following object:

{
    "returned": {
        "success": 1,
        "rows": [
            {   "a": "A0 value", "b": "B0 value"  },
            {   "a": "A1 value", "b": "B1 value"  },
            {   "a": "A2 value", "b": "X,YY,ZZZ"  }
        ],
        "group": [
            {   "name": "admin"   }
        ]
    }
}

The KPath returned.success would evaluate to 1.

The KPath returned.error would evaluate to null (missing named segment error).

The KPath returned.rows.[1].b would evaluate to "B1 value" (arrays are zero-based index).

The KPath returned.rows.[0].c would evaluate to null (missing named segment c).

The KPath returned.[0].success would evaluate to 1 (missing single-element array silently skipped).

The KPath returned.group.name would evaluate to "admin" (unexpected single-element array silently accepted).

The KPath returned.group.name.default(‘steve’) would evaluate to "admin" (default value not needed).

The KPath returned.group.age.default(‘10’) would evaluate to 10 (default value applied to missing value).

The KPath returned.rows.[2].b.split(',').[2] would evaluate to "ZZZ" (split method).