KPath

A number of operations (including 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

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.

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.

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.

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.

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.

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).