Search
Varnish Enterprise

JSON parsing (json)

Description

The json vmod allows for JSON parsing. It can parse JSON strings, request body JSON, and response body JSON.

To use this vmod, a JSON context must first be created using one of the parse functions. This context is then used by all subsequent vmod_json function calls. Creating a new context will clear any previously created context.

In addition, this vmod can be used in conjunction with other vmods, such as vmod_jwt and vmod_edgestash.

Examples

Item at Array Index

vcl 4.1;

import json;

sub vcl_deliver {
  json.parse({"{
    "baz": [
      3.14159,
      "pie",
      true
      ]
    }"});

  if (json.is_valid()) {
    set resp.http.result = json.get("baz[1]");
  }
}

Request Body Parsing

vcl 4.0;

import json;
import std;

sub vcl_recv
{
  std.cache_req_body(100KB);
  json.parse_req_body();

  if (json.is_valid() && json.is_object() &&
    json.get("authorization")) {
    req.http.X-authorization = json.get("authorization");
  } else {
    return(synth(401));
  }
}

API

parse

VOID parse(STRING json)

Parse a JSON string and create a new JSON context. Any previous context is freed.

Arguments:

  • json accepts type STRING

Type: Function

Returns: None

parse_req_body

VOID parse_req_body()

Parse a request body and create a new JSON context. Can only be used in sub vcl_recv. std.cache_req_body() must be called prior. Any previous context is freed.

Arguments: None

Type: Function

Returns: None

Restricted to: vcl_recv

parse_resp_index

VOID parse_resp_index()

Parse a response body and create a new JSON context. Must be used in conjunction with edgestash.index_json(). Can only be used in sub vcl_deliver. Any previous context is freed.

Arguments: None

Type: Function

Returns: None

Restricted to: vcl_deliver

contains

BOOL contains(STRING element)

Traverse from the document root with a given path. For example, myobject.value requires myobject to be in the root, and value to be a child. You can’t search for arbitrary values without a full path. This function is faster to call than get and does not require workspace allocations.

Arguments:

  • element accepts type STRING

Type: Function

Returns: Bool

get

STRING get(STRING search, STRING error = 0, BOOL json_string = 0)

Get the value for search in the current JSON context.

Examples:

  • myobject.value requires myobject to be in the root, and value to be a child.
  • myarray[2] obtains the third entry in an array.

Arguments:

  • search accepts type STRING

  • error accepts type STRING with a default value of 0 optional

  • json_string accepts type BOOL with a default value of 0 optional

Type: Function

Returns: String

length

INT length([STRING element])

Get the length of the JSON node described by element, or the root JSON node if element is not specified. For objects, this function returns the number of keys. For arrays, it returns the number of elements. For everything else, 0.

Arguments:

  • element accepts type STRING

Type: Function

Returns: Int

is_valid

BOOL is_valid()

Is this valid JSON?

Arguments: None

Type: Function

Returns: Bool

is_error

BOOL is_error()

Is this invalid JSON?

Arguments: None

Type: Function

Returns: Bool

is_object

BOOL is_object([STRING element])

Check whether or not the JSON node described by element is an object. If element is not specified, check the root JSON node.

Arguments:

  • element accepts type STRING

Type: Function

Returns: Bool

is_array

BOOL is_array([STRING element])

Check whether or not the JSON node described by element is an array. If element is not specified, check the root JSON node.

Arguments:

  • element accepts type STRING

Type: Function

Returns: Bool

is_string

BOOL is_string([STRING element])

Check whether or not the JSON node described by element is a string. If element is not specified, check the root JSON node.

Arguments:

  • element accepts type STRING

Type: Function

Returns: Bool

is_number

BOOL is_number([STRING element])

Check whether or not the JSON node described by element is a number. If element is not specified, check the root JSON node.

Arguments:

  • element accepts type STRING

Type: Function

Returns: Bool

is_true

BOOL is_true([STRING element])

Check whether or not the JSON node described by element is a true value. If element is not specified, check the root JSON node.

Arguments:

  • element accepts type STRING

Type: Function

Returns: Bool

is_false

BOOL is_false([STRING element])

Check whether or not the JSON node described by element is a false value. If element is not specified, check the root JSON node.

Arguments:

  • element accepts type STRING

Type: Function

Returns: Bool

is_null

BOOL is_null([STRING element])

Check whether or not the JSON node described by element is a null value. If element is not specified, check the root JSON node.

Arguments:

  • element accepts type STRING

Type: Function

Returns: Bool

stringify

STRING stringify(STRING value, BOOL quoted = 1)

Encode value into a JSON safe string

Arguments:

  • value accepts type STRING

  • quoted accepts type BOOL with a default value of 1 optional

Type: Function

Returns: String

reset

VOID reset()

Reset the internal state.

Arguments: None

Type: Function

Returns: None

Availability

The json VMOD is available in Varnish Enterprise version 6.0.6r6 and later.


®Varnish Software, Wallingatan 12, 111 60 Stockholm, Organization nr. 556805-6203