Merge pull request #23 from aether-framework/feature/supporting-extra-ops

Deprecate legacy codec modules and add null validation handling

Author: Splatcrafter

CHANGELOG.md

@@ -8,8 +8,76 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [0.4.0] - 2026-01-09
 
+### Breaking Changes
+
+#### Package Restructuring in `aether-datafixers-codec`
+
+The codec module has been restructured to use a format-first package organization. This is a **breaking change** that requires updating import statements.
+
+**Old Package Structure:**
+```
+de.splatgames.aether.datafixers.codec.gson.GsonOps
+de.splatgames.aether.datafixers.codec.jackson.JacksonOps
+```
+
+**New Package Structure:**
+```
+de.splatgames.aether.datafixers.codec.json.gson.GsonOps
+de.splatgames.aether.datafixers.codec.json.jackson.JacksonJsonOps
+de.splatgames.aether.datafixers.codec.yaml.snakeyaml.SnakeYamlOps
+de.splatgames.aether.datafixers.codec.yaml.jackson.JacksonYamlOps
+de.splatgames.aether.datafixers.codec.toml.jackson.JacksonTomlOps
+de.splatgames.aether.datafixers.codec.xml.jackson.JacksonXmlOps
+```
+
+**Migration Steps:**
+1. Update imports from `codec.gson.GsonOps` to `codec.json.gson.GsonOps`
+2. Update imports from `codec.jackson.JacksonOps` to `codec.json.jackson.JacksonJsonOps`
+3. Rename `JacksonOps` references to `JacksonJsonOps`
+
 ### Added
 
+#### Multi-Format DynamicOps Implementations (`aether-datafixers-codec`)
+
+New DynamicOps implementations for YAML, TOML, and XML formats:
+
+**YAML Support:**
+- `SnakeYamlOps` — Uses native Java types (`Map`, `List`, primitives) via SnakeYAML 2.x
+- `JacksonYamlOps` — Uses `JsonNode` via Jackson YAML dataformat module
+
+**TOML Support:**
+- `JacksonTomlOps` — Uses `JsonNode` via Jackson TOML dataformat module
+- Note: TOML requires top-level tables and doesn't support null values
+
+**XML Support:**
+- `JacksonXmlOps` — Uses `JsonNode` via Jackson XML dataformat module
+- Note: XML requires a root element and has different structural semantics
+
+**New Dependencies (all optional):**
+```xml
+<dependency>
+    <groupId>org.yaml</groupId>
+    <artifactId>snakeyaml</artifactId>
+    <version>2.2</version>
+    <optional>true</optional>
+</dependency>
+<dependency>
+    <groupId>com.fasterxml.jackson.dataformat</groupId>
+    <artifactId>jackson-dataformat-yaml</artifactId>
+    <optional>true</optional>
+</dependency>
+<dependency>
+    <groupId>com.fasterxml.jackson.dataformat</groupId>
+    <artifactId>jackson-dataformat-toml</artifactId>
+    <optional>true</optional>
+</dependency>
+<dependency>
+    <groupId>com.fasterxml.jackson.dataformat</groupId>
+    <artifactId>jackson-dataformat-xml</artifactId>
+    <optional>true</optional>
+</dependency>
+```
+
 #### Spring Boot Starter Module (`aether-datafixers-spring-boot-starter`)
 
 New module providing seamless Spring Boot integration with auto-configuration, fluent migration API, and observability features.
@@ -26,7 +94,13 @@ New module providing seamless Spring Boot integration with auto-configuration, f
 **Configuration Properties (`spring.config`):**
 - `AetherDataFixersProperties` — Root configuration with `aether.datafixers.*` prefix
 - `DataFixerDomainProperties` — Per-domain configuration (version, primary, description)
-- `DynamicOpsFormat` — Enum for selecting default serialization format (GSON, JACKSON)
+- `DynamicOpsFormat` — Enum for selecting default serialization format:
+  - `GSON` — JSON via Google Gson
+  - `JACKSON` — JSON via Jackson Databind
+  - `JACKSON_YAML` — YAML via Jackson dataformat
+  - `SNAKEYAML` — YAML via SnakeYAML (native Java types)
+  - `JACKSON_TOML` — TOML via Jackson dataformat
+  - `JACKSON_XML` — XML via Jackson dataformat
 - `ActuatorProperties` — Control schema/fix detail exposure in actuator responses
 - `MetricsProperties` — Configure timing, counting, and domain tag name
 
@@ -67,6 +141,19 @@ New module providing seamless Spring Boot integration with auto-configuration, f
 
 ### Documentation
 
+#### Codec Formats Documentation
+- Added new `docs/codec/` section with comprehensive format documentation
+- [Codec Overview](docs/codec/index.md) — Format comparison, package structure, dependency guide
+- [JSON Support](docs/codec/json.md) — GsonOps and JacksonJsonOps usage, examples, comparison
+- [YAML Support](docs/codec/yaml.md) — SnakeYamlOps and JacksonYamlOps usage, examples, comparison
+- [TOML Support](docs/codec/toml.md) — JacksonTomlOps usage, configuration file examples
+- [XML Support](docs/codec/xml.md) — JacksonXmlOps usage, XML-to-JsonNode mapping
+- Updated [Dynamic System](docs/concepts/dynamic-system.md) with all DynamicOps implementations table
+- Updated [Codec System](docs/concepts/codec-system.md) with links to format-specific docs
+- Updated [How-To Index](docs/how-to/index.md) with Format Integration section
+- Updated [Custom DynamicOps Tutorial](docs/tutorials/custom-dynamicops.md) with built-in implementations reference
+
+#### Spring Boot Integration Documentation
 - Added comprehensive Spring Boot Integration documentation
 - Quick Start Guide with complete code examples
 - Configuration Reference for all `aether.datafixers.*` properties

README.md

@@ -10,11 +10,12 @@ inspired by Minecraft's DataFixer Upper (DFU), with a focus on **simplicity**, *
 
 ---
 
-## ✨ Features (v0.3.0)
+## ✨ Features (v0.4.0)
 
 - ✅ **Schema-Based Versioning** — Define data types per version with `Schema` and `TypeRegistry`
 - ✅ **Forward Patching** — Apply `DataFix` instances sequentially to migrate data across versions
 - ✅ **Format-Agnostic** — Work with any serialization format via `Dynamic<T>` and `DynamicOps<T>`
+- ✅ **Multi-Format Support** — JSON (Gson, Jackson), YAML (SnakeYAML, Jackson), TOML, and XML
 - ✅ **Codec System** — Bidirectional transformation between typed Java objects and dynamic representations
 - ✅ **Type Safety** — Strong typing with `TypeReference` identifiers for data routing
 - ✅ **Testkit** — Fluent test data builders, custom assertions, and test harnesses for DataFix testing
@@ -32,7 +33,7 @@ inspired by Minecraft's DataFixer Upper (DFU), with a focus on **simplicity**, *
 
 - **aether-datafixers-api** — Core interfaces and API contracts (no implementation logic)
 - **aether-datafixers-core** — Default implementations of the API interfaces
-- **aether-datafixers-codec** — Codec implementations for serialization formats
+- **aether-datafixers-codec** — Multi-format codec implementations (JSON, YAML, TOML, XML)
 - **aether-datafixers-testkit** — Testing utilities for DataFix, Schema, and migration testing
 - **aether-datafixers-cli** — Command-line interface for data migration and validation
 - **aether-datafixers-schema-tools** — Schema analysis, validation, diffing, and introspection
@@ -421,7 +422,7 @@ public class GameService {
 aether:
   datafixers:
     enabled: true                    # Enable/disable auto-config
-    default-format: gson             # gson | jackson
+    default-format: gson             # gson | jackson | jackson_yaml | snakeyaml | jackson_toml | jackson_xml
     default-current-version: 200     # Fallback version
     domains:
       game:
@@ -555,19 +556,19 @@ mvn test
   - **High-performance APIs** — `Rules.batch()` and single-pass conditional transforms
   - **Performance optimizations** — Path caching, optimized fix registry, reduced allocations
 
-- **v0.3.0** (current)
+- **v0.3.0**
   - **CLI module** — Migrate files from the command line with batch processing and reports
   - **Schema Tools module** — Schema diffing, migration analysis, validation, and introspection
   - **Fix coverage analysis** — Detect schema changes without corresponding DataFixes
   - **Convention checking** — Enforce naming conventions for types, fields, and classes
 
-- **v0.4.0** (next)
+- **v0.4.0** (current)
   - **Spring Boot Starter** — Auto-configuration, MigrationService with fluent API
   - **Actuator integration** — Health indicator, info contributor, custom endpoint, Micrometer metrics
   - **Multi-domain support** — Multiple DataFixers with @Qualifier annotations
-  - **DynamicOps auto-configuration** — Conditional GsonOps/JacksonOps beans
-  - **Extra ops modules** — Optional YAML/TOML support (format adapters)
-  - **Debug utilities** — Pretty printers / tree diff for Dynamic structures (dev-facing)
+  - **DynamicOps auto-configuration** — Conditional beans for all supported formats
+  - **Multi-format DynamicOps** — YAML (SnakeYAML, Jackson), TOML (Jackson), XML (Jackson)
+  - **Package restructuring** — Format-first package organization (`codec.json.gson`, `codec.yaml.jackson`, etc.)
 
 - **v0.5.0** (API freeze candidate)
   - **API stabilization pass** — Naming/packaging cleanup + deprecations completed

aether-datafixers-cli/src/main/java/de/splatgames/aether/datafixers/cli/AetherCli.java

@@ -53,7 +53,7 @@
  * aether-cli info --bootstrap com.example.MyBootstrap
  * }</pre>
  *
- * @author Erik Pfoertner
+ * @author Erik Pförtner
  * @since 0.3.0
  */
 @Command(

aether-datafixers-cli/src/main/java/de/splatgames/aether/datafixers/cli/bootstrap/BootstrapLoadException.java

@@ -26,7 +26,7 @@
  * Exception thrown when loading a {@link de.splatgames.aether.datafixers.api.bootstrap.DataFixerBootstrap}
  * implementation fails.
  *
- * @author Erik Pfoertner
+ * @author Erik Pförtner
  * @since 0.3.0
  */
 public class BootstrapLoadException extends RuntimeException {

aether-datafixers-cli/src/main/java/de/splatgames/aether/datafixers/cli/bootstrap/BootstrapLoader.java

@@ -61,7 +61,7 @@
  * }
  * }</pre>
  *
- * @author Erik Pfoertner
+ * @author Erik Pförtner
  * @see DataFixerBootstrap
  * @see BootstrapLoadException
  * @see java.util.ServiceLoader

aether-datafixers-cli/src/main/java/de/splatgames/aether/datafixers/cli/command/InfoCommand.java

@@ -58,7 +58,7 @@
  *   <li>{@code 1} - Error loading bootstrap or missing required option</li>
  * </ul>
  *
- * @author Erik Pfoertner
+ * @author Erik Pförtner
  * @see de.splatgames.aether.datafixers.cli.AetherCli
  * @see de.splatgames.aether.datafixers.cli.format.FormatRegistry
  * @since 0.3.0

aether-datafixers-cli/src/main/java/de/splatgames/aether/datafixers/cli/command/MigrateCommand.java

@@ -86,7 +86,7 @@
  *   <li><b>Output file specified:</b> Result is written to the specified file or directory</li>
  * </ul>
  *
- * @author Erik Pfoertner
+ * @author Erik Pförtner
  * @see de.splatgames.aether.datafixers.cli.AetherCli
  * @see ValidateCommand
  * @since 0.3.0

aether-datafixers-cli/src/main/java/de/splatgames/aether/datafixers/cli/command/ValidateCommand.java

@@ -73,7 +73,7 @@
  *   <li>{@code ERROR: filename - message} - File could not be validated</li>
  * </ul>
  *
- * @author Erik Pfoertner
+ * @author Erik Pförtner
  * @see de.splatgames.aether.datafixers.cli.AetherCli
  * @see MigrateCommand
  * @since 0.3.0

aether-datafixers-cli/src/main/java/de/splatgames/aether/datafixers/cli/format/FormatHandler.java

@@ -67,7 +67,7 @@
  * <p>Register in {@code META-INF/services/de.splatgames.aether.datafixers.cli.format.FormatHandler}</p>
  *
  * @param <T> the underlying data representation type
- * @author Erik Pfoertner
+ * @author Erik Pförtner
  * @since 0.3.0
  */
 public interface FormatHandler<T> {

aether-datafixers-cli/src/main/java/de/splatgames/aether/datafixers/cli/format/FormatParseException.java

@@ -25,7 +25,7 @@
 /**
  * Exception thrown when parsing input data fails.
  *
- * @author Erik Pfoertner
+ * @author Erik Pförtner
  * @since 0.3.0
  */
 public class FormatParseException extends RuntimeException {