Getting Started¶

This guide walks you through installing Anvil, defining your first schema, and validating JSON using Gson or Jackson.

Prerequisites¶

Java: 21 or higher.
Build tool: Maven or Gradle.
JSON library: Gson or Jackson (or both).

1. Install the dependencies¶

Add the core library and at least one processor to your project. See the Installation section on the Home page for full Maven and Gradle snippets.

At minimum, you need:

anvil-core
anvil-processor-gson or anvil-processor-jackson (or both, if you need)

2. Define a schema¶

Create a class that implements Schema and annotate it with @Validate. Use field-level annotations such as @Regex, @StrIn, numeric annotations, and @OptionalValue to describe the validation rules for each field.

import io.github.anvil.Schema;
import io.github.anvil.annotations.Validate;
import io.github.anvil.annotations.StrIn;
import io.github.anvil.annotations.numeric.Between;

@Validate
public class User implements Schema {
    @StrIn({ "admin", "user", "guest" })
    private String role;

    @Between(min = 18, max = 120)
    private int age;

    private String email;

    @OptionalValue
    private String nickname;
}

3. Validate JSON¶

Create an Anvil instance with your preferred JSON processor, then call validate.

gsonjackson

import com.google.gson.JsonObject;
import io.github.anvil.Anvil;
import io.github.anvil.exceptions.ValidationException;
import io.github.anvil.processor.GsonProcessor;

public class Main {
    public static void main(String[] args) {
        Anvil<JsonObject> anvil = new Anvil<>(new GsonProcessor());

        JsonObject json = new JsonObject();
        json.addProperty("role", "admin");
        json.addProperty("age", 25);
        json.addProperty("email", "user@example.com");

        try {
            User user = anvil.validate(json, User.class);
            System.out.println("Validation successful!");
        } catch (ValidationException e) {
            System.out.println("Validation failed: " + e.getMessage());
        }
    }
}

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import io.github.anvil.Anvil;
import io.github.anvil.exceptions.ValidationException;
import io.github.anvil.processor.JacksonProcessor;

public class Main {
    public static void main(String[] args) throws Exception {
        ObjectMapper mapper = new ObjectMapper();
        ObjectNode json = mapper.createObjectNode()
            .put("role", "admin")
            .put("age", 25)
            .put("email", "user@example.com");

        Anvil<ObjectNode> anvil = new Anvil<>(new JacksonProcessor());

        try {
            User user = anvil.validate(json, User.class);
            System.out.println("Validation successful!");
        } catch (ValidationException e) {
            System.out.println("Validation failed: " + e.getMessage());
        }
    }
}