From 40dffa562b6fa72bb7abc09048507eb7cf41504e Mon Sep 17 00:00:00 2001
From: cgardens <charles@airbyte.io>
Date: Fri, 1 Apr 2022 12:15:37 -0700
Subject: [PATCH 1/5] add JsonPaths class; needs tests

---
 .../io/airbyte/commons/json/JsonPaths.java    | 269 ++++++++++++++++++
 build.gradle                                  |   1 +
 2 files changed, 270 insertions(+)
 create mode 100644 airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java

diff --git a/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java b/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java
new file mode 100644
index 0000000000000..d8df1a2a041b4
--- /dev/null
+++ b/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java
@@ -0,0 +1,269 @@
+/*
+ * Copyright (c) 2021 Airbyte, Inc., all rights reserved.
+ */
+
+package io.airbyte.commons.json;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.node.ArrayNode;
+import com.google.api.client.util.Preconditions;
+import com.jayway.jsonpath.Configuration;
+import com.jayway.jsonpath.JsonPath;
+import com.jayway.jsonpath.Option;
+import com.jayway.jsonpath.PathNotFoundException;
+import com.jayway.jsonpath.spi.json.JacksonJsonNodeJsonProvider;
+import com.jayway.jsonpath.spi.json.JsonProvider;
+import com.jayway.jsonpath.spi.mapper.JacksonMappingProvider;
+import com.jayway.jsonpath.spi.mapper.MappingProvider;
+import io.airbyte.commons.util.MoreIterators;
+import java.util.Collections;
+import java.util.EnumSet;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+import java.util.function.BiFunction;
+import java.util.stream.Collectors;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+// todo (cgardens) - needs a test.
+/**
+ * JSONPath is specification for querying JSON objects. More information about the specification can
+ * be found here: https://goessner.net/articles/JsonPath/. For those familiar with jq, JSONPath will
+ * be most recognizable as "that DSL that jq uses".
+ *
+ * We use a java implementation of this specification (repo: https://github.com/json-path/JsonPath).
+ * This class wraps that implementation to make it easier to leverage this tool internally.
+ *
+ * GOTCHA: Keep in mind with JSONPath, depending on the query, 0, 1, or N values may be returned.
+ * The pattern for handling return values is very much like writing SQL queries. When using it, you
+ * must consider what the number of return values for your query might be. e.g. for this object: {
+ * "alpha": [1, 2, 3] }, this JSONPath "$.alpha[*]", would return: [1, 2, 3], but this one
+ * "$.alpha[0]" would return: [1]. The Java interface we place over this query system defaults to
+ * returning a list for query results. In addition, we provide helper functions that will just
+ * return a single value (see: {@link JsonPaths#getSingleValue(JsonNode, String)}. These should only
+ * be used if it is not possible for a query to return more than one value.
+ */
+public class JsonPaths {
+
+  private static final Logger LOGGER = LoggerFactory.getLogger(JsonPaths.class);
+
+  // set default configurations at start up to match our JSON setup.
+  static {
+    Configuration.setDefaults(new Configuration.Defaults() {
+
+      // allows us to pass in Jackson JsonNode
+      private static final JsonProvider jsonProvider = new JacksonJsonNodeJsonProvider();
+      private static final MappingProvider mappingProvider = new JacksonMappingProvider();
+
+      @Override
+      public JsonProvider jsonProvider() {
+        return jsonProvider;
+      }
+
+      @Override
+      public MappingProvider mappingProvider() {
+        return mappingProvider;
+      }
+
+      @Override
+      public Set<Option> options() {
+        /*
+         * All JsonPath queries will return a list of values. This makes parsing the outputs much easier. In
+         * cases where it is not a list, helpers in this class can assert that. See
+         * https://github.com/json-path/JsonPath in the JsonPath documentation.
+         */
+        return EnumSet.of(Option.ALWAYS_RETURN_LIST);
+      }
+
+    });
+  }
+
+  /*
+   * This version of the JsonPath Configuration object allows queries to return to the path of values
+   * instead of the values that were found.
+   */
+  private static final Configuration GET_PATHS_CONFIGURATION = Configuration.defaultConfiguration().addOptions(Option.AS_PATH_LIST);
+
+  /**
+   * Attempt to validate if a string is a valid JSONPath string. This assertion does NOT handle all
+   * cases, but at least a common on. We can add to it as we detect others.
+   *
+   * @param jsonPath - path to validate
+   */
+  public static void assertIsJsonPath(final String jsonPath) {
+    Preconditions.checkArgument(jsonPath.startsWith("$"));
+  }
+
+  /**
+   * Attempt to detect if a JSONPath query could return more than 1 value. This assertion does NOT
+   * handle all cases, but at least a common on. We can add to it as we detect others.
+   *
+   * @param jsonPath - path to validate
+   */
+  public static void assertIsSingleReturnQuery(final String jsonPath) {
+    Preconditions.checkArgument(jsonPath.contains("*"), "Cannot accept paths with wildcards because they may return more than one item.");
+  }
+
+  /**
+   * Traverses into a json object and replaces all values that match the input path with the provided
+   * string. Throws if no existing fields match the path.
+   *
+   * @param json - json object
+   * @param jsonPath - path into the json object. must be in the format of JSONPath.
+   * @param replacement - a string value to replace the current value at the jsonPath
+   * @throws PathNotFoundException throws if the path is not present in the object
+   */
+  public static void replaceAtWithStringLoud(final JsonNode json, final String jsonPath, final String replacement) {
+    assertIsJsonPath(jsonPath);
+    JsonPath.parse(json).set(jsonPath, replacement).json();
+  }
+
+  /**
+   * Traverses into a json object and replaces all values that match the input path with the provided
+   * string . Does nothing if no existing fields match the path.
+   *
+   * @param json - json object
+   * @param jsonPath - path into the json object. must be in the format of JSONPath.
+   * @param replacement - a string value to replace the current value at the jsonPath
+   */
+  public static void replaceAtWithString(final JsonNode json, final String jsonPath, final String replacement) {
+    try {
+      replaceAtWithStringLoud(json, jsonPath, replacement);
+    } catch (final PathNotFoundException e) {
+      LOGGER.debug("Path not found", e);
+    }
+  }
+
+  /**
+   * Traverses into a json object and replaces all values that match the input path with the provided
+   * json object. Does nothing if no existing fields match the path.
+   *
+   * @param json - json object
+   * @param jsonPath - path into the json object. must be in the format of JSONPath.
+   * @param replacement - a json node to replace the current value at the jsonPath
+   */
+  public static void replaceAtJsonNode(final JsonNode json, final String jsonPath, final JsonNode replacement) {
+    assertIsJsonPath(jsonPath);
+    try {
+      JsonPath.parse(json).set(jsonPath, replacement).json();
+    } catch (final PathNotFoundException e) {
+      LOGGER.debug("Path not found", e);
+    }
+  }
+
+  /**
+   * Traverses into a json object and replaces all values that match the input path with the output of
+   * the provided function. Does nothing if no existing fields match the path.
+   *
+   * @param json - json object
+   * @param jsonPath - path into the json object. must be in the format of JSONPath.
+   * @param replacementFunction - a function that takes in a node that matches the path as well as the
+   *        path to the node itself. the return of this function will replace the current node.
+   */
+  public static void replaceAt(final JsonNode json, final String jsonPath, final BiFunction<JsonNode, String, JsonNode> replacementFunction) {
+    assertIsJsonPath(jsonPath);
+    try {
+      final List<String> foundPaths = getPaths(json, jsonPath);
+      for (final String foundPath : foundPaths) {
+        getSingleValue(json, foundPath).ifPresent(node -> {
+          final JsonNode replacement = replacementFunction.apply(node, foundPath);
+          replaceAtJsonNode(json, foundPath, replacement);
+        });
+
+      }
+    } catch (final PathNotFoundException e) {
+      LOGGER.debug("Path not found", e);
+    }
+  }
+
+  /**
+   * Given a JSONPath, returns all the values that match that path.
+   *
+   * e.g. for this object: { "alpha": [1, 2, 3] }, if the input JSONPath were "$.alpha[*]", this
+   * function would return: [1, 2, 3].
+   *
+   * @param json - json object
+   * @param jsonPath - path into the json object. must be in the format of JSONPath.
+   * @return all values that match the input query
+   */
+  public static List<JsonNode> getValues(final JsonNode json, final String jsonPath) {
+    return getInternal(Configuration.defaultConfiguration(), json, jsonPath);
+  }
+
+  /**
+   * Given a JSONPath, returns all the path of all values that match that path.
+   *
+   * e.g. for this object: { "alpha": [1, 2, 3] }, if the input JSONPath were "$.alpha[*]", this
+   * function would return: ["$.alpha[0]", "$.alpha[1]", "$.alpha[2]"].
+   *
+   * @param json - json object
+   * @param jsonPath - path into the json object. must be in the format of JSONPath.
+   * @return all paths that are present that match the input query
+   */
+  public static List<String> getPaths(final JsonNode json, final String jsonPath) {
+    return getInternal(GET_PATHS_CONFIGURATION, json, jsonPath)
+        .stream()
+        .map(JsonNode::asText)
+        .collect(Collectors.toList());
+  }
+
+  /**
+   * Given a JSONPath, returns 1 or 0 values that match the path. Throws is more than 1 value is
+   * found.
+   *
+   * THIS SHOULD ONLY BE USED IF THE JSONPATH CAN ONLY EVER RETURN 0 OR 1 VALUES. e.g. don't do
+   * "$.alpha[*]"
+   *
+   * @param json - json object
+   * @param jsonPath - path into the json object. must be in the format of JSONPath.
+   * @return value if present, otherwise empty.
+   */
+  public static Optional<JsonNode> getSingleValue(final JsonNode json, final String jsonPath) {
+    assertIsSingleReturnQuery(jsonPath);
+
+    final List<JsonNode> jsonNodes = getValues(json, jsonPath);
+
+    Preconditions.checkState(jsonNodes.size() <= 1, String.format("Path returned more than one item. path: %s items: %s", jsonPath, jsonNodes));
+    return jsonNodes.isEmpty() ? Optional.empty() : Optional.of(jsonNodes.get(0));
+  }
+
+  /**
+   * Given a JSONPath, true if path is present in the object, otherwise false. Throws is more than 1
+   * path is found.
+   *
+   * THIS SHOULD ONLY BE USED IF THE JSONPATH CAN ONLY EVER RETURN 0 OR 1 VALUES. e.g. don't do
+   * "$.alpha[*]"
+   *
+   * @param json - json object
+   * @param jsonPath - path into the json object. must be in the format of JSONPath.
+   * @return true if path is present in the object, otherwise false.
+   */
+  public static boolean isPathPresent(final JsonNode json, final String jsonPath) {
+    assertIsSingleReturnQuery(jsonPath);
+
+    final List<String> foundPaths = getPaths(json, jsonPath);
+
+    Preconditions.checkState(foundPaths.size() <= 1, String.format("Path returned more than one item. path: %s items: %s", jsonPath, foundPaths));
+    return !foundPaths.isEmpty();
+  }
+
+  /**
+   *
+   * @param conf - JsonPath configuration. Primarily used to reuse code to allow fetching values or
+   *        paths from a json object
+   * @param json - json object
+   * @param jsonPath - path into the json object. must be in the format of JSONPath.
+   * @return all values that match the input query (whether the values are paths or actual values in
+   *         the json object is determined by the conf)
+   */
+  private static List<JsonNode> getInternal(final Configuration conf, final JsonNode json, final String jsonPath) {
+    assertIsJsonPath(jsonPath);
+    try {
+      return MoreIterators.toList(JsonPath.using(conf).parse(json).read(jsonPath, ArrayNode.class).iterator());
+    } catch (final PathNotFoundException e) {
+      return Collections.emptyList();
+    }
+  }
+
+}
diff --git a/build.gradle b/build.gradle
index a2a1fee6c0ae1..5a57032271a03 100644
--- a/build.gradle
+++ b/build.gradle
@@ -272,6 +272,7 @@ subprojects {
         implementation 'com.fasterxml.jackson.core:jackson-annotations'
         implementation 'com.fasterxml.jackson.dataformat:jackson-dataformat-yaml'
         implementation 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310'
+        implementation 'com.jayway.jsonpath:json-path:2.7.0'
 
         implementation 'com.google.guava:guava:30.1.1-jre'
 

From 0397dc658ba95c14abb1402f5b187c5eccd5f5d3 Mon Sep 17 00:00:00 2001
From: cgardens <charles@airbyte.io>
Date: Sat, 2 Apr 2022 11:47:59 -0700
Subject: [PATCH 2/5] add tests

---
 .../io/airbyte/commons/json/JsonPaths.java    | 158 ++++++------
 .../airbyte/commons/json/JsonPathsTest.java   | 228 ++++++++++++++++++
 2 files changed, 313 insertions(+), 73 deletions(-)
 create mode 100644 airbyte-commons/src/test/java/io/airbyte/commons/json/JsonPathsTest.java

diff --git a/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java b/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java
index d8df1a2a041b4..3f50a704bb5e6 100644
--- a/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java
+++ b/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java
@@ -102,79 +102,7 @@ public static void assertIsJsonPath(final String jsonPath) {
    * @param jsonPath - path to validate
    */
   public static void assertIsSingleReturnQuery(final String jsonPath) {
-    Preconditions.checkArgument(jsonPath.contains("*"), "Cannot accept paths with wildcards because they may return more than one item.");
-  }
-
-  /**
-   * Traverses into a json object and replaces all values that match the input path with the provided
-   * string. Throws if no existing fields match the path.
-   *
-   * @param json - json object
-   * @param jsonPath - path into the json object. must be in the format of JSONPath.
-   * @param replacement - a string value to replace the current value at the jsonPath
-   * @throws PathNotFoundException throws if the path is not present in the object
-   */
-  public static void replaceAtWithStringLoud(final JsonNode json, final String jsonPath, final String replacement) {
-    assertIsJsonPath(jsonPath);
-    JsonPath.parse(json).set(jsonPath, replacement).json();
-  }
-
-  /**
-   * Traverses into a json object and replaces all values that match the input path with the provided
-   * string . Does nothing if no existing fields match the path.
-   *
-   * @param json - json object
-   * @param jsonPath - path into the json object. must be in the format of JSONPath.
-   * @param replacement - a string value to replace the current value at the jsonPath
-   */
-  public static void replaceAtWithString(final JsonNode json, final String jsonPath, final String replacement) {
-    try {
-      replaceAtWithStringLoud(json, jsonPath, replacement);
-    } catch (final PathNotFoundException e) {
-      LOGGER.debug("Path not found", e);
-    }
-  }
-
-  /**
-   * Traverses into a json object and replaces all values that match the input path with the provided
-   * json object. Does nothing if no existing fields match the path.
-   *
-   * @param json - json object
-   * @param jsonPath - path into the json object. must be in the format of JSONPath.
-   * @param replacement - a json node to replace the current value at the jsonPath
-   */
-  public static void replaceAtJsonNode(final JsonNode json, final String jsonPath, final JsonNode replacement) {
-    assertIsJsonPath(jsonPath);
-    try {
-      JsonPath.parse(json).set(jsonPath, replacement).json();
-    } catch (final PathNotFoundException e) {
-      LOGGER.debug("Path not found", e);
-    }
-  }
-
-  /**
-   * Traverses into a json object and replaces all values that match the input path with the output of
-   * the provided function. Does nothing if no existing fields match the path.
-   *
-   * @param json - json object
-   * @param jsonPath - path into the json object. must be in the format of JSONPath.
-   * @param replacementFunction - a function that takes in a node that matches the path as well as the
-   *        path to the node itself. the return of this function will replace the current node.
-   */
-  public static void replaceAt(final JsonNode json, final String jsonPath, final BiFunction<JsonNode, String, JsonNode> replacementFunction) {
-    assertIsJsonPath(jsonPath);
-    try {
-      final List<String> foundPaths = getPaths(json, jsonPath);
-      for (final String foundPath : foundPaths) {
-        getSingleValue(json, foundPath).ifPresent(node -> {
-          final JsonNode replacement = replacementFunction.apply(node, foundPath);
-          replaceAtJsonNode(json, foundPath, replacement);
-        });
-
-      }
-    } catch (final PathNotFoundException e) {
-      LOGGER.debug("Path not found", e);
-    }
+    Preconditions.checkArgument(!jsonPath.contains("*"), "Cannot accept paths with wildcards because they may return more than one item.");
   }
 
   /**
@@ -248,6 +176,90 @@ public static boolean isPathPresent(final JsonNode json, final String jsonPath)
     return !foundPaths.isEmpty();
   }
 
+  /**
+   * Traverses into a json object and replaces all values that match the input path with the provided
+   * string. Throws if no existing fields match the path.
+   *
+   * @param json - json object
+   * @param jsonPath - path into the json object. must be in the format of JSONPath.
+   * @param replacement - a string value to replace the current value at the jsonPath
+   * @throws PathNotFoundException throws if the path is not present in the object
+   */
+  public static JsonNode replaceAtStringLoud(final JsonNode json, final String jsonPath, final String replacement) {
+    return replaceAtJsonNodeLoud(json, jsonPath, Jsons.jsonNode(replacement));
+    // assertIsJsonPath(jsonPath);
+    // return JsonPath.parse(Jsons.clone(json)).set(jsonPath, replacement).json();
+  }
+
+  /**
+   * Traverses into a json object and replaces all values that match the input path with the provided
+   * string . Does nothing if no existing fields match the path.
+   *
+   * @param json - json object
+   * @param jsonPath - path into the json object. must be in the format of JSONPath.
+   * @param replacement - a string value to replace the current value at the jsonPath
+   */
+  public static JsonNode replaceAtString(final JsonNode json, final String jsonPath, final String replacement) {
+    return replaceAtJsonNode(json, jsonPath, Jsons.jsonNode(replacement));
+  }
+
+  /**
+   * Traverses into a json object and replaces all values that match the input path with the provided
+   * json object. Does nothing if no existing fields match the path.
+   *
+   * @param json - json object
+   * @param jsonPath - path into the json object. must be in the format of JSONPath.
+   * @param replacement - a json node to replace the current value at the jsonPath
+   */
+  public static JsonNode replaceAtJsonNodeLoud(final JsonNode json, final String jsonPath, final JsonNode replacement) {
+    assertIsJsonPath(jsonPath);
+    return JsonPath.parse(Jsons.clone(json)).set(jsonPath, replacement).json();
+  }
+
+  /**
+   * Traverses into a json object and replaces all values that match the input path with the provided
+   * json object. Does nothing if no existing fields match the path.
+   *
+   * @param json - json object
+   * @param jsonPath - path into the json object. must be in the format of JSONPath.
+   * @param replacement - a json node to replace the current value at the jsonPath
+   */
+  public static JsonNode replaceAtJsonNode(final JsonNode json, final String jsonPath, final JsonNode replacement) {
+    try {
+      return replaceAtJsonNodeLoud(json, jsonPath, replacement);
+    } catch (final PathNotFoundException e) {
+      LOGGER.debug("Path not found", e);
+      return Jsons.clone(json); // defensive copy in failure case.
+    }
+  }
+
+  /**
+   * Traverses into a json object and replaces all values that match the input path with the output of
+   * the provided function. Does nothing if no existing fields match the path.
+   *
+   * @param json - json object
+   * @param jsonPath - path into the json object. must be in the format of JSONPath.
+   * @param replacementFunction - a function that takes in a node that matches the path as well as the
+   *        path to the node itself. the return of this function will replace the current node.
+   */
+  public static JsonNode replaceAt(final JsonNode json, final String jsonPath, final BiFunction<JsonNode, String, JsonNode> replacementFunction) {
+    JsonNode clone = Jsons.clone(json);
+    assertIsJsonPath(jsonPath);
+    try {
+      final List<String> foundPaths = getPaths(clone, jsonPath);
+      for (final String foundPath : foundPaths) {
+        final Optional<JsonNode> singleValue = getSingleValue(clone, foundPath);
+        if (singleValue.isPresent()) {
+          final JsonNode replacement = replacementFunction.apply(singleValue.get(), foundPath);
+          clone = replaceAtJsonNode(clone, foundPath, replacement);
+        }
+      }
+    } catch (final PathNotFoundException e) {
+      LOGGER.debug("Path not found", e);
+    }
+    return clone;
+  }
+
   /**
    *
    * @param conf - JsonPath configuration. Primarily used to reuse code to allow fetching values or
diff --git a/airbyte-commons/src/test/java/io/airbyte/commons/json/JsonPathsTest.java b/airbyte-commons/src/test/java/io/airbyte/commons/json/JsonPathsTest.java
new file mode 100644
index 0000000000000..d0a8b3fd7ccef
--- /dev/null
+++ b/airbyte-commons/src/test/java/io/airbyte/commons/json/JsonPathsTest.java
@@ -0,0 +1,228 @@
+/*
+ * Copyright (c) 2021 Airbyte, Inc., all rights reserved.
+ */
+
+package io.airbyte.commons.json;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.node.ArrayNode;
+import com.jayway.jsonpath.PathNotFoundException;
+import java.util.Collections;
+import java.util.List;
+import java.util.stream.Collectors;
+import org.junit.jupiter.api.Test;
+
+class JsonPathsTest {
+
+  private static final String JSON = """
+                                     {
+                                       "one": [0,1,2],
+                                       "two": { "nested": 10}
+                                     }""";
+  private static final JsonNode JSON_NODE = Jsons.deserialize(JSON);
+  private static final String LIST_ALL_QUERY = "$.one[*]";
+  private static final String LIST_ONE_QUERY = "$.one[1]";
+  private static final String NESTED_FIELD_QUERY = "$.two.nested";
+  private static final String JSON_OBJECT_QUERY = "$.two";
+  private static final String EMPTY_RETURN_QUERY = "$.three";
+  private static final String REPLACEMENT_STRING = "replaced";
+  private static final JsonNode REPLACEMENT_JSON = Jsons.deserialize("{ \"replacement\": \"replaced\" }");
+
+  @Test
+  void testGetValues() {
+    assertEquals(List.of(0, 1, 2), JsonPaths.getValues(JSON_NODE, LIST_ALL_QUERY).stream().map(JsonNode::asInt).collect(Collectors.toList()));
+    assertEquals(List.of(1), JsonPaths.getValues(JSON_NODE, LIST_ONE_QUERY).stream().map(JsonNode::asInt).collect(Collectors.toList()));
+    assertEquals(List.of(10), JsonPaths.getValues(JSON_NODE, NESTED_FIELD_QUERY).stream().map(JsonNode::asInt).collect(Collectors.toList()));
+    assertEquals(JSON_NODE.get("two"), JsonPaths.getValues(JSON_NODE, JSON_OBJECT_QUERY).stream().findFirst().orElse(null));
+    assertEquals(Collections.emptyList(), JsonPaths.getValues(JSON_NODE, EMPTY_RETURN_QUERY));
+  }
+
+  @Test
+  void testGetSingleValue() {
+    assertThrows(IllegalArgumentException.class, () -> JsonPaths.getSingleValue(JSON_NODE, LIST_ALL_QUERY));
+    assertEquals(1, JsonPaths.getSingleValue(JSON_NODE, LIST_ONE_QUERY).map(JsonNode::asInt).orElse(null));
+    assertEquals(10, JsonPaths.getSingleValue(JSON_NODE, NESTED_FIELD_QUERY).map(JsonNode::asInt).orElse(null));
+    assertEquals(JSON_NODE.get("two"), JsonPaths.getSingleValue(JSON_NODE, JSON_OBJECT_QUERY).orElse(null));
+    assertNull(JsonPaths.getSingleValue(JSON_NODE, EMPTY_RETURN_QUERY).orElse(null));
+  }
+
+  @Test
+  void testGetPaths() {
+    assertEquals(List.of("$['one'][0]", "$['one'][1]", "$['one'][2]"), JsonPaths.getPaths(JSON_NODE, LIST_ALL_QUERY));
+    assertEquals(List.of("$['one'][1]"), JsonPaths.getPaths(JSON_NODE, LIST_ONE_QUERY));
+    assertEquals(List.of("$['two']['nested']"), JsonPaths.getPaths(JSON_NODE, NESTED_FIELD_QUERY));
+    assertEquals(List.of("$['two']"), JsonPaths.getPaths(JSON_NODE, JSON_OBJECT_QUERY));
+    assertEquals(Collections.emptyList(), JsonPaths.getPaths(JSON_NODE, EMPTY_RETURN_QUERY));
+  }
+
+  @Test
+  void testIsPathPresent() {
+    assertThrows(IllegalArgumentException.class, () -> JsonPaths.isPathPresent(JSON_NODE, LIST_ALL_QUERY));
+    assertTrue(JsonPaths.isPathPresent(JSON_NODE, LIST_ONE_QUERY));
+    assertTrue(JsonPaths.isPathPresent(JSON_NODE, NESTED_FIELD_QUERY));
+    assertTrue(JsonPaths.isPathPresent(JSON_NODE, JSON_OBJECT_QUERY));
+    assertFalse(JsonPaths.isPathPresent(JSON_NODE, EMPTY_RETURN_QUERY));
+  }
+
+  @Test
+  void testReplaceAtStringLoud() {
+    assertOriginalObjectNotModified(JSON_NODE, () -> {
+      final JsonNode expected = Jsons.clone(JSON_NODE);
+      ((ArrayNode) expected.get("one")).set(1, REPLACEMENT_STRING);
+
+      final JsonNode actual = JsonPaths.replaceAtStringLoud(JSON_NODE, LIST_ONE_QUERY, REPLACEMENT_STRING);
+      assertEquals(expected, actual);
+    });
+  }
+
+  @SuppressWarnings("CodeBlock2Expr")
+  @Test
+  void testReplaceAtStringLoudEmptyPathThrows() {
+    assertOriginalObjectNotModified(JSON_NODE, () -> {
+      assertThrows(PathNotFoundException.class, () -> JsonPaths.replaceAtStringLoud(JSON_NODE, EMPTY_RETURN_QUERY, REPLACEMENT_STRING));
+    });
+  }
+
+  @Test
+  void testReplaceAtString() {
+    assertOriginalObjectNotModified(JSON_NODE, () -> {
+      final JsonNode expected = Jsons.clone(JSON_NODE);
+      ((ArrayNode) expected.get("one")).set(1, REPLACEMENT_STRING);
+
+      final JsonNode actual = JsonPaths.replaceAtString(JSON_NODE, LIST_ONE_QUERY, REPLACEMENT_STRING);
+      assertEquals(expected, actual);
+    });
+  }
+
+  @Test
+  void testReplaceAtStringEmptyReturnNoOp() {
+    assertOriginalObjectNotModified(JSON_NODE, () -> {
+      final JsonNode expected = Jsons.clone(JSON_NODE);
+
+      final JsonNode actual = JsonPaths.replaceAtString(JSON_NODE, EMPTY_RETURN_QUERY, REPLACEMENT_STRING);
+      assertEquals(expected, actual);
+    });
+  }
+
+  @Test
+  void testReplaceAtJsonNodeLoud() {
+    assertOriginalObjectNotModified(JSON_NODE, () -> {
+      final JsonNode expected = Jsons.clone(JSON_NODE);
+      ((ArrayNode) expected.get("one")).set(1, REPLACEMENT_JSON);
+
+      final JsonNode actual = JsonPaths.replaceAtJsonNodeLoud(JSON_NODE, LIST_ONE_QUERY, REPLACEMENT_JSON);
+      assertEquals(expected, actual);
+    });
+  }
+
+  @SuppressWarnings("CodeBlock2Expr")
+  @Test
+  void testReplaceAtJsonNodeLoudEmptyPathThrows() {
+    assertOriginalObjectNotModified(JSON_NODE, () -> {
+      assertThrows(PathNotFoundException.class, () -> JsonPaths.replaceAtJsonNodeLoud(JSON_NODE, EMPTY_RETURN_QUERY, REPLACEMENT_JSON));
+    });
+  }
+
+  @Test
+  void testReplaceAtJsonNodeLoudMultipleReplace() {
+    assertOriginalObjectNotModified(JSON_NODE, () -> {
+      final JsonNode expected = Jsons.clone(JSON_NODE);
+      ((ArrayNode) expected.get("one")).set(0, REPLACEMENT_JSON);
+      ((ArrayNode) expected.get("one")).set(1, REPLACEMENT_JSON);
+      ((ArrayNode) expected.get("one")).set(2, REPLACEMENT_JSON);
+
+      final JsonNode actual = JsonPaths.replaceAtJsonNodeLoud(JSON_NODE, LIST_ALL_QUERY, REPLACEMENT_JSON);
+      assertEquals(expected, actual);
+    });
+  }
+
+  // todo (cgardens) - this behavior is a little unintuitive, but based on the docs, there's not an
+  // obvious workaround. in this case, i would expect this to silently do nothing instead of throwing.
+  // for now just documenting it with a test. to avoid this, use the non-loud version of this method.
+  @SuppressWarnings("CodeBlock2Expr")
+  @Test
+  void testReplaceAtJsonNodeLoudMultipleReplaceSplatInEmptyArrayThrows() {
+    final JsonNode expected = Jsons.clone(JSON_NODE);
+    ((ArrayNode) expected.get("one")).removeAll();
+
+    assertOriginalObjectNotModified(expected, () -> {
+      assertThrows(PathNotFoundException.class, () -> JsonPaths.replaceAtJsonNodeLoud(expected, "$.one[*]", REPLACEMENT_JSON));
+    });
+  }
+
+  @Test
+  void testReplaceAtJsonNode() {
+    assertOriginalObjectNotModified(JSON_NODE, () -> {
+      final JsonNode expected = Jsons.clone(JSON_NODE);
+      ((ArrayNode) expected.get("one")).set(1, REPLACEMENT_JSON);
+
+      final JsonNode actual = JsonPaths.replaceAtJsonNode(JSON_NODE, LIST_ONE_QUERY, REPLACEMENT_JSON);
+      assertEquals(expected, actual);
+    });
+  }
+
+  @Test
+  void testReplaceAtJsonNodeEmptyReturnNoOp() {
+    assertOriginalObjectNotModified(JSON_NODE, () -> {
+      final JsonNode expected = Jsons.clone(JSON_NODE);
+
+      final JsonNode actual = JsonPaths.replaceAtJsonNode(JSON_NODE, EMPTY_RETURN_QUERY, REPLACEMENT_JSON);
+      assertEquals(expected, actual);
+    });
+  }
+
+  @Test
+  void testReplaceAt() {
+    assertOriginalObjectNotModified(JSON_NODE, () -> {
+      final JsonNode expected = Jsons.clone(JSON_NODE);
+      ((ArrayNode) expected.get("one")).set(1, "1-$['one'][1]");
+
+      final JsonNode actual = JsonPaths.replaceAt(JSON_NODE, LIST_ONE_QUERY, (node, path) -> Jsons.jsonNode(node + "-" + path));
+      assertEquals(expected, actual);
+    });
+  }
+
+  @Test
+  void testReplaceAtMultiple() {
+    assertOriginalObjectNotModified(JSON_NODE, () -> {
+      final JsonNode expected = Jsons.clone(JSON_NODE);
+      ((ArrayNode) expected.get("one")).set(0, "0-$['one'][0]");
+      ((ArrayNode) expected.get("one")).set(1, "1-$['one'][1]");
+      ((ArrayNode) expected.get("one")).set(2, "2-$['one'][2]");
+
+      final JsonNode actual = JsonPaths.replaceAt(JSON_NODE, LIST_ALL_QUERY, (node, path) -> Jsons.jsonNode(node + "-" + path));
+      assertEquals(expected, actual);
+    });
+  }
+
+  @Test
+  void testReplaceAtEmptyReturnNoOp() {
+    assertOriginalObjectNotModified(JSON_NODE, () -> {
+      final JsonNode expected = Jsons.clone(JSON_NODE);
+
+      final JsonNode actual = JsonPaths.replaceAt(JSON_NODE, EMPTY_RETURN_QUERY, (node, path) -> Jsons.jsonNode(node + "-" + path));
+      assertEquals(expected, actual);
+    });
+  }
+
+  /**
+   * For all replacement functions, they should NOT mutate in place. Helper assertion to verify that
+   * invariant.
+   *
+   * @param json - json object used for testing
+   * @param runnable - the rest of the test code that does the replacement
+   */
+  private static void assertOriginalObjectNotModified(final JsonNode json, final Runnable runnable) {
+    final JsonNode originalJsonNode = Jsons.clone(json);
+    runnable.run();
+    // verify the original object was not mutated.
+    assertEquals(originalJsonNode, json);
+  }
+
+}

From e5ce9ae9d333a3f71a10f14a2b9f540f0f4d64cf Mon Sep 17 00:00:00 2001
From: cgardens <charles@airbyte.io>
Date: Sat, 2 Apr 2022 11:56:59 -0700
Subject: [PATCH 3/5] copy clean up

---
 .../src/main/java/io/airbyte/commons/json/JsonPaths.java   | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java b/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java
index 3f50a704bb5e6..fe203617c5c76 100644
--- a/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java
+++ b/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java
@@ -26,7 +26,6 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-// todo (cgardens) - needs a test.
 /**
  * JSONPath is specification for querying JSON objects. More information about the specification can
  * be found here: https://goessner.net/articles/JsonPath/. For those familiar with jq, JSONPath will
@@ -41,8 +40,8 @@
  * "alpha": [1, 2, 3] }, this JSONPath "$.alpha[*]", would return: [1, 2, 3], but this one
  * "$.alpha[0]" would return: [1]. The Java interface we place over this query system defaults to
  * returning a list for query results. In addition, we provide helper functions that will just
- * return a single value (see: {@link JsonPaths#getSingleValue(JsonNode, String)}. These should only
- * be used if it is not possible for a query to return more than one value.
+ * return a single value (see: {@link JsonPaths#getSingleValue(JsonNode, String)}). These should
+ * only be used if it is not possible for a query to return more than one value.
  */
 public class JsonPaths {
 
@@ -187,8 +186,6 @@ public static boolean isPathPresent(final JsonNode json, final String jsonPath)
    */
   public static JsonNode replaceAtStringLoud(final JsonNode json, final String jsonPath, final String replacement) {
     return replaceAtJsonNodeLoud(json, jsonPath, Jsons.jsonNode(replacement));
-    // assertIsJsonPath(jsonPath);
-    // return JsonPath.parse(Jsons.clone(json)).set(jsonPath, replacement).json();
   }
 
   /**

From e40372b285ce02da06136cd17b6d76f8d35afa83 Mon Sep 17 00:00:00 2001
From: Charles <charles@airbyte.io>
Date: Fri, 8 Apr 2022 09:49:50 -0700
Subject: [PATCH 4/5] Update
 airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java

Co-authored-by: Topher Lubaway <asimplechris@gmail.com>
---
 .../src/main/java/io/airbyte/commons/json/JsonPaths.java        | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java b/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java
index fe203617c5c76..3731683bbae8a 100644
--- a/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java
+++ b/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java
@@ -136,7 +136,7 @@ public static List<String> getPaths(final JsonNode json, final String jsonPath)
   }
 
   /**
-   * Given a JSONPath, returns 1 or 0 values that match the path. Throws is more than 1 value is
+   * Given a JSONPath, returns 1 or 0 values that match the path. Throws if more than 1 value is
    * found.
    *
    * THIS SHOULD ONLY BE USED IF THE JSONPATH CAN ONLY EVER RETURN 0 OR 1 VALUES. e.g. don't do

From 5703131e93a9e8db630a87c119a0c6fca5562ae4 Mon Sep 17 00:00:00 2001
From: cgardens <charles@airbyte.io>
Date: Fri, 8 Apr 2022 10:49:21 -0700
Subject: [PATCH 5/5] code review feedback

---
 airbyte-commons/build.gradle                  |  3 ++
 .../io/airbyte/commons/json/JsonPaths.java    | 30 +++++++++++--------
 build.gradle                                  |  1 -
 3 files changed, 21 insertions(+), 13 deletions(-)

diff --git a/airbyte-commons/build.gradle b/airbyte-commons/build.gradle
index 2e9147968aa9b..d69e3c405cd4c 100644
--- a/airbyte-commons/build.gradle
+++ b/airbyte-commons/build.gradle
@@ -4,4 +4,7 @@ plugins {
 
 dependencies {
     // Dependencies for this module should be specified in the top-level build.gradle. See readme for more explanation.
+
+    // this dependency is an exception to the above rule because it is only used INTERNALLY to the commons library.
+    implementation 'com.jayway.jsonpath:json-path:2.7.0'
 }
diff --git a/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java b/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java
index 3731683bbae8a..428299aa958b4 100644
--- a/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java
+++ b/airbyte-commons/src/main/java/io/airbyte/commons/json/JsonPaths.java
@@ -42,8 +42,12 @@
  * returning a list for query results. In addition, we provide helper functions that will just
  * return a single value (see: {@link JsonPaths#getSingleValue(JsonNode, String)}). These should
  * only be used if it is not possible for a query to return more than one value.
+ *
+ * Note: Package private as most uses of JsonPaths seems like they can be hidden inside other
+ * commons libraries (i.e. Jsons and JsonsSchemas). If this assumption proves incorrect, we can open
+ * it up.
  */
-public class JsonPaths {
+class JsonPaths {
 
   private static final Logger LOGGER = LoggerFactory.getLogger(JsonPaths.class);
 
@@ -126,7 +130,13 @@ public static List<JsonNode> getValues(final JsonNode json, final String jsonPat
    *
    * @param json - json object
    * @param jsonPath - path into the json object. must be in the format of JSONPath.
-   * @return all paths that are present that match the input query
+   * @return all paths that are present that match the input query. returns a list (instead of a set),
+   *         because having a deterministic ordering is valuable for all downstream consumers (i.e. in
+   *         most cases if we returned a set, the downstream would then put it in a set and sort it so
+   *         that if they are doing replacements using the paths, the behavior is predictable e.g. if
+   *         you do replace $.alpha and $.alpha[*], the order you do those replacements in matters).
+   *         specifically that said, we do expect that there will be no duplicates in the returned
+   *         list.
    */
   public static List<String> getPaths(final JsonNode json, final String jsonPath) {
     return getInternal(GET_PATHS_CONFIGURATION, json, jsonPath)
@@ -242,17 +252,13 @@ public static JsonNode replaceAtJsonNode(final JsonNode json, final String jsonP
   public static JsonNode replaceAt(final JsonNode json, final String jsonPath, final BiFunction<JsonNode, String, JsonNode> replacementFunction) {
     JsonNode clone = Jsons.clone(json);
     assertIsJsonPath(jsonPath);
-    try {
-      final List<String> foundPaths = getPaths(clone, jsonPath);
-      for (final String foundPath : foundPaths) {
-        final Optional<JsonNode> singleValue = getSingleValue(clone, foundPath);
-        if (singleValue.isPresent()) {
-          final JsonNode replacement = replacementFunction.apply(singleValue.get(), foundPath);
-          clone = replaceAtJsonNode(clone, foundPath, replacement);
-        }
+    final List<String> foundPaths = getPaths(clone, jsonPath);
+    for (final String foundPath : foundPaths) {
+      final Optional<JsonNode> singleValue = getSingleValue(clone, foundPath);
+      if (singleValue.isPresent()) {
+        final JsonNode replacement = replacementFunction.apply(singleValue.get(), foundPath);
+        clone = replaceAtJsonNode(clone, foundPath, replacement);
       }
-    } catch (final PathNotFoundException e) {
-      LOGGER.debug("Path not found", e);
     }
     return clone;
   }
diff --git a/build.gradle b/build.gradle
index 5a57032271a03..a2a1fee6c0ae1 100644
--- a/build.gradle
+++ b/build.gradle
@@ -272,7 +272,6 @@ subprojects {
         implementation 'com.fasterxml.jackson.core:jackson-annotations'
         implementation 'com.fasterxml.jackson.dataformat:jackson-dataformat-yaml'
         implementation 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310'
-        implementation 'com.jayway.jsonpath:json-path:2.7.0'
 
         implementation 'com.google.guava:guava:30.1.1-jre'