JsonTemplate

A Java tool for generating json strings.

Maven Central Javadoc

Getting started

<dependency>
    <groupId>com.github.json-template</groupId>
    <artifactId>jsontemplate</artifactId>
    <version>0.2.1</version>
</dependency>

Suppose that we want to create the following json String,

{
  "name" : "John",
  "age" : 23,
  "role" : [ "developer", "tester" ],
  "address" : {
    "city" : "Utrecht",
    "street" : "Musicallaan",
    "number" : 413
  }  
}

With JsonTemplate, you can do it in the following way. Compared to the typical solution, JsonTemplate saves you effort in reading and writing the escaped quotes "\"".

String template = "{" +
                  "  name : John," +
                  "  age : 23," +
                  "  role : [ developer, tester ]," +
                  "  address : {" +
                  "    city : Utrecht," +
                  "    street : Musicallaan," +
                  "    number : 413" +
                  "  }" +
                  "}";
String json = new JsonTemplate(template).prettyString();

Furthermore, suppose that what you need is only a schema-compatible json and you don't want to bother with the specific values. This is usually the case when you test the validation logic in the controllers. JsonTemplate allows you to code in the following way:

String template = "{" +
                  "  name : @s," +
                  "  age : @i(max=100)," +
                  "  role : @s[](min=1, max=3)," +
                  "  address : {" +
                  "    city : @s," +
                  "    street : @s," +
                  "    number : @i" +
                  "  }" +
                  "}";
String json = new JsonTemplate(template).prettyString();

Examples

Smart conversion

TemplateGenerated Json
{
  name : John,
  age : 23,
  accountBalance: 30.4,
  married : true,
  role : programmer
}

{
  "name" : "John",
  "age" : 23,
  "accountBalance": 30.4,
  "married" : true,
  "role" : "programmer"
}

JsonTemplate automatically converts a string into a json value with the type which the string looks like. For example, "23" looks like a number, therefore it is converted to a json numeric value.

If this is not the intention, a specific value producer needs to be given, e.g. @s(23).

Value producers

TemplateGenerated Json
{
  aField : @s
}

{
  "aField" : "ISCZd"
}

In JsonTemplate, @x can refer to a value producer or a value producer declaration (will be described later). When it is at the value part, it is a value producer.

Following is the table about all the pre-installed value producers:

value producer description
@smart used for smart conversion, it is the default value producer which is implicitly used.
@s produces a string
@i produces an integer
@f produces a float
@b produces a boolean
@raw produces a raw string content
@ip produces an ip string
@ipv6 produces an ipv6 string
@base64 produces a base64 string
@iso8601 produces a ISO8601 string
@cat used for concatenating strings

Value producers with a single parameter

TemplateGenerated Json
{
  aField : @s(myValue)
}

{
  "aField" : "myValue"
}

If a single parameter is given, the value producer produces a fixed value correspondingly by default.

Value producers with a list parameter

TemplateGenerated Json
{
  aField : @s(A, B, C, D)
}

{
  "aField" : "C"
}

If a list parameter is given, the value producer randomly selects a value from that list by default.

Value producers with a map parameter

TemplateGenerated Json
{
  aField : @s(length=10)
}

{
  "aField" : "awpVXpJTxb"
}

{
  aField : @s(min=10, max=20)
}

{
  "aField" : "AgPkUNKonauaxJgct"
}

If a map parameter is given, the value producer produces a value according to the map values.

Following is the table about whether each type of parameter is supported by the pre-installed producers.

producer none single list map
@smart no, produce null yes no no
@s yes yes yes yes, supported parameters: length, max, min
@i yes yes yes yes, supported parameters: max, min
@f yes yes yes yes, supported parameters: max, min
@b yes yes yes no
@raw no yes no no
@ip yes no no no
@ipv6 yes no no no
@base64 yes no no yes, supported parameters: length
@iso8601 yes no no no
@cat yes yes yes no

Json objects

TemplateGenerated Json
{
  anObject : {
    aField : @s, 
    bField : @s
  }
}

{
  "anObject" : {
    "aField" : "hhnNc",
    "bField" : "EyHbB"
  }
}

A json object consists of a set of properties. Each property can be specified with a value producer. The default type is @smart which is implicitly used.

Array producer with size configuration

TemplateGenerated Json
@s[](3)

[ "hwhCL", "tDcPO", "OgdGC" ]

@s[](1, 10)

[ "QwWxg", "ytaGY", "NGZBr", "DsBKx", "MvwSb", "qsEXA", "YHkxC" ]

Array tag [] indicates producing a json array. The default value producer for the array elements is placed before []. The size configuration of the generated array is placed after [].

Array producer with elements

TemplateGenerated Json
@s[ 1, 2, 3, 4 ]

[ "1", "2", "3", "4" ]

@s[ 1, 2, 3, 4 ](6)

[ "1", "2", "3", "4", "qRTWm", "RTBik" ]

@s[ 1, @i(2), @b(false), @s(4) ]

[ "1", 2, false, "4" ]

Customized value producer definition

TemplateGenerated Json
@address : {
  city : @s,
  street : @s,
  number : @i
},
{
  office : @address, 
  home : @address
}

{
  "office" : {
    "city" : "MavBr",
    "street" : "odcjd",
    "number" : 79
  },
  "home" : {
    "city" : "zdNCm",
    "street" : "UsBcv",
    "number" : 63
  }
}

A value producer @x can be used for value producer declaration.
The declaration can be before or after the json root, separated by comma ,. The order between multiple declarations do not matter.

Default value producer

TemplateGenerated Json
@s {
  fieldA, 
  fieldB,
  fieldC: @i
}

{
  "fieldA" : "yUiIE",
  "fieldB" : "vrMwv"
  "fieldC" : 54
}

In the above example, the default value producer is explicitly specified as @s. If nothing is specified, @smart is used. In case of @s, it supports none parameters. Therefore, the values of fieldA and fieldB can be omitted. @s will generate a random value form them.

The mechanism of searching the default value producer is the same as Java inheritance: It starts from itself to the root, util it finds a value producer.

Inject variables

JsonTemplate allows to inject variables to the template, it provides two methods to do that:

Use the variable as values

TemplateGenerated Json
{
  name : $name
}

{
  "name" : "John"
}

In the above example, token $ indicates a variable. Variable name refers to a string John.

TemplateGenerated Json
{
  letters : $letters
}

{
  "letters" : [ "A", "B", "C" ]
}

In the above example, variable letters refers to an array ["A", "B", "C"] or a collection with elements "A", "B", "C".

TemplateGenerated Json
{
  person : $person
}

{
  "person" : {
    "languages" : [ "Chinese", "English", "Dutch" ],
    "name" : "Haihan",
    "age" : 33,
    "male" : true
  }
}

In the above example, variable person refers to an map object.

Use variables as parameters

Variables can be also put in the parameters of a value producer.

When variable used as a single parameter, the parameter type (single, list, or map) is adjusted according to the type of the variable.

When variable used as list or map parameter, the semantics won't change.

Customize value producers

JsonTemplate does not aim for providing the full-fledged value generation. Other libraries, such as Guava, Apache Commons, JFaker, etc., provide powerful value generation apis.

The pre-installed value producers are designed in a way which can be extended. With JsonTemplate.withValueProducer(IValueProducer), users can freely extend the pre-installed values producers or create new ones.

Above is just a peek for the list of features. For more examples, examples.txt provides part of the logs in tests.

Support

If you have issues, great ideas, or comments, please let us know. We have a mailing list located at: [email protected]