Class JsonPath

java.lang.Object
com.jayway.jsonpath.JsonPath

public class JsonPath extends Object

JsonPath is to JSON what XPATH is to XML, a simple way to extract parts of a given document. JsonPath is available in many programming languages such as Javascript, Python and PHP.

JsonPath allows you to compile a json path string to use it many times or to compile and apply in one single on demand operation.

Given the Json document:

 String json =
 "{
 "store":
 {
 "book":
 [
 {
 "category": "reference",
 "author": "Nigel Rees",
 "title": "Sayings of the Century",
 "price": 8.95
 },
 {
 "category": "fiction",
 "author": "Evelyn Waugh",
 "title": "Sword of Honour",
 "price": 12.99
 }
 ],
 "bicycle":
 {
 "color": "red",
 "price": 19.95
 }
 }
 }";
 

A JsonPath can be compiled and used as shown:

JsonPath path = JsonPath.compile("$.store.book[1]");
List<Object> books = path.read(json);

Or:

List<Object> authors = JsonPath.read(json, "$.store.book[*].author")

If the json path returns a single value (is definite):

String author = JsonPath.read(json, "$.store.book[1].author")
  • Field Details

    • path

      private final Path path
  • Constructor Details

  • Method Details

    • getPath

      public String getPath()
      Returns the string representation of this JsonPath
      Returns:
      path as String
    • isPathDefinite

      public static boolean isPathDefinite(String path)
      See Also:
    • isDefinite

      public boolean isDefinite()
      Checks if a path points to a single item or if it potentially returns multiple items

      a path is considered not definite if it contains a scan fragment ".." or an array position fragment that is not based on a single index

      definite path examples are:

      $store.book $store.book[1].title

      not definite path examples are:

      $..book $.store.book[*] $.store.book[1,2] $.store.book[?(@.category = 'fiction')]

      Returns:
      true if path is definite (points to single item)
    • read

      public <T> T read(Object jsonObject)
      Applies this JsonPath to the provided json document. Note that the document must be identified as either a List or Map by the JsonProvider
      Type Parameters:
      T - expected return type
      Parameters:
      jsonObject - a container Object
      Returns:
      object(s) matched by the given path
    • read

      public <T> T read(Object jsonObject, Configuration configuration)
      Applies this JsonPath to the provided json document. Note that the document must be identified as either a List or Map by the JsonProvider
      Type Parameters:
      T - expected return type
      Parameters:
      jsonObject - a container Object
      configuration - configuration to use
      Returns:
      object(s) matched by the given path
    • set

      public <T> T set(Object jsonObject, Object newVal, Configuration configuration)
      Set the value this path points to in the provided jsonObject
      Type Parameters:
      T - expected return type
      Parameters:
      jsonObject - a json object
      configuration - configuration to use
      Returns:
      the updated jsonObject or the path list to updated objects if option AS_PATH_LIST is set.
    • map

      public <T> T map(Object jsonObject, MapFunction mapFunction, Configuration configuration)
      Replaces the value on the given path with the result of the MapFunction.
      Parameters:
      jsonObject - a json object
      mapFunction - Converter object to be invoked
      configuration - configuration to use
      Returns:
      the updated jsonObject or the path list to updated objects if option AS_PATH_LIST is set.
    • delete

      public <T> T delete(Object jsonObject, Configuration configuration)
      Deletes the object this path points to in the provided jsonObject
      Type Parameters:
      T - expected return type
      Parameters:
      jsonObject - a json object
      configuration - configuration to use
      Returns:
      the updated jsonObject or the path list to deleted objects if option AS_PATH_LIST is set.
    • add

      public <T> T add(Object jsonObject, Object value, Configuration configuration)
      Adds a new value to the Array this path points to in the provided jsonObject
      Type Parameters:
      T - expected return type
      Parameters:
      jsonObject - a json object
      value - the value to add
      configuration - configuration to use
      Returns:
      the updated jsonObject or the path list to updated object if option AS_PATH_LIST is set.
    • put

      public <T> T put(Object jsonObject, String key, Object value, Configuration configuration)
      Adds or updates the Object this path points to in the provided jsonObject with a key with a value
      Type Parameters:
      T - expected return type
      Parameters:
      jsonObject - a json object
      value - the key to add or update
      configuration - configuration to use
      value - the new value
      Returns:
      the updated jsonObject or the path list to updated objects if option AS_PATH_LIST is set.
    • renameKey

      public <T> T renameKey(Object jsonObject, String oldKeyName, String newKeyName, Configuration configuration)
    • read

      public <T> T read(String json)
      Applies this JsonPath to the provided json string
      Type Parameters:
      T - expected return type
      Parameters:
      json - a json string
      Returns:
      list of objects matched by the given path
    • read

      public <T> T read(String json, Configuration configuration)
      Applies this JsonPath to the provided json string
      Type Parameters:
      T - expected return type
      Parameters:
      json - a json string
      configuration - configuration to use
      Returns:
      list of objects matched by the given path
    • read

      public <T> T read(URL jsonURL) throws IOException
      Applies this JsonPath to the provided json URL
      Type Parameters:
      T - expected return type
      Parameters:
      jsonURL - url to read from
      Returns:
      list of objects matched by the given path
      Throws:
      IOException
    • read

      public <T> T read(File jsonFile) throws IOException
      Applies this JsonPath to the provided json file
      Type Parameters:
      T - expected return type
      Parameters:
      jsonFile - file to read from
      Returns:
      list of objects matched by the given path
      Throws:
      IOException
    • read

      public <T> T read(File jsonFile, Configuration configuration) throws IOException
      Applies this JsonPath to the provided json file
      Type Parameters:
      T - expected return type
      Parameters:
      jsonFile - file to read from
      configuration - configuration to use
      Returns:
      list of objects matched by the given path
      Throws:
      IOException
    • read

      public <T> T read(InputStream jsonInputStream) throws IOException
      Applies this JsonPath to the provided json input stream
      Type Parameters:
      T - expected return type
      Parameters:
      jsonInputStream - input stream to read from
      Returns:
      list of objects matched by the given path
      Throws:
      IOException
    • read

      public <T> T read(InputStream jsonInputStream, Configuration configuration) throws IOException
      Applies this JsonPath to the provided json input stream
      Type Parameters:
      T - expected return type
      Parameters:
      jsonInputStream - input stream to read from
      configuration - configuration to use
      Returns:
      list of objects matched by the given path
      Throws:
      IOException
    • read

      public <T> T read(InputStream jsonInputStream, String charset, Configuration configuration) throws IOException
      Applies this JsonPath to the provided json input stream
      Type Parameters:
      T - expected return type
      Parameters:
      jsonInputStream - input stream to read from
      configuration - configuration to use
      Returns:
      list of objects matched by the given path
      Throws:
      IOException
    • compile

      public static JsonPath compile(String jsonPath, Predicate... filters)
      Compiles a JsonPath
      Parameters:
      jsonPath - to compile
      filters - filters to be applied to the filter place holders [?] in the path
      Returns:
      compiled JsonPath
    • read

      public static <T> T read(Object json, String jsonPath, Predicate... filters)
      Creates a new JsonPath and applies it to the provided Json object
      Type Parameters:
      T - expected return type
      Parameters:
      json - a json object
      jsonPath - the json path
      filters - filters to be applied to the filter place holders [?] in the path
      Returns:
      list of objects matched by the given path
    • read

      public static <T> T read(String json, String jsonPath, Predicate... filters)
      Creates a new JsonPath and applies it to the provided Json string
      Type Parameters:
      T - expected return type
      Parameters:
      json - a json string
      jsonPath - the json path
      filters - filters to be applied to the filter place holders [?] in the path
      Returns:
      list of objects matched by the given path
    • read

      public static <T> T read(URL jsonURL, String jsonPath, Predicate... filters) throws IOException
      Creates a new JsonPath and applies it to the provided Json object
      Type Parameters:
      T - expected return type
      Parameters:
      jsonURL - url pointing to json doc
      jsonPath - the json path
      filters - filters to be applied to the filter place holders [?] in the path
      Returns:
      list of objects matched by the given path
      Throws:
      IOException
    • read

      public static <T> T read(File jsonFile, String jsonPath, Predicate... filters) throws IOException
      Creates a new JsonPath and applies it to the provided Json object
      Type Parameters:
      T - expected return type
      Parameters:
      jsonFile - json file
      jsonPath - the json path
      filters - filters to be applied to the filter place holders [?] in the path
      Returns:
      list of objects matched by the given path
      Throws:
      IOException
    • read

      public static <T> T read(InputStream jsonInputStream, String jsonPath, Predicate... filters) throws IOException
      Creates a new JsonPath and applies it to the provided Json object
      Type Parameters:
      T - expected return type
      Parameters:
      jsonInputStream - json input stream
      jsonPath - the json path
      filters - filters to be applied to the filter place holders [?] in the path
      Returns:
      list of objects matched by the given path
      Throws:
      IOException
    • using

      public static ParseContext using(Configuration configuration)
      Creates a ParseContext that can be used to parse a given JSON input.
      Parameters:
      configuration - configuration to use when parsing JSON
      Returns:
      a parsing context based on given configuration
    • using

      @Deprecated public static ParseContext using(JsonProvider provider)
      Deprecated.
      Creates a ParseContext that will parse a given JSON input.
      Parameters:
      provider - jsonProvider to use when parsing JSON
      Returns:
      a parsing context based on given jsonProvider
    • parse

      public static DocumentContext parse(Object json)
      Parses the given JSON input using the default Configuration and returns a DocumentContext for path evaluation
      Parameters:
      json - input
      Returns:
      a read context
    • parse

      public static DocumentContext parse(String json)
      Parses the given JSON input using the default Configuration and returns a DocumentContext for path evaluation
      Parameters:
      json - string
      Returns:
      a read context
    • parse

      public static DocumentContext parse(InputStream json)
      Parses the given JSON input using the default Configuration and returns a DocumentContext for path evaluation
      Parameters:
      json - stream
      Returns:
      a read context
    • parse

      public static DocumentContext parse(File json) throws IOException
      Parses the given JSON input using the default Configuration and returns a DocumentContext for path evaluation
      Parameters:
      json - file
      Returns:
      a read context
      Throws:
      IOException
    • parse

      public static DocumentContext parse(URL json) throws IOException
      Parses the given JSON input using the default Configuration and returns a DocumentContext for path evaluation
      Parameters:
      json - url
      Returns:
      a read context
      Throws:
      IOException
    • parse

      public static DocumentContext parse(Object json, Configuration configuration)
      Parses the given JSON input using the provided Configuration and returns a DocumentContext for path evaluation
      Parameters:
      json - input
      Returns:
      a read context
    • parse

      public static DocumentContext parse(String json, Configuration configuration)
      Parses the given JSON input using the provided Configuration and returns a DocumentContext for path evaluation
      Parameters:
      json - input
      Returns:
      a read context
    • parse

      public static DocumentContext parse(InputStream json, Configuration configuration)
      Parses the given JSON input using the provided Configuration and returns a DocumentContext for path evaluation
      Parameters:
      json - input
      Returns:
      a read context
    • parse

      public static DocumentContext parse(File json, Configuration configuration) throws IOException
      Parses the given JSON input using the provided Configuration and returns a DocumentContext for path evaluation
      Parameters:
      json - input
      Returns:
      a read context
      Throws:
      IOException
    • parse

      public static DocumentContext parse(URL json, Configuration configuration) throws IOException
      Parses the given JSON input using the provided Configuration and returns a DocumentContext for path evaluation
      Parameters:
      json - input
      Returns:
      a read context
      Throws:
      IOException
    • resultByConfiguration

      private <T> T resultByConfiguration(Object jsonObject, Configuration configuration, EvaluationContext evaluationContext)