KissJson AI Skill v0.1.0

This Markdown file is a versioned AI skill for using KissJson in other Java projects. It is intentionally self-contained so an AI assistant can load this one document, add the Maven dependency, write consumer code, and avoid inventing APIs.

Use this skill for release 0.1.0. If the repository source is on a later -SNAPSHOT, consumer documentation should still use 0.1.0 unless the user explicitly asks for a snapshot build.

Library Summary

Tiny zero-dependency Java 17+ JSON serializer and deserializer with explicit field naming, annotations, depth limits, cycle handling, date handling, and enum handling.

Maven Dependency

<dependency>
  <groupId>io.github.arthurhoch</groupId>
  <artifactId>kiss-json</artifactId>
  <version>0.1.0</version>
</dependency>

AI Usage Rules

Target Java 17 or newer.
Prefer the public package rooted at io.github.arthurhoch.kissjson.
Do not invent convenience APIs. Use only the public members listed in this file or in generated Javadocs for the same release.
Keep examples small and explicit, matching the KISS philosophy.
Do not add extra frameworks unless the consuming project already uses them.
Keep older skill files in place when a new release is documented.

Quick Example

Json json = Json.create();

String body = json.stringify(new User("Ada", 42));
User user = json.parse(body, User.class);
List<User> users = json.parseList("[{\"name\":\"Ada\",\"age\":42}]", User.class);

How To Use The Library

Json.create() is the default reusable entry point. Use one Json instance per configuration and reuse it across calls.
Json.builder() configures naming, null handling, strict parsing/mapping behavior, max depth, pretty output, date format, timezone, and enum mode.
stringify(Object) returns JSON text. parse(String, Class<T>) maps a JSON value to a class. parseList and parseMap cover common collection roots.
Use annotations from io.github.arthurhoch.kissjson on fields or types when the JSON contract differs from Java names or default null handling.
Do not import io.github.arthurhoch.kissjson.internal.* in consumer projects. Those classes are implementation details.

Behavioral Contract For v0.1.0

Default configuration is FieldNaming.IDENTITY, include nulls enabled, unknown properties ignored, missing @JsonRequired fields tolerated, duplicate keys tolerated, cycle detection enabled, max depth 128, compact output, ISO dates, UTC zone, and enum names.
FieldNaming values are IDENTITY, LOWER_CASE, UPPER_CASE, CAMEL_CASE, SNAKE_CASE, and KEBAB_CASE.
DateFormat values are ISO, EPOCH_MILLIS, and EPOCH_SECONDS.
EnumMode values are NAME and TO_STRING.
Supported annotation intent: @JsonName overrides the JSON property name, @JsonAliases accepts alternate input names, @JsonIgnore skips a field, @JsonRequired marks a field as required when strict missing-field checks are enabled, @JsonIncludeNull and @JsonExcludeNull override null inclusion, and @JsonDateFormat overrides date formatting for the annotated field.
Expected failures use JsonException and subclasses JsonParseException and JsonMappingException; invalid null inputs to core parse methods throw NullPointerException as declared by the implementation.

Practical Examples

Strict mapper

Json json = Json.builder()
    .fieldNaming(FieldNaming.SNAKE_CASE)
    .failOnUnknownProperties(true)
    .failOnMissingRequiredFields(true)
    .failOnDuplicateKeys(true)
    .maxDepth(64)
    .build();

Annotated DTO

public final class UserDto {
    @JsonName("user_id")
    public long id;

    @JsonAliases({"display", "display_name"})
    public String name;

    @JsonIgnore
    public String transientNote;
}

Public API Specification

The following index is generated from compiled public classes with javap -public. It includes public constructors, constants, enum methods, record accessors, inherited Object overrides when public, and public nested classes.

When an internal package appears here, treat it as implementation detail unless the project documentation explicitly says otherwise. Consumer code should prefer the public surface described above.

public final class io.github.arthurhoch.kissjson.DateFormat extends java.lang.Enum<io.github.arthurhoch.kissjson.DateFormat> {
  public static final io.github.arthurhoch.kissjson.DateFormat ISO;
  public static final io.github.arthurhoch.kissjson.DateFormat EPOCH_MILLIS;
  public static final io.github.arthurhoch.kissjson.DateFormat EPOCH_SECONDS;
  public static io.github.arthurhoch.kissjson.DateFormat[] values();
  public static io.github.arthurhoch.kissjson.DateFormat valueOf(java.lang.String);
}

public final class io.github.arthurhoch.kissjson.EnumMode extends java.lang.Enum<io.github.arthurhoch.kissjson.EnumMode> {
  public static final io.github.arthurhoch.kissjson.EnumMode NAME;
  public static final io.github.arthurhoch.kissjson.EnumMode TO_STRING;
  public static io.github.arthurhoch.kissjson.EnumMode[] values();
  public static io.github.arthurhoch.kissjson.EnumMode valueOf(java.lang.String);
}

public final class io.github.arthurhoch.kissjson.FieldNaming extends java.lang.Enum<io.github.arthurhoch.kissjson.FieldNaming> {
  public static final io.github.arthurhoch.kissjson.FieldNaming IDENTITY;
  public static final io.github.arthurhoch.kissjson.FieldNaming LOWER_CASE;
  public static final io.github.arthurhoch.kissjson.FieldNaming UPPER_CASE;
  public static final io.github.arthurhoch.kissjson.FieldNaming CAMEL_CASE;
  public static final io.github.arthurhoch.kissjson.FieldNaming SNAKE_CASE;
  public static final io.github.arthurhoch.kissjson.FieldNaming KEBAB_CASE;
  public static io.github.arthurhoch.kissjson.FieldNaming[] values();
  public static io.github.arthurhoch.kissjson.FieldNaming valueOf(java.lang.String);
}

public final class io.github.arthurhoch.kissjson.Json {
  public static io.github.arthurhoch.kissjson.Json create();
  public static io.github.arthurhoch.kissjson.JsonBuilder builder();
  public io.github.arthurhoch.kissjson.JsonConfig config();
  public java.lang.String stringify(java.lang.Object);
  public <T> T parse(java.lang.String, java.lang.Class<T>);
  public <T> java.util.List<T> parseList(java.lang.String, java.lang.Class<T>);
  public java.util.Map<java.lang.String, java.lang.Object> parseMap(java.lang.String);
  public <T> java.util.Map<java.lang.String, T> parseMap(java.lang.String, java.lang.Class<T>);
}

public interface io.github.arthurhoch.kissjson.JsonAliases extends java.lang.annotation.Annotation {
  public abstract java.lang.String[] value();
}

public final class io.github.arthurhoch.kissjson.JsonBuilder {
  public io.github.arthurhoch.kissjson.JsonBuilder fieldNaming(io.github.arthurhoch.kissjson.FieldNaming);
  public io.github.arthurhoch.kissjson.JsonBuilder includeNulls(boolean);
  public io.github.arthurhoch.kissjson.JsonBuilder failOnUnknownProperties(boolean);
  public io.github.arthurhoch.kissjson.JsonBuilder failOnMissingRequiredFields(boolean);
  public io.github.arthurhoch.kissjson.JsonBuilder failOnNullForPrimitives(boolean);
  public io.github.arthurhoch.kissjson.JsonBuilder failOnDuplicateKeys(boolean);
  public io.github.arthurhoch.kissjson.JsonBuilder failOnCycles(boolean);
  public io.github.arthurhoch.kissjson.JsonBuilder maxDepth(int);
  public io.github.arthurhoch.kissjson.JsonBuilder prettyPrint(boolean);
  public io.github.arthurhoch.kissjson.JsonBuilder dateFormat(io.github.arthurhoch.kissjson.DateFormat);
  public io.github.arthurhoch.kissjson.JsonBuilder zoneId(java.time.ZoneId);
  public io.github.arthurhoch.kissjson.JsonBuilder enumMode(io.github.arthurhoch.kissjson.EnumMode);
  public io.github.arthurhoch.kissjson.Json build();
}

public final class io.github.arthurhoch.kissjson.JsonConfig {
  public io.github.arthurhoch.kissjson.FieldNaming fieldNaming();
  public boolean includeNulls();
  public boolean failOnUnknownProperties();
  public boolean failOnMissingRequiredFields();
  public boolean failOnNullForPrimitives();
  public boolean failOnDuplicateKeys();
  public boolean failOnCycles();
  public int maxDepth();
  public boolean prettyPrint();
  public io.github.arthurhoch.kissjson.DateFormat dateFormat();
  public java.time.ZoneId zoneId();
  public io.github.arthurhoch.kissjson.EnumMode enumMode();
}

public interface io.github.arthurhoch.kissjson.JsonDateFormat extends java.lang.annotation.Annotation {
  public abstract java.lang.String value();
}

public class io.github.arthurhoch.kissjson.JsonException extends java.lang.RuntimeException {
  public io.github.arthurhoch.kissjson.JsonException(java.lang.String);
  public io.github.arthurhoch.kissjson.JsonException(java.lang.String, java.lang.Throwable);
}

public interface io.github.arthurhoch.kissjson.JsonExcludeNull extends java.lang.annotation.Annotation {
}

public interface io.github.arthurhoch.kissjson.JsonIgnore extends java.lang.annotation.Annotation {
}

public interface io.github.arthurhoch.kissjson.JsonIncludeNull extends java.lang.annotation.Annotation {
}

public final class io.github.arthurhoch.kissjson.JsonMappingException extends io.github.arthurhoch.kissjson.JsonException {
  public io.github.arthurhoch.kissjson.JsonMappingException(java.lang.String, java.lang.String, java.lang.Class<?>, java.lang.String, java.lang.Class<?>, java.lang.Object);
  public io.github.arthurhoch.kissjson.JsonMappingException(java.lang.String, java.lang.String, java.lang.Class<?>, java.lang.String, java.lang.Class<?>, java.lang.Object, java.lang.Throwable);
  public java.lang.String jsonPath();
  public java.lang.Class<?> targetType();
  public java.lang.String fieldName();
  public java.lang.Class<?> expectedType();
  public java.lang.Object actualValue();
}

public interface io.github.arthurhoch.kissjson.JsonName extends java.lang.annotation.Annotation {
  public abstract java.lang.String value();
}

public final class io.github.arthurhoch.kissjson.JsonParseException extends io.github.arthurhoch.kissjson.JsonException {
  public io.github.arthurhoch.kissjson.JsonParseException(java.lang.String, int, int, int);
  public io.github.arthurhoch.kissjson.JsonParseException(java.lang.String, int, int, int, java.lang.Throwable);
  public int line();
  public int column();
  public int offset();
}

public interface io.github.arthurhoch.kissjson.JsonRequired extends java.lang.annotation.Annotation {
}

Local Verification Commands

Run these commands in the KissJson repository when changing examples, docs, or release skill files:

mvn -B clean verify
mvn -B javadoc:javadoc

Release Skill Maintenance

For a future release such as 0.2.0, create a new file at docs/skills/v0.2.0.md instead of editing or deleting this historical file. Update docs/skills/index.md with a view link and a raw download link for the new version.