Possible mismatches

This section summarizes potential errors you may encounter when crafting search queries. Unlike more obvious JSONPath parse errors for which you receive an explicit error response, these conceptual errors may result either in an empty set of search results, or far more search results than you intend:

  • Testing a location vs. its value. The first expression below matches all origin hostname values. If you want to change a specific value, make sure to specify it, as in the second expression. Otherwise the range of your search results and subsequent patch operation may be wider than you intend:

      $..behaviors[?(@.name == 'origin')].options.hostname
      $..behaviors[?(@.name == 'origin')].options[?(@.hostname == 'old.example.com')].hostname
  • Testing existence vs. truth. The first match expression below tests whether the enabled option exists, not as a shorthand for whether it evaluates as boolean true as in many programming environments. Like the second match expression, it matches both true and false values, likely a wider match than intended. Use the third type of expression to refine the test to specify a true value:

      $..behaviors[?(@.name == 'http2'].options[?(@.enabled)].enabled
      $..behaviors[?(@.name == 'http2'].options.enabled
      $..behaviors[?(@.name == 'http2'].options[?(@.enabled == true)].enabled
  • Mismatching type. The data type of any value you're trying to match needs to be the same as the one in the rule configuration. This example yields no results because it matches a 'true' string value rather than a true boolean value:

      $..behaviors[?(@.name == 'http2')].options[?(@.enabled == 'true')].enabled
  • Mismatching case. String matches and regular expression tests are case-sensitive. The first match below yields no data because the behavior is named cpCode, not cpcode. The second pattern match yields either name, in case you're not sure:

      $..behaviors[?(@.name == 'cpcode'].options.value.id
      $..behaviors[?(@.name =~ /cp[Cc]ode/].options.value.id
  • Object values. PAPI's implementation of JSONPath doesn't allow you to test an object's scalar value directly on the matched node. The first match below fails, but the second succeeds:

      $.behaviors[?(@.name == 'origin')].options.hostname[?(@ == 'old.example.com')]
      $.behaviors[?(@.name == 'origin')].options[?(@.hostname == 'old.example.com')].hostname
  • Matches execute within rules. All JSONPath matches execute within a configuration's set of rules, not the outermost object from the Get a rule tree JSON response. This example fails to match the top-level default rule, because the expression's initial rules segment is unnecessary:

      $.rules.behaviors[?(@.name == 'origin')].options.hostname[?(@ == 'old.example.com')]

    Note that although you don't specify rules at the start of your bulk search JSONPath query expression, the JSON Pointer search results still always include it as its first path segment:

      "matchLocations": [