Generate builder methods
Use primitive types
Use long integers
Use double numbers
Use Joda dates
Use Commons-Lang3
Include getters and setters
Include constructors
Include hashCode and equals
Include toString
Include JSR-303 annotations
Allow additional properties
Make classes serializable
Make classes parcelable
Initialize collections

Property word delimiters:

Preview

Reference

properties

For each property present in the 'properties' definition, we add a property to a given Java class according to the JavaBeans spec. A private field is added to the parent class, along with accompanying accessor methods (getter and setter).

When applying the usePrimitives option, the primitives double, integer and boolean will replace the wrapper types listed above.

additionalProperties

If additionalProperties is specified and set to the boolean value false, then the generated Java type does not support additional properties.

If the additionalProperties node is undefined (not present), null or empty, then a new bean property named "additionalProperties", of type Map<String,Object> is added to
the generated type (with appropriate accessors). The accessors are
annotated to allow Jackson to marshal/unmarshal unrecognised (additional) properties found in JSON data from/to this map.

If the additionalProperties node is present and specifies a schema, then an "additionalProperties" map is added to the generated type and map values will be restricted according to the additionalProperties schema.

Where the additionalProperties schema species a type object, map values will be restricted to instances of a newly generated Java type. If the given schema does not specify the =javaType= property, the name of the newly generated type will be derived from the parent type name and the suffix 'Property'.

produces a property called myArrayProperty of type List<String> in the generated Java type. If items itself declares a complex type ("type" : "object") then the generic type of the List or Set will itself be a generated type e.g. List<MyComplexType>.

required

The 'required' schema rule doesn't produce a structural change in generated Java types, it simply causes the text (Required) to be added to the JavaDoc for fields, getters and setters.

optional

The 'optional' schema rule doesn't produce a structural change in generated Java types, it simply causes the text (Optional) to be added to the JavaDoc for fields, getters and setters.

This schema rule is deprecated since Draft 03 of the JSON Schema specification. Rather than marking optional properties as optional, one should mark required properties as required.

uniqueItems

For properties of type 'array', setting uniqueItems to false (or omitting it entirely) causes the generated Java property to be of type java.util.List.

When uniqueItems is set to true, the generated Java property value is of type java.util.Set.

enum

When a generated type includes a property of type "enum", the generated enum type becomes a static inner type declared within the enclosing (parent) generated type. If an enum is declared at the root of a schema, the generated enum is a public Java type with no enclosing type.

The actual enum value is held in a 'value' property inside the enum constants. The generated enum type also includes annotations that allow Jackson to correctly marshal/unmarshal JSON values, even when the actual values contain spaces, start with digits, or contain other characters that cannot legally form part of the Java enum constant name.

default

Using the default rule in your JSON Schema causes the corresponding property in your generated Java type to be initialised with a default value. You'll see the default value is assigned during field declaration.

Default values are supported for the JSON Schema properties of type string, integer, number and boolean; for enum properties; for properties with format of utc-millisec or date-time; for arrays of any of these types.

Some example JSON Schema property definitions and their corresponding Java field declaration are shown:

As the above table shows, dates can be given a default using either a number of millis since epoch or a date string (ISO 8601 or RFC 1123). In either case, the date will be initialized using a millisecond value in the generated Java type.

title

The 'title' rule appearing in a JSON Schema causes the given title text to be added to the JavaDoc for a property. The title text will appear in JavaDoc comments of the field, getter and setter.

title text always appears before description text.

description

The description rule appearing in a JSON Schema causes the given description text to be added to the JavaDoc for a property. The description text will appear in JavaDoc comments of the field, getter and setter.

description text always appears after title text.

format

Using the format rule for a property can influence the Java type chosen to represent your property values. When you use a format value that jsonschema2pojo recognises, it will use a better (more appropriate) type for your Java bean property.

For example, when I define a JSON property in my schema of type string, if I also attach the rule "format" : "uri" to that property (because my string is actually a URI) then my corresponding Java property will now have the type java.net.URI instead of java.lang.String.

How jsonschema2pojo maps format values to Java types:

Format value

Java type

"date-time"

java.util.Date

"date"

String

"time"

String

"utc-millisec"

long

"regex"

java.util.regex.Pattern

"color"

String

"style"

String

"phone"

String

"uri"

java.net.URI

"email"

String

"ip-address"

String

"ipv6"

String

"host-name"

String

"uuid"

java.util.UUID

anything else (unrecognised format)

type is unchanged

extends

When the extends rule is encountered in your JSON schema (to indicate that one type extends another), this will produce an extends relationship in your generated Java types. That extends value can be a schema given in-line, or referenced using $ref.

As an example, lets imagine a file flower.json with the following content:

{
"type" : "object"
}

and a second file rose.json which contains:

{
"type" : "object",
"extends" : {
"$ref" : "flower.json"
}
}

The two resulting Java types generated from these schemas would be:

publicclassFlower {
....
}

and

publicclassRoseextendsFlower {
....
}

Note: the extends rule in JSON schema accepts a schema or an array of schemas - jsonschema2pojo only supports the single schema variant.

$ref

A '$ref' rule can be used wherever a schema is expected i.e at the root of a schema document, as part of a property definition, as part of the items definition for an array type, as part of an additionalProperties definition.

Supported protocols:

http://, https://

file://

classpath:, resource:, java: (all synonyms used to resolve schemas from the classpath).

Note: If you want to refer to classpath resources from the current Maven module, you will need to bind jsonschema2pojo to a later phase. By default jsonschema2pojo is bound to generate-sources but if you want resources present in the current module to be on the classpath when the plugin executes, then you should bind jsonschema2pojo to the process-resources phase.

For example, to refer to another document in the same directory which will provide the definition of a 'user' object, you might create a schema like:

jsonschema2pojo expects $ref values (URIs) to be URLs. Both absolute and relative URLs are valid. You may also refer to part of a schema document using the '#' character followed by a slash or dot delimited path.

The javaType property also allows existing Java types to be used in your POJOs. If the value of javaType refers to an existing class or interface on the classpath, then that class/interface will be used (a new Java type will not be generated).

javaInterfaces

Any schema may include a javaInterfaces property, the value of this property is an array of strings. Each string is expected to contain the fully-qualified name of a Java interface. The Java type generated by the schema will implement all the given interfaces.

javaJsonView

Any schema may include a javaJsonView property, the value of the property is a fully qualified class name. The property causes a @JsonView annotation to be added to the member with the given class for a value. This only works for Jackson-based annotators. It is supported for v1 and v2 Jackson. See Jackson Annotations.

customPattern/customTimezone

Set a custom format pattern for date or date-time fields that will be used during serialization (if your binding library supports it). If you're using Jackson 2 this will cause an @JsonFormat annotation to be added. For 'date-time' fields you may also set a custom timezone (if you want to use a timezone other than UTC when writing out the date-time as a string).

There are two important things to note before using this extension property:

If you set the formatDates/formatDateTimes global config options to true, you'll get default ISO-8601/RFC 3339 formatting without having to set these custom properties.

You should be aware that setting a custom date or date-time pattern may mean that the JSON content you produce is not valid according to the rules of JSON Schema.

excludedFromEqualsAndHashCode

You can specify which fields should be omitted in the generated equals() and hashCode() methods using the excludedFromEqualsAndHashCode rule. These fields can be either listed in an object-level array or flagged individually.

This option is only meaningful if equals() and hashCode() generation is enabled.