API Reference

Note: All API described below is the current v1 contract for 0.1.0.

All public API lives in the package io.github.arthurhoch.kissjson.

Json

The main entry point for serialization and deserialization.

public final class Json

create()

public static Json create()

Creates a Json instance with default configuration. Equivalent to Json.builder().build().

builder()

public static JsonBuilder builder()

Returns a new JsonBuilder for configuring a Json instance with custom options.

config()

public JsonConfig config()

Returns the immutable JsonConfig for this instance.

stringify(Object)

public String stringify(Object value)

Serializes the given Java object to a JSON string.

• Parameters: value — the object to serialize. May be null (returns "null").
• Returns: JSON string.
• Throws:
  • JsonException — if cycle detection triggers or max depth is exceeded.

parse(String, Class<T>)

public <T> T parse(String json, Class<T> type)

Deserializes a JSON string to an object of the given type.

• Parameters:
  • json — the JSON string to parse.
  • type — the target class.
• Returns: deserialized object.
• Throws:
  • JsonParseException — if the JSON is syntactically invalid.
  • JsonMappingException — if the JSON cannot be mapped to the target type.
  • NullPointerException — if json or type is null.

parseList(String, Class<T>)

public <T> List<T> parseList(String json, Class<T> elementType)

Deserializes a JSON array to a List<T>.

• Parameters:
  • json — the JSON array string.
  • elementType — the element type.
• Returns: List<T> of deserialized elements.
• Throws:
  • JsonParseException — if the JSON is syntactically invalid or not an array.
  • JsonMappingException — if an element cannot be mapped.

parseMap(String)

public Map<String, Object> parseMap(String json)

Deserializes a JSON object to a Map<String, Object>. Values are mapped to their natural Java types:

• Parameters: json — the JSON object string.
• Returns: Map<String, Object>.
• Throws: JsonParseException — if the JSON is syntactically invalid.

parseMap(String, Class<T>)

public <T> Map<String, T> parseMap(String json, Class<T> valueType)

Deserializes a JSON object to a Map<String, T> where each value is deserialized to the given type.

• Parameters:
  • json — the JSON object string.
  • valueType — the value type class.
• Returns: Map<String, T>.
• Throws:
  • JsonParseException — if the JSON is syntactically invalid.
  • JsonMappingException — if a value cannot be mapped.

JsonBuilder

Builder for creating Json instances with custom configuration.

public final class JsonBuilder

All setter methods return this for chaining. Call build() to create the Json instance.

fieldNaming(FieldNaming)

public JsonBuilder fieldNaming(FieldNaming strategy)

Sets the naming strategy for mapping Java field names to JSON keys. Default: FieldNaming.IDENTITY.

includeNulls(boolean)

public JsonBuilder includeNulls(boolean value)

Whether to include null fields in serialized JSON output. Default: true.

failOnUnknownProperties(boolean)

public JsonBuilder failOnUnknownProperties(boolean value)

Whether to throw JsonMappingException when a JSON key has no matching field. Default: false (ignore).

failOnMissingRequiredFields(boolean)

public JsonBuilder failOnMissingRequiredFields(boolean value)

Whether to throw JsonMappingException when a @JsonRequired field is missing. Default: false. With the default, missing required fields keep normal Java defaults; strict required-field enforcement is opt-in.

failOnNullForPrimitives(boolean)

public JsonBuilder failOnNullForPrimitives(boolean value)

Whether to throw JsonMappingException when a null JSON value maps to a primitive field. Default: false (assign default value).

failOnDuplicateKeys(boolean)

public JsonBuilder failOnDuplicateKeys(boolean value)

Whether to throw JsonParseException when a JSON object contains duplicate keys. Default: false (last wins).

failOnCycles(boolean)

public JsonBuilder failOnCycles(boolean value)

Whether to detect and throw on circular references during serialization. Default: true.

maxDepth(int)

public JsonBuilder maxDepth(int value)

Maximum nesting depth for serialization and deserialization. Must be positive. Default: 128.

prettyPrint(boolean)

public JsonBuilder prettyPrint(boolean value)

Whether to format JSON output with indentation (2 spaces). Default: false.

dateFormat(DateFormat)

public JsonBuilder dateFormat(DateFormat value)

Global date/time format strategy. Default: DateFormat.ISO.

zoneId(ZoneId)

public JsonBuilder zoneId(ZoneId value)

Timezone for java.util.Date and java.util.Calendar conversion. Default: ZoneId.of("UTC").

enumMode(EnumMode)

public JsonBuilder enumMode(EnumMode value)

Enum serialization/deserialization mode. Default: EnumMode.NAME.

build()

public Json build()

Creates a new Json instance with the configured options. The returned Json is immutable and thread-safe for reads.

JsonConfig

Immutable configuration snapshot.

public final class JsonConfig

Obtained via Json.config(). All fields are read-only.

JsonException

Base exception for all KissJson errors.

public class JsonException extends RuntimeException

• Extends RuntimeException (unchecked).
• Carries a descriptive message with context.

JsonParseException

Thrown when JSON text is syntactically invalid.

public final class JsonParseException extends JsonException

line()

public int line()

Returns the 1-based line number where the error occurred.

column()

public int column()

Returns the 1-based column number where the error occurred.

offset()

public int offset()

Returns the 0-based character offset where the error occurred.

JsonMappingException

Thrown when JSON cannot be mapped to the target Java type.

public final class JsonMappingException extends JsonException

jsonPath()

public String jsonPath()

Returns the JSON path to the error location, e.g. $.user.address.zipCode.

targetType()

public Class<?> targetType()

Returns the target Java class being deserialized.

fieldName()

public String fieldName()

Returns the Java field name where the error occurred, or null if not applicable.

expectedType()

public Class<?> expectedType()

Returns the expected Java type, or null if not applicable.

actualValue()

public Object actualValue()

Returns the actual JSON value that caused the error (truncated if too long), or null if not applicable.

FieldNaming

Naming strategies for field-to-JSON-key mapping.

public enum FieldNaming

DateFormat

Date/time format strategies.

public enum DateFormat

EnumMode

Enum serialization/deserialization modes.

public enum EnumMode

Annotations

All annotations target fields and have runtime retention.

@JsonName

@io.github.arthurhoch.kissjson.JsonName("custom_name")

Specifies a custom JSON key name for a field. Takes precedence over naming strategies.

• Applies to: serialization and deserialization
• Example: @JsonName("user_name") String userName → JSON key is "user_name"

@JsonAliases

@io.github.arthurhoch.kissjson.JsonAliases({"alias1", "alias2"})

Specifies alternative JSON key names accepted during deserialization. Useful for backward compatibility.

• Applies to: deserialization only
• Example: @JsonAliases({"userName", "user_name"}) String name — JSON keys "userName" or "user_name" both map to name
• Multiple matches: First matching alias wins (order matters)

@JsonIgnore

@io.github.arthurhoch.kissjson.JsonIgnore

Excludes the field from both serialization and deserialization.

• Applies to: serialization and deserialization
• Example: @JsonIgnore String internalId — never appears in JSON

@JsonRequired

@io.github.arthurhoch.kissjson.JsonRequired

Marks a field as required during deserialization when failOnMissingRequiredFields(true) is configured. The JSON key must be present (value can be null).

• Applies to: deserialization only
• Example: @JsonRequired String email — JSON must contain "email" key
• Error: JsonMappingException if the key is missing and required-field enforcement is enabled

@JsonIncludeNull

@io.github.arthurhoch.kissjson.JsonIncludeNull

Always include this field in serialized output, even when its value is null. Overrides a global includeNulls = false setting.

• Applies to: serialization only
• Example: @JsonIncludeNull String middleName — always appears in JSON output

@JsonExcludeNull

@io.github.arthurhoch.kissjson.JsonExcludeNull

Exclude this field from serialized output when its value is null. Overrides a global includeNulls = true setting.

• Applies to: serialization only
• Example: @JsonExcludeNull String nickname — omitted from JSON when null

@JsonDateFormat

@io.github.arthurhoch.kissjson.JsonDateFormat("yyyy-MM-dd")

Specifies a custom date format pattern for a specific field. Overrides the global dateFormat setting.

• Applies to: serialization and deserialization
• Parameter: value — a java.time.format.DateTimeFormatter pattern string
• Example: @JsonDateFormat("dd/MM/yyyy") LocalDate birthDate → "15/01/2025"

Thread Safety

All API described above is the current v1 contract for 0.1.0.