Fork me on GitHub

Working with JSON

Ninja provides out of the box support to render arbitrary Java objects as JSON as well as parsing of JSON into Java objects.

Rendering JSON

Consider this simple model class:

package models;

public class Person {       
    String name;

And this controller:

package controllers;

public class ApplicationController {       

    public Result index() {

        Person person = new Person(); = "John Johnson";

        return Results.json().render(person);


This controller will produce a nicely formatted JSON output:

{"name":"John Johnson"}

Parsing JSON

If you want to parse incoming JSON requests you simply have to add the mapping POJO to the controller method signature.

Consider the following JSON:

{"name":"John Johnson"}

This JSON maps to the following Java POJO:

package models;

public class Person {       
    String name;

If you send that JSON to your application via the HTTP body you only need to add the POJO class to the controller method and Ninja will parse the incoming JSON for you:

package controllers;

public class ApplicationController {       

    public Result parsePerson(Person person) {
        String nameOfPerson =; // will be John Johnson


Rendering JSONP

Rendering JSONP (JSON wrapped by Javascript function call) is quite similar to rendering plain JSON:


The only important difference that the function name to render must be defined via parameter callback. For instance ?callback=MyApp.Path.myCallback123 would then produce the following output:


You can change the name of the callback parameter (callback by default) in your application.conf via

ninja.jsonp.callbackParameter=... // specify your custom callback parameter name
The value of the callback parameter is sanitized for security reasons. Only plain callback parameter values are possible. Something like ?callback=MyApp.Path.myCallback123 works, but ?callback=alert(document.cookie) does not work.

Advanced JSON usage

Under the hood Ninja uses Jackson ( Jackson is one of the most widely used JSON serializers of the Java ecosystem.

If you want to customize the way Jackson works you can do so by injecting ObjectMapper into a startup action and modifying it.

public class MyObjectMapper {

    ObjectMapper objectMapper;

    @Start(order = 90)
    public void configureObjectMapper() {
        // Adding Joda Time parsing and rendering support to Jackson
        objectMapper.registerModule(new JodaModule());     

ObjectMapper is a singleton and can be modified and extended by your application.

It is safe to modify ObjectMapper before it is actually used, but it is not threadsafe to modify ObjectMapper after is has been used to parse or generate JSON.

In order to replace the provided Jackson ObjectMapper with your own do this in your own guice module:

OptionalBinder.newOptionalBinder(binder(), ObjectMapper.class)

More on Jackson modules:

Jackson JSON Views

Ninja also supports Jackson's JSON Views: with @JsonView annotations you can easily define which properties of an object you want to include in the JSON output. A simple example where only the “name” field will be included:

public class AppController {

    public Result jsonPerson() {
        Person person = new Person(); = "John Doe";
        person.age = 56;
        return Results.json().jsonView(View.Public.class).render(person);
    static class Person {
        public String name;
        public Integer age;
    static class View {
        static class Public {}
        static class Private {}

More on Jackson's JSON Views: