Readme cleanup

CONTRIBUTING.md

@@ -9,7 +9,7 @@ This project uses [Gradle](https://gradle.org) for dependency management and bui
 ```bash
 # Clone the repository
 git clone https://github.com/toon-format/toon-java.git
-cd JToon
+cd toon-java
 
 # Build the project
 ./gradlew build

README.md

@@ -11,7 +11,7 @@
 
 Compact, human-readable serialization format for LLM contexts with **30-60% token reduction** vs JSON. Combines YAML-like indentation with CSV-like tabular arrays. Working towards full compatibility with the [official TOON specification](https://github.com/toon-format/spec).
 
-**Key Features:** Minimal syntax • TOON Encoding and Decoding • Tabular arrays for uniform data • Array length validation • Java 17 • Comprehensive test coverage.
+**Key Features:** Minimal syntax • TOON Encoding and Decoding • Tabular arrays for uniform data • Array length validation • Java 17 • full [Jackson Annotation](https://github.com/FasterXML/jackson-annotations) Support • Comprehensive test coverage.
 
 ## Installation
 
@@ -68,7 +68,7 @@ System.out.println(JToon.encode(data));
 
 **Output:**
 
-```
+```yaml
 user:
   id: 123
   name: Ada
@@ -118,6 +118,8 @@ Converts any Java object or JSON-string to TOON format.
   - `indent` – Number of spaces per indentation level (default: `2`)
   - `delimiter` – Delimiter enum for array values and tabular rows: `Delimiter.COMMA` (default), `Delimiter.TAB`, or `Delimiter.PIPE`
   - `lengthMarker` – Boolean to prefix array lengths with `#` (default: `false`)
+  - `flatten` – Boolean to key folding to collapse single-key wrapper chains (default: `OFF`).
+  - `flattenDepth` – maximum number of segments to fold  (default: `Infinity`)
 
 For `encodeJson` overloads:
 
@@ -131,26 +133,29 @@ A TOON-formatted string with no trailing newline or spaces.
 
 ```java
 import dev.toonformat.jtoon.JToon;
+import com.fasterxml.jackson.annotation.JsonIgnore;
 import java.util.*;
 
-record Item(String sku, int qty, double price) {}
+record Item(String sku, int qty, double price,  @JsonIgnore double internPrice) {}
 record Data(List<Item> items) {}
 
-Item item1 = new Item("A1", 2, 9.99);
-Item item2 = new Item("B2", 1, 14.5);
+Item item1 = new Item("A1", 2, 9.99, 8.50);
+Item item2 = new Item("B2", 1, 14.5, 14.0);
 Data data = new Data(List.of(item1, item2));
 
 System.out.println(JToon.encode(data));
 ```
 
 **Output:**
 
-```
+```yaml
 items[2]{sku,qty,price}:
   A1,2,9.99
   B2,1,14.5
 ```
 
+The [Jackson Annotation](https://github.com/FasterXML/jackson-annotations) @JsonIgnore will help to keep fields from exposing.
+
 #### Encode a plain JSON string
 
 ```java
@@ -168,7 +173,7 @@ System.out.println(JToon.encodeJson(json));
 
 Output:
 
-```
+```yaml
 user:
   id: 123
   name: Ada
@@ -195,13 +200,13 @@ Item item1 = new Item("A1", "Widget", 2, 9.99);
 Item item2 = new Item("B2", "Gadget", 1, 14.5);
 Data data = new Data(List.of(item1, item2));
 
-EncodeOptions options = new EncodeOptions(2, Delimiter.TAB, false);
+EncodeOptions options = new EncodeOptions(2, Delimiter.TAB, false, KeyFolding.OFF, 3);
 System.out.println(JToon.encode(data, options));
 ```
 
 **Output:**
 
-```
+```yaml
 items[2 ]{sku name qty price}:
   A1 Widget 2 9.99
   B2 Gadget 1 14.5
@@ -224,13 +229,13 @@ Pipe delimiters offer a middle ground between commas and tabs:
 
 ```java
 // Using the same Item and Data records from above
-EncodeOptions options = new EncodeOptions(2, Delimiter.PIPE, false);
+EncodeOptions options = new EncodeOptions(2, Delimiter.PIPE, false, KeyFolding.OFF, 3);
 System.out.println(JToon.encode(data, options));
 ```
 
 **Output:**
 
-```
+```yaml
 items[2|]{sku|name|qty|price}:
   A1|Widget|2|9.99
   B2|Gadget|1|14.5
@@ -252,14 +257,14 @@ Item item1 = new Item("A1", 2, 9.99);
 Item item2 = new Item("B2", 1, 14.5);
 Data data = new Data(List.of("reading", "gaming", "coding"), List.of(item1, item2));
 
-System.out.println(JToon.encode(data, new EncodeOptions(2, Delimiter.COMMA, true)));
+System.out.println(JToon.encode(data, new EncodeOptions(2, Delimiter.COMMA, true, KeyFolding.OFF, 3)));
 // tags[#3]: reading,gaming,coding
 // items[#2]{sku,qty,price}:
 //   A1,2,9.99
 //   B2,1,14.5
 
 // Works with custom delimiters
-System.out.println(JToon.encode(data, new EncodeOptions(2, Delimiter.PIPE, true)));
+System.out.println(JToon.encode(data, new EncodeOptions(2, Delimiter.PIPE, true, KeyFolding.OFF, 3)));
 // tags[#3|]: reading|gaming|coding
 // items[#2|]{sku|qty|price}:
 //   A1|2|9.99
@@ -283,6 +288,7 @@ Converts TOON-formatted strings back to Java objects or JSON.
   - `indent` – Number of spaces per indentation level (default: `2`)
   - `delimiter` – Expected delimiter: `Delimiter.COMMA` (default), `Delimiter.TAB`, or `Delimiter.PIPE`
   - `strict` – Boolean for validation mode. When `true` (default), throws `IllegalArgumentException` on invalid input. When `false`, returns `null` on errors.
+  - `expandPaths` – Boolean Path expansion mode for dotted keys (default: `OFF`).
 
 **Returns:**
 

src/main/java/dev/toonformat/jtoon/EncodeOptions.java

@@ -9,27 +9,27 @@
  * @param lengthMarker Optional marker to prefix array lengths in headers. When
  *                     true, arrays render as [#N] instead of [N] (default:
  *                     false)
- * @param flatten      Optional flag to flatten nested objects to a single level.
- *                     (default: false)
+ * @param flatten      Key folding mode n nested objects to a single level.
+ *                     (default: OFF)
  * @param flattenDepth Optional maximum depth to flatten nested objects.
  *                     (default: Integer.MAX_VALUE)
  */
 public record EncodeOptions(
         int indent,
         Delimiter delimiter,
         boolean lengthMarker,
-        boolean flatten,
+        KeyFolding flatten,
         int flattenDepth) {
     /**
      * Default encoding options: 2 spaces indent, comma delimiter, no length marker
      */
-    public static final EncodeOptions DEFAULT = new EncodeOptions(2, Delimiter.COMMA, false, false, Integer.MAX_VALUE);
+    public static final EncodeOptions DEFAULT = new EncodeOptions(2, Delimiter.COMMA, false, KeyFolding.OFF, Integer.MAX_VALUE);
 
     /**
      * Creates EncodeOptions with default values.
      */
     public EncodeOptions() {
-        this(2, Delimiter.COMMA, false, false, Integer.MAX_VALUE);
+        this(2, Delimiter.COMMA, false, KeyFolding.OFF, Integer.MAX_VALUE);
     }
 
     /**
@@ -40,7 +40,7 @@ public EncodeOptions() {
      * @return a new EncodeOptions instance with the specified indent
      */
     public static EncodeOptions withIndent(int indent) {
-        return new EncodeOptions(indent, Delimiter.COMMA, false, false, Integer.MAX_VALUE);
+        return new EncodeOptions(indent, Delimiter.COMMA, false, KeyFolding.OFF, Integer.MAX_VALUE);
     }
 
     /**
@@ -51,7 +51,7 @@ public static EncodeOptions withIndent(int indent) {
      * @return a new EncodeOptions instance with the specified delimiter
      */
     public static EncodeOptions withDelimiter(Delimiter delimiter) {
-        return new EncodeOptions(2, delimiter, false, false, Integer.MAX_VALUE);
+        return new EncodeOptions(2, delimiter, false, KeyFolding.OFF, Integer.MAX_VALUE);
     }
 
     /**
@@ -62,7 +62,7 @@ public static EncodeOptions withDelimiter(Delimiter delimiter) {
      * @return a new EncodeOptions instance with the specified length marker setting
      */
     public static EncodeOptions withLengthMarker(boolean lengthMarker) {
-        return new EncodeOptions(2, Delimiter.COMMA, lengthMarker, false, Integer.MAX_VALUE);
+        return new EncodeOptions(2, Delimiter.COMMA, lengthMarker, KeyFolding.OFF, Integer.MAX_VALUE);
     }
 
     /**
@@ -73,7 +73,7 @@ public static EncodeOptions withLengthMarker(boolean lengthMarker) {
      * @return a new EncodeOptions instance with the flatten setting
      */
     public static EncodeOptions withFlatten(boolean flatten) {
-        return new EncodeOptions(2, Delimiter.COMMA, false, flatten, Integer.MAX_VALUE);
+        return new EncodeOptions(2, Delimiter.COMMA, false, flatten ? KeyFolding.SAFE : KeyFolding.OFF, Integer.MAX_VALUE);
     }
 
     /**
@@ -84,6 +84,6 @@ public static EncodeOptions withFlatten(boolean flatten) {
      * @return a new EncodeOptions instance with the flatten setting and the depth of to flatten the nested objects.
      */
     public static EncodeOptions withFlattenDepth(int flattenDepth) {
-        return new EncodeOptions(2, Delimiter.COMMA, false, true, flattenDepth);
+        return new EncodeOptions(2, Delimiter.COMMA, false, KeyFolding.SAFE, flattenDepth);
     }
 }

src/main/java/dev/toonformat/jtoon/KeyFolding.java

@@ -0,0 +1,19 @@
+package dev.toonformat.jtoon;
+
+/**
+ * Enable key folding to collapse single-key wrapper chains.
+ */
+public enum KeyFolding {
+    /**
+     * Safe mode:
+     * When set to 'safe', nested objects with single keys are collapsed into dotted paths.
+     * (e.g., data.metadata.items instead of nested indentation).
+     */
+    SAFE,
+
+    /**
+     * Off mode: default
+     */
+    OFF
+}
+

src/main/java/dev/toonformat/jtoon/encoder/ObjectEncoder.java

@@ -1,6 +1,7 @@
 package dev.toonformat.jtoon.encoder;
 
 import dev.toonformat.jtoon.EncodeOptions;
+import dev.toonformat.jtoon.KeyFolding;
 import tools.jackson.databind.JsonNode;
 import tools.jackson.databind.node.ArrayNode;
 import tools.jackson.databind.node.ObjectNode;
@@ -93,7 +94,7 @@ public static void encodeKeyValuePair(String key,
         int remainingDepth = effectiveFlattenDepth - depth;
 
         // Attempt key folding when enabled
-        if (options.flatten()
+        if (KeyFolding.SAFE.equals(options.flatten())
             && !siblings.isEmpty()
             && remainingDepth > 0
             && blockedKeys != null
@@ -162,7 +163,7 @@ private static EncodeOptions flatten(String key, Flatten.FoldResult foldResult,
                 // Pass "-1" if remainingDepth is exhausted and set the encoding in the option to false.
                 // to encode normally without flattening
                 newRemainingDepth = -1;
-                options = new EncodeOptions(options.indent(), options.delimiter(), options.lengthMarker(), false, options.flattenDepth());
+                options = new EncodeOptions(options.indent(), options.delimiter(), options.lengthMarker(), KeyFolding.OFF, options.flattenDepth());
             }
 
             encodeObject((ObjectNode) remainder, writer, depth + 1, options, rootLiteralKeys, foldedPath, newRemainingDepth, blockedKeys);
@@ -178,10 +179,10 @@ private static void handleFullyFoldedLeaf(Flatten.FoldResult foldResult, LineWri
         // Primitive
         if (leaf.isValueNode()) {
             writer.push(depth,
-                        indentedLine(depth,
-                                     encodedFoldedKey + ": " +
-                                         PrimitiveEncoder.encodePrimitive(leaf, options.delimiter().toString()),
-                                     options.indent()));
+                indentedLine(depth,
+                    encodedFoldedKey + ": " +
+                        PrimitiveEncoder.encodePrimitive(leaf, options.delimiter().toString()),
+                    options.indent()));
             return;
         }
 
@@ -196,7 +197,7 @@ private static void handleFullyFoldedLeaf(Flatten.FoldResult foldResult, LineWri
             writer.push(depth, indentedLine(depth, encodedFoldedKey + ":", options.indent()));
             if (!leaf.isEmpty()) {
                 encodeObject((ObjectNode) leaf, writer, depth + 1, options,
-                             null, null, null, null);
+                    null, null, null, null);
             }
         }
     }

src/test/java/dev/toonformat/jtoon/EncodeOptionsTest.java

@@ -17,7 +17,7 @@ void givenDefaultConstructor_whenCreateInstance_thenUsesDefaultValues() {
         assertEquals(2, opts.indent());
         assertEquals(Delimiter.COMMA, opts.delimiter());
         assertFalse(opts.lengthMarker());
-        assertFalse(opts.flatten());
+        assertEquals(KeyFolding.OFF, opts.flatten());
         assertEquals(Integer.MAX_VALUE, opts.flattenDepth());
     }
 
@@ -33,7 +33,7 @@ void givenDefaultStaticInstance_whenAccess_thenValuesMatchDefaultConstructor() {
         assertEquals(2, opts.indent());
         assertEquals(Delimiter.COMMA, opts.delimiter());
         assertFalse(opts.lengthMarker());
-        assertFalse(opts.flatten());
+        assertEquals(KeyFolding.OFF, opts.flatten());
         assertEquals(Integer.MAX_VALUE, opts.flattenDepth());
     }
 
@@ -49,7 +49,7 @@ void givenCustomIndent_whenUsingWithIndent_thenOnlyIndentIsModified() {
         assertEquals(4, opts.indent());
         assertEquals(Delimiter.COMMA, opts.delimiter());
         assertFalse(opts.lengthMarker());
-        assertFalse(opts.flatten());
+        assertEquals(KeyFolding.OFF, opts.flatten());
         assertEquals(Integer.MAX_VALUE, opts.flattenDepth());
     }
 
@@ -65,7 +65,7 @@ void givenCustomDelimiter_whenUsingWithDelimiter_thenOnlyDelimiterIsModified() {
         assertEquals(2, opts.indent());
         assertEquals(Delimiter.TAB, opts.delimiter());
         assertFalse(opts.lengthMarker());
-        assertFalse(opts.flatten());
+        assertEquals(KeyFolding.OFF, opts.flatten());
         assertEquals(Integer.MAX_VALUE, opts.flattenDepth());
     }
 
@@ -81,7 +81,7 @@ void givenLengthMarkerFlag_whenUsingWithLengthMarker_thenOnlyLengthMarkerIsModif
         assertEquals(2, opts.indent());
         assertEquals(Delimiter.COMMA, opts.delimiter());
         assertTrue(opts.lengthMarker());
-        assertFalse(opts.flatten());
+        assertEquals(KeyFolding.OFF, opts.flatten());
         assertEquals(Integer.MAX_VALUE, opts.flattenDepth());
     }
 
@@ -97,7 +97,7 @@ void givenFlattenFlag_whenUsingWithFlatten_thenOnlyFlattenIsModified() {
         assertEquals(2, opts.indent());
         assertEquals(Delimiter.COMMA, opts.delimiter());
         assertFalse(opts.lengthMarker());
-        assertTrue(opts.flatten());
+        assertEquals(KeyFolding.SAFE, opts.flatten());
         assertEquals(Integer.MAX_VALUE, opts.flattenDepth());
     }
 
@@ -113,7 +113,7 @@ void givenFlattenDepth_whenUsingWithFlattenDepth_thenFlattenDepthIsSetAndFlatten
         assertEquals(2, opts.indent());
         assertEquals(Delimiter.COMMA, opts.delimiter());
         assertFalse(opts.lengthMarker());
-        assertTrue(opts.flatten());
+        assertEquals(KeyFolding.SAFE, opts.flatten());
         assertEquals(3, opts.flattenDepth());
     }
-}
+}

src/test/java/dev/toonformat/jtoon/JToonJsonStringTest.java

@@ -63,7 +63,7 @@ void encodesMixedArray() {
         @DisplayName("supports custom options with pipe delimiter and length marker")
         void encodesWithCustomOptions() {
             String json = "{\"tags\":[\"reading\",\"gaming\",\"coding\"],\"items\":[{\"sku\":\"A1\",\"qty\":2,\"price\":9.99},{\"sku\":\"B2\",\"qty\":1,\"price\":14.5}]}";
-            EncodeOptions options = new EncodeOptions(2, Delimiter.PIPE, true, false, Integer.MAX_VALUE);
+            EncodeOptions options = new EncodeOptions(2, Delimiter.PIPE, true, KeyFolding.OFF, Integer.MAX_VALUE);
             String result = JToon.encodeJson(json, options);
 
             String expected = String.join("\n",