JSONPath

public struct JSONPath<Root> where Root : PathRoot
extension JSONPath: Equatable

A structure representing the location of an item in a JSON object or JSON array, potentially nested in other JSON objects and JSON arrays.

To create a basic JSONPath you can call the JSONPath subscript with a String or an Int depending on where you want to start the path from: the first one would start from a JSON object, the second would start from a JSON array.

 let objectPath = JSONPath["container"]
 let arrayPath = JSONPath[0]

To create a path like container.array[0].property you can use a subscript for each path component:

 JSONPath["container"]["array"][0]["property"]

  • Creates a new JSONPath starting from self and adding a new component that looks up for an item in an object at the given key.

    As an example, given the following JSON:

     {
   "root": {
      "property": "item"
   }
 }

    JSONPath["root"]["property"] will point to the value "item".

    Declaration

    Swift

    public subscript(key: String) -> `Self` { get }

    Parameters

    key

    The key to look for an item in an object, after reaching the current path component.

    Return Value

    A new JSONPath, that has the key lookup appended at the end of the current path.

  • Creates a new JSONPath starting from self and adding a new component that looks up for an item in an array at the given index.

    As an example, given the following JSON:

     {
   "root": [
      "item"
   ]
 }

    JSONPath["root"][0] will point to the value "item".

    Declaration

    Swift

    public subscript(index: Int) -> `Self` { get }

    Parameters

    index

    The index to look for an item in an array, after reaching the current path component.

    Return Value

    A new JSONPath, that has the index lookup appended at the end of the current path.

  • Renders the path as a String

    Declaration

    Swift

    public func render() -> String

  • Declaration

    Swift

    public static func == (lhs: JSONPath, rhs: JSONPath) -> Bool

Available where Root == ObjectRoot

  • The root key component of this JSONObjectPath.

    This property returns the first key component of the path, which represents the top-level property name in a JSON object.

    For example, given a path like JSONPath["container"]["property"], the root would return "container".

    Declaration

    Swift

    var root: String { get }

    Return Value

    The root key as a String.

  • Creates a JSONObjectPath with the root component.

    Warning

    This will not parse the given key, but rather use it in its entirety as a root key. Use JSONObjectPath.parse to parse a complete path like container.property.

    Declaration

    Swift

    static subscript(key: String) -> `Self` { get }

    Parameters

    key

    The root component of this JSONObjectPath.

  • Parses a string into a JSONObjectPath.

    The string to pass needs to conform to a specific format.

    • It can be a dot (.) separated list of alphanumeric characters and/or underscores.
      • Each component of a list built this way represents one level of a JSON object.
      • The last one can represent any type of JSON value.
    • Square brackets ([]) could be used instead of the dot notation, to separate one (or each) of the components. Inside these brackets you can put:
      • An integer, to represent an element into a JSON array.
      • A single (') or double (") quoted string to represent an element into a JSON object.
      • Inside of the quoted string any character is valid, but the character used to quote the string (' or ") needs to be escaped with a backslash (\), and same for backslashes, which need to be escaped with an additional backslash.
    • It needs to start with a key component.

    Examples of valid strings:

    • property
    • container.property
    • container["property"]
    • container['property']
    • container["john's party"]
    • container['john\'s party']
    • container["\"nested quote\""]
    • container["escaped\\backslash"]
    • array[123]
      • which is different from array["123"], although both are valid. Difference is that the quoted version treats the array property as an object and looks for a nested “123” by string instead of the item at index 123 in an array.
    • array[123].property
    • some_property
    • container.some_property
    • container["some.property"]
      • which is different from container.some.property, although both are valid
    • container["some@property"]
      • which would be wrong without the quoted brackets: container.some@property)
    • ["array"][123]["property"]

    Examples of invalid strings:

    • "property": invalid character (")
    • container-property: invalid character (-)
    • container[property]: missing quotes (") in brackets
    • container.["property"]: invalid character (.) before the brackets
    • container["property']: closing quote (') different from opening one (") in brackets
    • container['john's party']: unescaped quote (')
    • container[""nested quote""]: unescaped quotes (")
    • container["unescaped\backslash"]: unescaped backslash (\)
    • array[12 3]: invalid number with whitespace ( ) inside index brackets
    • container@property: invalid character (@)

    • [123].property: index is not valid as a first component. Must start with a key.

    Throws

    A JSONPathParseError if the parsing failed.

    Declaration

    Swift

    static func parse(_ pathString: String) throws(JSONPathParseError) -> JSONPath<Root>

    Parameters

    pathString

    The String that will be parsed.

    Return Value

    A JSONObjectPath, if the parsing succeeded.

Available where Root == ArrayRoot

  • Creates a JSONArrayPath with the root component.

    Declaration

    Swift

    static subscript(index: Int) -> `Self` { get }

    Parameters

    index

    The root component of this JSONArrayPath.

  • Parses a string into a JSONArrayPath.

    The string to pass needs to conform to a specific format.

    • It can be a dot (.) separated list of alphanumeric characters and/or underscores.
      • Each component of a list built this way represents one level of a JSON object.
      • The last one can represent any type of JSON value.
    • Square brackets ([]) could be used instead of the dot notation, to separate one (or each) of the components. Inside these brackets you can put:
      • An integer, to represent an element into a JSON array.
      • A single (') or double (") quoted string to represent an element into a JSON object.
      • Inside of the quoted string any character is valid, but the character used to quote the string (' or ") needs to be escaped with a backslash (\), and same for backslashes, which need to be escaped with an additional backslash.
    • It needs to start with an index component.

    Examples of valid strings:

    • [123]
    • [0].property
    • [0]["property"]
    • [0]['property']
    • [0]["john's party"]
    • [0]['john\'s party']
    • [0]["\"nested quote\""]
    • [0]["escaped\\backslash"]
    • [0][123]
      • which is different from [0]["123"], although both are valid. Difference is that the quoted version treats the [0] item as an object and looks for a nested “123” by string instead of the item at index 123 in an array.
    • [0].array[123].property
    • [0].some_property
    • [0].container.some_property
    • [0].container["some.property"]
      • which is different from [0].container.some.property, although both are valid
    • [0].container["some@property"]
      • which would be wrong without the quoted brackets: container.some@property)
    • [0]["array"][123]["property"]

    Examples of invalid strings:

    • [0]."property": invalid character (")
    • [0].container-property: invalid character (-)
    • [0].container[property]: missing quotes (") in brackets
    • [0].container.["property"]: invalid character (.) before the brackets
    • [0].container["property']: closing quote (') different from opening quote (") in brackets
    • [0]['john's party']: unescaped quote (')
    • [0][""nested quote""]: unescaped quotes (")
    • [0]["unescaped\backslash"]: unescaped backslash (\)
    • [12 3]: invalid number with whitespace ( ) inside index brackets
    • [0].container@property: invalid character (@)

    • property: key is not a valid first component. Must start with an index.

    Throws

    A JSONPathParseError if the parsing failed.

    Declaration

    Swift

    static func parse(_ pathString: String) throws(JSONPathParseError) -> JSONPath<Root>

    Parameters

    pathString

    The String that will be parsed.

    Return Value

    A JSONArrayPath, if the parsing succeeded.