JSON functions

The following table describes the functions that are available for you to use to create or manipulate JSON objects:

Description	JSON function
Create a new JSON object from key-value pairs.	json_object
Create a JSON array using a list of values.	json_array
Return either a JSON array or a Splunk software native type value from a field and zero or more paths.	json_extract
Insert or overwrite values for a JSON node with the values provided and return an updated JSON object.	json_set
Evaluate whether a JSON object uses valid JSON syntax and returns either TRUE or FALSE.	json_valid

json_object(<members>)

Creates a new JSON object from members of key-value pairs.

Usage

If you specify a string for a <key> or <value>, you must enclose the string in double quotation marks. A <key> must be a string. A <value> can be a string, number, Boolean, null, multivalue field, array, or another JSON object.

You can use this function with the eval and where commands, and as part of evaluation expressions with other commands.

To use named arguments, you must specify the pairs of arguments in an array, enclosing the values in square brackets. The syntax for named arguments is json_object(members: [<key>, <value>,...]). For example:

... json_object(members: ["name", "maria", "surname", "dubois"])

Examples

These examples show different ways to use the json_object function to create JSON objects in your events.

1. Create a basic JSON object

The following example creates a basic JSON object { "name": "maria" }.

... | eval name = json_object("name", "maria")

2. Create a JSON object using a multivalue field

The following example creates a multivalue field called firstnames that uses the key name and contains the values "maria" and "arun". The JSON object created is { "name": ["maria", "arun"] } .

... | eval firstnames = json_object("name", mvappend("maria", "arun"))

3. Create a JSON object using a JSON array

The following example creates a JSON object that uses a JSON array for the values.

... | eval locations = json_object("cities", json_array("London", "Sydney", "Berlin", "Santiago"))

The result is the JSON object { "cities": ["London", "Sydney", "Berlin", "Santiago"] }.

4. Create a nested JSON object

The following example creates a nested JSON object that uses other JSON objects and a multivalue or JSON array field called gamelist.

...| eval games = json_object("category", json_object("boardgames", json_object("cooperative", gamelist)))

The result is this JSON object:

{
  "games": {
    "category": {
      "boardgames": {
        "cooperative": [ "Pandemic", "Forbidden Island", "Castle Panic" ]
      }
    }
  }
}

json_array(<values>)

Creates a JSON array using a list of values.

Usage

A <value> can be any kind of value such as string, number, or Boolean. You can also use the json_object function to specify values.

You can use this function with the eval and where commands, and as part of evaluation expressions with other commands.

To use named arguments, you must specify the values in an array, enclosing the values in square brackets. The syntax for named arguments is json_array(values: [<value>, <value>...]). For example:

... json_array(values: ["buttercup", "fluttershy", "rarity"])

Examples

These examples show different ways to use the json_array function to create JSON arrays in your events.

Create a basic JSON array

The following example creates a simple array ["buttercup", "fluttershy", "rarity"] .

... | eval ponies = json_array("buttercup", "fluttershy", "rarity")

Create an JSON array from a string and a JSON object

The following example uses a string dubois and the json_object function for the array values.

... | eval surname = json_array("dubois", json_object("name", "patel"))

The result is the JSON array [ "dubois", {"name": "patel}" ].

json_extract(<json>, <paths>)

This function returns a value from a piece JSON and zero or more paths. The value is returned in either a JSON array, or a Splunk software native type value.

Usage

What is converted or extracted depends on whether you specify piece of JSON, or JSON and one or more paths.

Syntax	Description
json_extract(<json>)	Converts a JSON field to the Splunk software native type. For example: Converts a JSON string to a string Converts a JSON Boolean to a Boolean Converts a JSON null to a null
json_extract(<json>, <path>)	Extracts the value specified by <path> from <json>, and converts the value to the native type. This can be a JSON array if the path leads to an array.
json_extract(<json>, <path>, <path>, ...)	Extracts all of the paths from <json> and returns it as a JSON array.

You can use this function with the eval and where commands, and as part of evaluation expressions with other commands.

To use named arguments, you must specify the paths in an array, enclosing the values in square brackets. The syntax for named arguments is json_extract(json:<json>, paths:[<path>, <path>...]). For example:

... json_extract(json: cities, paths:["cities{}.name", "cities{}.Bridges{}"])

Examples

These examples use this JSON object, which is in a field called cities in an event:

{
  "cities": [
    {
      "name": "London",
      "Bridges": [
        { "name": "Tower Bridge", "length": 801 },
        { "name": "Millennium Bridge", "length": 1066 }
      ]
    },
    {
      "name": "Venice",
      "Bridges": [
        { "name": "Rialto Bridge", "length": 157 },
        { "name": "Bridge of Sighs", "length": 36 },
        { "name": "Ponte della Paglia" }
      ]
    },
    {
      "name": "San Francisco",
      "Bridges": [
        { "name": "Golden Gate Bridge", "length": 8981 },
        { "name": "Bay Bridge", "length": 23556 }
      ]
    }
  ]
}

1. Extract the entire JSON object in a field

The following example returns the entire JSON object from the cities field. The cities field contains only one object. The key is the entire object. This extraction can return any type of value.

... | eval extract_cities = json_extract(cities)

Field	Results
extract_cities	{"cities":[{"name":"London","Bridges":[{"name":"Tower Bridge","length":801},{"name":"Millennium Bridge","length":1066}]},{"name":"Venice","Bridges":[{"name":"Rialto Bridge","length":157},{"name":"Bridge of Sighs","length":36},{"name":"Ponte della Paglia"}]},{"name":"San Francisco","Bridges":[{"name":"Golden Gate Bridge","length":8981},{"name":"Bay Bridge","length":23556}]}]}

2. Extract the first nested JSON object in a field

The following example extracts the information about the city of London from the JSON object. This extraction can return any type of value.

... | eval London=json_extract(cities,"cities{0}")

Field	Results
London	{"name":"London","Bridges":[{"name":"Tower Bridge","length":801},{"name":"Millennium Bridge","length":1066}]}

3. Extract the third nested JSON object in a field

The following example extracts the information about the city of San Francisco from the JSON object. This extraction can return any type of value.

... | eval "San_Francisco"=json_extract(cities,"cities{2}")

Field	Results
San_Francisco	{"name":"San Francisco","Bridges":[{"name":"Golden Gate Bridge","length":8981},{"name":"Bay Bridge","length":23556}]}

4. Extract a specific key from each nested JSON object in a field

The following example extracts the names of the cities from the JSON object. This extraction can return any type of value.

... | eval my_cities=json_extract(cities,"cities{}.name")

Field	Results
my_cities	["London","Venice","San Francisco"]

5. Extract a specific set of key-value pairs from each nested JSON object in a field

The following example extracts the information about each bridge from every city from the JSON object. This extraction can return any type of value.

... | eval Bridges=json_extract(cities,"cities{}.Bridges{}")

Field	Results
Bridges	[{"name":"Tower Bridge","length":801},{"name":"Millennium Bridge","length":1066},{"name":"Rialto Bridge","length":157},{"name":"Bridge of Sighs","length":36},{"name":"Ponte della Paglia"},{"name":"Golden Gate Bridge","length":8981},{"name":"Bay Bridge","length":23556}]

6. Extract a specific value from each nested JSON object in a field

The following example extracts the names of the bridges from all of the cities from the JSON object. This extraction can return any type of value.

... | eval Bridge_names=json_extract(cities,"cities{}.Bridges{}.name")

Field	Results
Bridge_names	["Tower Bridge","Millennium Bridge","Rialto Bridge","Bridge of Sighs","Ponte della Paglia","Golden Gate Bridge","Bay Bridge"]

7. Extract a specific key-value pair from a specific nested JSON object in a field

The following example extracts the name and length of the first bridge from the third city from the JSON object. This extraction can return any type of value.

... | eval GG_Bridge=json_extract(cities,"cities{2}.Bridges{0}")

Field	Results
GG_Bridge	{"name":"Golden Gate Bridge","length":8981}

8. Extract a specific value from a specific nested JSON object in a field

The following example extracts the length of the first bridge from the third city from the JSON object. This extraction can return any type of value.

... | eval GG_Bridge_length=json_extract(cities,"cities{2}.Bridges{0}.length")

Field	Results
GG_Bridge_length	8981

json_set(<json>, <path_value_pairs>)

Inserts or overwrites values for a JSON node with the values provided and returns an updated JSON object.

Usage

You can use this function with the eval and where commands, and as part of evaluation expressions with other commands.

• If the path contains a list of keys, all of the keys in the chain are created if the keys don't exist.
• If there's a mismatch between the JSON object and the path, the update is skipped and doesn't generate an error. For example, for object {"a": "b"}, json_set(.., "a.c", "d") produces no results since "a" has a string value and "a.c" implies a nested object.
• If the value already exists and is of a matching non-value type, the json_set function overwrites the value by default. A value type match isn't enforced. For example, you can overwrite a number with a string, Boolean, null, and so on.

To use named arguments, you must specify the path value pairs in an array, enclosing the pairs in square brackets. The syntax for named arguments is json_set(json:<json>, path_value_pairs:[<path>, <value>...]). For example:

... json_set(json:games, path_value_pairs:["category.boardgames.cooperative{2}", "name":"Sherlock Holmes: Consulting Detective"])

Examples

These examples use this JSON object, which is in a field called games in an event:

{
  "category": {
    "boardgames": {
      "cooperative": [
        {
          "name": "Pandemic"
        },
        {
          "name": "Forbidden Island"
        },
        {
          "name": "Castle Panic"
        }
      ]
    }
  }
}

1. Overwrite a value in an existing JSON array

The following example overwrites the value "Castle Panic" in the path [category.boardgames.cooperative] in the JSON object. The value is replaced with "name":"Sherlock Holmes: Consulting Detective". The results are placed into a new field called my_games.

The position count starts with 0. The third position is 2, which is why the example specifies {2} in the path.

... | eval my_games = json_set(games,"category.boardgames.cooperative{2}", "name":"Sherlock Holmes: Consulting Detective")

Here are the results of the search:

Field	Results
my_games	{"category":{"boardgames":{"cooperative":["name":"Pandemic", "name":"Forbidden Island", "name":"Sherlock Holmes: Consulting Detective"]}}}

2. Insert a list of values in an existing JSON object

The following example inserts a list of popular games ["name":"Settlers of Catan", "name":"Terraforming Mars", "name":"Ticket to Ride"] into the path [category.boardgames.competitive] in the JSON object.

Because the key competitive doesn't exist in the path, the key is created. The json_array function is used to append the value list to the boardgames JSON object.

...| eval my_games = json_set(games,"category.boardgames.competitive", json_array(json_object("name", "Settlers of Catan"), json_object("name", "Terraforming Mars"), json_object("name", "Ticket to Ride")))

Here are the results of the search:

Field	Results
my_games	{"category":{"boardgames":{"cooperative":["name":"Pandemic", "name":"Forbidden Island", "name":"Sherlock Holmes: Consulting Detective"],"competitive": ["name":"Settlers of Catan", "name":"Terraforming Mars", "name":"Ticket to Ride"]}}}

The JSON object now looks like this:

{
  "category": {
    "boardgames": {
      "cooperative": [
        {
          "name": "Pandemic"
        },
        {
          "name": "Forbidden Island"
        },
        {
          "name": "Castle Panic"
        }
      ]
    },
    "competitive": [
      {
        "name": "Settlers of Catan"
      },
      {
        "name": "Terraforming Mars"
      },
      {
        "name": "Ticket to Ride"
      }
    ]
  }
}

3. Insert a set of key-value pairs in an existing JSON object

The following example inserts a set of key-value pairs that specify if the game is available using a Boolean value. These pairs are inserted into the path [category.boardgames.competitive] in the JSON object. The json_array function is used to append the key-value pairs list to the boardgames JSON object.

...| eval my_games = json_set(games,"category.boardgames.competitive{}.available", true())

Here are the results of the search:

Field	Results
my_games	{"category":{"boardgames":{"cooperative":["name":"Pandemic", "name":"Forbidden Island", "name":"Sherlock Holmes: Consulting Detective"],"competitive": ["name":"Settlers of Catan", "available":true, "name":"Terraforming Mars", "available":true, "name":"Ticket to Ride", "available":true]}}}

The JSON object now looks like this:

{
  "category": {
    "boardgames": {
      "cooperative": [
        {
          "name": "Pandemic"
        },
        {
          "name": "Forbidden Island"
        },
        {
          "name": "Castle Panic"
        }
      ]
    },
    "competitive": [
      {
        "name": "Settlers of Catan",
        "available": true
      },
      {
        "name": "Terraforming Mars",
        "available": true
      },
      {
        "name": "Ticket to Ride",
        "available": true
      }
    ]
  }
}

If the Settlers of Catan game is out of stock, you can overwrite the value for the available key with the value false().

For example:

... | eval my_games = json_set(games,"category.boardgames.competitive{0}.available", false())

Here are the results of the search:

Field	Results
my_games	{"category":{"boardgames":{"cooperative":["name":"Pandemic", "name":"Forbidden Island", "name":"Sherlock Holmes: Consulting Detective"],"competitive": ["name":"Settlers of Catan", "available":false, "name":"Terraforming Mars", "available":true, "name":"Ticket to Ride", "available":true]}}}

The JSON object now looks like this:

{
  "category": {
    "boardgames": {
      "cooperative": [
        {
          "name": "Pandemic"
        },
        {
          "name": "Forbidden Island"
        },
        {
          "name": "Castle Panic"
        }
      ]
    },
    "competitive": [
      {
        "name": "Settlers of Catan",
        "available": false
      },
      {
        "name": "Terraforming Mars",
        "available": true
      },
      {
        "name": "Ticket to Ride",
        "available": true
      }
    ]
  }
}

json_valid(<json>)

Evaluates whether piece of JSON uses valid JSON syntax and returns either TRUE or FALSE.

Usage

You can use this function with the eval and where commands, and as part of evaluation expressions with other commands.

To use named arguments, you must specify the argument name before the argument value. For example:

... json_valid(json:names)

Example

Validate a JSON object

The following example validates a JSON object { "names": ["maria", "arun"] } in the firstnames field.

Because fields cannot hold Boolean values, the if function is used with the json_valid function to place the string value equivalents of the Boolean values into the isValid field.

... | eval IsValid = if(json_valid(firstnames), "true", "false")

See also

Functions

Evaluation functions quick reference