YAML Path Definition

Proposal for the subset to be supported by the OVAL yamlfilecontent test

Overview

This implementation is a subset of the intersection between JSONPath and YAML Path, and it focuses on addressing elements inside YAML files (node descriptors). The querying capabilities are limited to sequence slicing.

Example YAML structure:

foo:
  - bar: &bar True
    first: First Bar
    second: 2
    arr: [1, 2, 3]
  - baz: False
    other_bar: *bar
    first: First Baz
    some.el/here: Delimiters...

Example JSON structure:

{
    "foo": [
        {
            "bar": true,
            "first": "First Bar", 
            "second": 2,
            "arr": [1, 2, 3]
        },
        {
            "baz": false,
            "other_bar": true,
            "first": "First Baz",
            "some.el/here": "Delimiters..."
        }
    ]
}

Delimiters

Dot-notation (.) is the only supported notation to define key path segments. Both key and index path segments could also be defined by square brackets ([, ]).

$.foo[0].bar or .foo[0]['bar'] or ['foo'][0].bar

Other special symbols

A path might be prefixed by a dollar sign and a comma ($) but this prefix is for compatibility with JSONPath and is not mandatory, implicit document root segment would be created internally. Then, if the first segment is a key segment, described in dot-notation, the initial dot (.) is also not mandatory. For example, these paths are equal: $.el, .el, el, ['el']. And they all address the value stored in the "el" key of the top-most map of the document.

Path Segment Types

Map Key

.map.key or .map['key']

$.foo[0].second = ['foo'][0]['second']
== 2

Sequence Index

.array[<number>]

$.foo[0]
== {"bar": True, "first": "First Bar", "second": 2}

Sequence Slice

.array[<number (start index)>:<number (stop index, exclusive)>:<number (stride)>]

Syntax and behaviour are similar to Python's extended slices.

Start is the first inclusive, zero-based element and stop is the last exclusive element to select. Either or both can be negative, causing the elements to be selected from the end. Either or both can be omitted, effectively marking the first or the last elements (inclusively).

The stride can be empty, omitted completely or greater than 0.

If all elements are omitted ([:] or [::]) the slice is considered to be all-inclusive and equivalent to [0:MAX_INT:1].

$.foo[0].arr[0:3] = foo[0].arr[0:] = foo[0].arr[::1]
== [1, 2, 3]

Anchor

&anchor

Matches elements starting from the given anchor instead of the document root. This segment is only sensible in paths for YAML documents as there is no anchors/aliases concept in the JSON specification.

$.foo[1].other_bar = &bar = foo[0].bar
== True