Overview (Hibiscus 0.3.0 API)

Packages
Package	Description
com.github.i49.hibiscus.common	Provides common classes shared among all packages in this library.
com.github.i49.hibiscus.facets	Provides various kinds of facets that allow you to restrict the value spaces of built-in types in schema for JSON.
com.github.i49.hibiscus.formats	Provides various kinds of formats that allow you to specify the known format for values of types declared in schema for JSON.
com.github.i49.hibiscus.json	Provides helper classes to enhance Java API for JSON Processing (JSR 353), which are used only inside of this library.
com.github.i49.hibiscus.problems	Provides classes representing problems that will be detected by validation of JSON document.
com.github.i49.hibiscus.schema	Provides schema components such as schema, built-in types and object properties, which are used to define schemas for JSON document.
com.github.i49.hibiscus.schema.internal	Provides implementations of the schema components.
com.github.i49.hibiscus.validation	Provides a JSON validator and its supporting types.

Hibiscus is JSON validator that verifies JSON documents against your schema which can be written as Java code.

1. Introduction

1.1 Schema example

As first example we assume that you have JSON document below that you would like to validate in your application.

{
  "firstName": "Jason",
  "lastName": "Bourne",
  "age": 46,
  "hobbies": ["shooting", "recollection"]
}

Supposing that the first two properties of the object are mandatory and others are optional. We can write the schema for this kind of document as Java code like following:

Schema schema = schema(
  object(
    required("firstName", string()),
    required("lastName", string()),
    optional("age", integer()),
    optional("hobbies", array(string()))
  )  
);

1.2. How to write your own JSON validator

Create a new class that extends BasicJsonValidator class.

import com.github.i49.hibiscus.validation.BasicJsonValidator;

public class PersonValidator extends BasicJsonValidator {
}

Add static import statement which will make your schema building easier.
```
import static com.github.i49.hibiscus.schema.SchemaComponents.*;
```

Define your schema as a class constant of your validator.

import com.github.i49.hibiscus.validation.BasicJsonValidator;
import com.github.i49.hibiscus.schema.Schema;
import static com.github.i49.hibiscus.schema.SchemaComponents.*;

public class PersonValidator extends BasicJsonValidator {
  // Schema definition.
  private static final Schema schema = schema(
    object(
      required("firstName", string()),
      required("lastName", string()),
      optional("age", integer()),
      optional("hobbies", array(string()))
    )
  );  
}

Pass the schema to the constructor of superclass, and then your work is done.

import com.github.i49.hibiscus.validation.BasicJsonValidator;
import com.github.i49.hibiscus.schema.Schema;
import static com.github.i49.hibiscus.schema.SchemaComponents.*;

public class PersonValidator extends BasicJsonValidator {
  // Schema definition.
  private static final Schema schema = schema(
    object(
      required("firstName", string()),
      required("lastName", string()),
      optional("age", integer()),
      optional("hobbies", array(string()))
    )
  );  

  public PersonValidator() {
    super(schema)
  }
}

The next section shows you how to use the validator you created.

1.3. How to validate JSON documents with your validator

Create an instance of your validator.

PersonValidator validator = new PersonValidator();

Validate JSON document with the validator.

// An object to retrieve validation result.
ValidationResult result = null;
try (Reader reader = new FileReader("person.json")) {
  // Reads and validates JSON document here.
  result = validator.validate(reader);
}

Process detected problems properly.
```
for (Problem problem: result.getProblems()) {
  // Handles each problem here.
  // We just print text representation of the problem here.
  System.out.println(problem);
}
```
One of the nice features of Hibiscus is that it reports where these problems occurred, such as line and column numbers. This can be accomplished because the library do both loading and validating JSON document at the same time, not after completely loading it and building a tree of JSON values.
Make use of retrieved JSON value as you like in your application.
```
JsonValue root = result.getValue();
```
Hibiscus returns JSON values defined in Java API for JSON Processing (JSR-353, JSON-P). Please note that it returns JSON value even when the JSON document does not obey the given schema, as long as the document is well-formed and not broken as JSON.

2. Schema Basics

2.1. Schema

The top level component of your schema is Schema which can be instantiated by calling SchemaComponents.schema() class method.


import static com.github.i49.hibiscus.schema.SchemaComponents.*;
Schema s = schema(/* type declarations here. */);

The parameters of this method are types that allowed to be at the root of JSON documents. All types that are useful to write schema will be introduced in the next section.

2.2. Built-in Types

This library offers following built-in types which can be used to define schemas for JSON.

The list of built-in types
No.	Type Name	Creation Method	Interface	Description	Sample Values
1	array	`SchemaComponents.array()`	`ArrayType`	JSON array	`["milk", "bread", "eggs"]`
2	bool	`SchemaComponents.bool()`	`BooleanType`	JSON boolean	`true`
3	integer	`SchemaComponents.integer()`	`IntegerType`	JSON number without a fractional part	`42`
4	number	`SchemaComponents.number()`	`NumberType`	JSON number	`3.14`
5	null	`SchemaComponents.nil()`	`NullType`	JSON null	`null`
6	object	`SchemaComponents.object()`	`ObjectType`	JSON object	`{"name": "John", "age": 33}`
7	string	`SchemaComponents.string()`	`StringType`	JSON string	`"hello"`

All methods that will create these built-in types are provided as SchemaComponents class methods.


import static com.github.i49.hibiscus.schema.SchemaComponents.*;
BooleanType b = bool();
IntegerType i = integer();
NumberType n = number();
NullType nil = nil();
StringType s = string();