---
layout: default
title: KissJson AI Skill
library: kiss-json
skill_version: 0.1.0
release_version: 0.1.0
maven: io.github.arthurhoch:kiss-json:0.1.0
java: "17+"
format: markdown
---

# 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 <code>-SNAPSHOT</code>, consumer documentation should still use <code>0.1.0</code> 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

~~~xml
<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 <code>io.github.arthurhoch.kissjson</code>.
- 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

~~~java
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

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

### Annotated DTO

~~~java
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 <code>javap -public</code>. It includes public constructors, constants, enum methods, record accessors, inherited Object overrides when public, and public nested classes.

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

~~~text
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:

~~~bash
mvn -B clean verify
mvn -B javadoc:javadoc
~~~

## Release Skill Maintenance

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