CBOR Pointer: Selecting Elements of Concise Binary Object Representation (CBOR) Documents

3.1. Implicit Pathspecs

The semantics of an implicit pathspec depend on the type of the parent element.¶

• If the parent element is an array, it returns the appropriate element:¶

  • if the pathspec is an unsigned integer, it matches the element at that zero-based position from the start of the array;¶

  • if the pathspec is a CBOR negative integer, hexadecimal 0x20 matches the last element of the array, with higher numbers moving backwards through the array¶

• If the parent element is a map, the pathspec matches if it matches one of the map keys of the map. It returns the value of the map key.¶

• If the parent element is a tag, the pathspec matches if it matches the tag number. It returns the value inside the tag.¶

• If the parent element is a byte string, the parent element is re-evaluated as embedded CBOR. The pathspec is evaluated as above if the type after byte string decoding is an array, map, or tag.¶

• If the root element is a CBOR sequence, and the pathspec is evaluated as if the entire sequence were wrapped in an array.¶

3.2. Examples with Implicit Pathspecs

Given the following source document, the table below gives the corresponding result.¶

777([
  [
    [1, "two", 3],
    [4, "five", 6]
  ],
  {
    1: "abc",
    -18: h'1234',
    "x": null,
    35: 1(1760686166),
    "y": [ "l", "m"]
  },
  <<{
    2: 45,
    "pdq": false
  }>>,
  27,
  h'abcdef'
])

3.3. Explicit Pathspecs

Explicit CBOR Pointers use tags to match a specific type of element for each pathspec. If the type of the parent element matches the expected type, the matching rules and return values are the same as for implicit pathspecs, except that in explicit pathspecs, byte string encoded strings are unwrapped in a separate pathspec. Explicit CBOR Pointers are always wrapped in the tag <TBD1>. Each element in an explicit CBOR Pointer is either the simple value <TBD0> for byte string encoded elements, or a pathspec tagged with one of the following tags:¶

Converting one of our implicit pathspec examples ([777, 1, "y", 1]) into explicit pathspecs, gives us:¶

TBD1([          # Explicit pathspecs
    TBD4(777),  # Tag 777
    TBD2(1),    # 2nd Array element
    TBD3("y"),  # Map key "y"
    TBD(1)      # 2nd Array element
])

Both the implicit and explicit version return the value ["m"]. However, an explicit pathspec tag referring to a different type would return null. Consequently explicit pathspecs are useful where different types could be in the same location and the distinction is semantically meaningful.¶

Explicit pathspecs involving embedded byte strings require an additional pathspec element. For example, the equivalent of the implicit pointer [777, 2, 2] (which returns [45]) is the following:¶

TBD1([            # Explicit Pathspecs
    TBD4(777),    # Tag 777
    TBD2(2),      # 3rd Array element
    simple(TBD1), # decode byte string
    TBD3(2)       # Map key 2
])

This property of explicit pathspecs makes it possible to return the entire decoded value of an encoded byte string. For example, the following explicit pointer applied to our original example:¶

TBD1([            # Explicit Pathspecs
    TBD4(777),    # Tag 777
    TBD2(2),      # 3rd Array element
    simple(TBD1)  # decode byte string
])

returns [ {2:45, "pdq":false} ] as its result.¶

3.4. Array Filters

Array filters allow selecting a single array element by evaluating the contents of those elements against another CBOR Pointer. This filter pointer is evaluated against each array element inside the parent element where the filter was invoked, in turn. An array filter is tagged with tag TBD6.¶

For example, if a filter were invoked at the following parent element of our initial example document, the filter pointer is evaluated once for each of the two elements of the parent.¶

[
  [1, "two", 3],
  [4, "five", 6]
]

The CBOR Pointer Filter below selects the entire matching array element under the parent element, where the second element ([TBD2(1)]) matches the value "five":¶

TBD6([           # Array Filter
    [            # Per-element CBOR Pointer
        TBD2(1)  # 2nd Array element
    ],
    ["five"]     # value to match per-element pointer result
])

If multiple elements or no elements would be returned after evaluating an array filter, the result of the entire array filter is null.¶

When evaluating the CBOR Pointer (containing an array filter) below, against the original example, the result is [6]:¶

TBD1([            # Explicit Pathspecs
    TBD4(777),    # Tag 777
    TBD2(0),      # 1st Array element
    TBD6([        # Array Filter
      [             # Per-element CBOR Pointer
        TBD2(1)       # 2nd Array element
      ],
      ["five"]      # value to match per-element pointer result
    ]),
    TBD2(2)       # 3rd Array element
])

6.1. Normative References

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8494]

Wilson, D. and A. Melnikov, Ed., "Multicast Email (MULE) over Allied Communications Publication (ACP) 142", RFC 8494, DOI 10.17487/RFC8494, November 2018, <https://www.rfc-editor.org/rfc/rfc8494>.

6.2. Informative References

[RFC6901]

Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation (JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, April 2013, <https://www.rfc-editor.org/rfc/rfc6901>.