Segments of a YAML Path

1. YAML Path Standard
2. Illustration

YAML Path Standard

A YAML Path is comprised of segments. Each segment indicates part of the navigation instructions through the source data. Some segment types select a single precise node while others are capable of selecting zero, one, or more than one. Most segment types move the internal pointer through the source data, adjusting the basis for the next segment. Not all do. YAML Path defines these segment types:

• Anchors
• Array Elements
• Array Element Searches
• Array Slices
• Collectors
• Hash Attribute Searches
• Hash Keys
• Hash Slices
• Pass-Through Selections for Arrays of Hashes
• Search Keywords
• Set Values
• Wildcard Segments

YAML Paths support one of two segment separators per path:

• Dot (.); as in: segment1.segment2.segment3
• Forward-Slash (/); as in: /segment1/segment2/segment3

For any YAML Path, these two types of segment separators cannot be mixed. When using the forward-slash separator, the first character of the YAML Path MUST be a forward-slash. When using the dot separator, this is optional; the first character does not need to be a dot.

Illustration

Whether using dot- or forward-slash notation, every YAML Path is comprised of at least one navigation segment. Whether fetching, changing, or creating new data, all YAML Paths serve the same purpose: to indicate where within the data the requested operation is to be performed. Take the following data for example:

hash:
  scalar_value: data
  array_values:
    - element0
    - element1
    - element2
  array_of_hashes:
    - id: 0
      name: something
    - id: 1
      name: something else

To navigate to element1 of the array_values key within the complex hash data structure, you'd use the following YAML Path: hash.array_values[1] (dot-notation) or /hash/array_values[1] (forward-slash notation). Both of these forms of the YAML Path are comprised of 3 segments:

1. hash: A Hash Key; in this case the data root is itself a Hash data structure with hash being one of its top-most keys.
2. array_values: Another Hash Key; in this case it is a child key of the parent hash.
3. [1]: An Array Element Index; in this case selecting the second element of the array, because Arrays use 0-based indexing (the first element of every array is always at index 0).

How would you select an array_of_hashes entity with the phrase else in its name? Along with deterministic selection, YAML Path also provides for searching capabilities, which can return 0 or more results. Using a Hash Attribute Search segment, you could write: hash.array_of_hashes[name % else] and get back the entire matching child Hash, {"id": 1, "name": "something else"}.

Say you needed only the id of the matching record. In this case, you could add another segment to the YAML Path, selecting just the id node: hash.array_of_hashes[name % else].id would yield 1.

Visit each page of the available YAML Path Segment Types for more detail about how each segment works with examples.