Aether Datafixers Documentation

Welcome to the official documentation for Aether Datafixers, a lightweight data migration framework for the JVM.

What is Aether Datafixers?

Aether Datafixers is a framework for migrating serialized data through schema versions using forward patching. Inspired by Minecraft's DataFixer Upper (DFU), it provides a simpler and more approachable API while maintaining the power and flexibility needed for complex data migrations.

Key Features

• 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>
• Codec System - Bidirectional transformation between typed Java objects and dynamic representations
• Profunctor Optics - Composable, type-safe accessors for nested data (Lens, Prism, Finder)
• Type Safety - Strong typing with TypeReference identifiers for data routing
• Migration Diagnostics - Opt-in structured reports with timing, rules, and snapshots
• JDK 17+ - Built and tested on modern LTS JVMs

---

Quick Navigation

Getting Started

New to Aether Datafixers? Start here:

• Installation - Add the framework to your project
• Quick Start - Get up and running in 5 minutes
• Your First Migration - Complete tutorial for beginners

Core Concepts

Understand the fundamental concepts:

• Architecture Overview - How the framework fits together
• DataVersion - Version identifiers for data schemas
• TypeReference - Type identifiers for data routing
• Schema System - Defining data structures per version
• DataFix System - Creating and applying migrations
• Dynamic System - Format-agnostic data manipulation
• Codec System - Encoding and decoding typed data
• Optics - Composable data accessors

Tutorials

Step-by-step learning guides:

• Basic Migration - Your first complete migration
• Multi-Version Migration - Chaining migrations
• Using Codecs - Building custom codecs
• RecordCodecBuilder - Composing record codecs
• Nested Transformations - Restructuring data

How-To Guides

Practical task-oriented guides:

• Rename a Field
• Add a New Field
• Remove a Field
• Transform Field Values
• Restructure Data
• Debug Migrations
• Use Diagnostics
• View all How-To Guides

Codec Formats

DynamicOps implementations for various data formats:

• Codec Overview - Introduction to DynamicOps implementations
• JSON Support - GsonOps and JacksonJsonOps
• YAML Support - SnakeYamlOps and JacksonYamlOps
• TOML Support - JacksonTomlOps
• XML Support - JacksonXmlOps

Examples

Working code examples:

• Game Data Example - Complete game save migration
• User Profile Example - User data migration
• Configuration Example - Config file versioning

Testing

Test your DataFixes and migrations with the Testkit module:

• Testkit Overview - Introduction to the testing utilities
• Test Data Builders - Fluent API for creating test data
• Custom Assertions - AssertJ assertions for Dynamic, DataResult, Typed
• DataFixTester - Test harness for isolated DataFix testing
• QuickFix Factories - Factory methods for common fix patterns
• Mock Schemas - Mock schema utilities

Command-Line Interface

Migrate and validate data files from the command line:

• CLI Overview - Introduction to the CLI tool
• Installation - Building and running the CLI
• Command Reference - Detailed command documentation
• Format Handlers - Custom format handler development
• Examples - Practical usage examples

Schema Tools

Analyze, compare, and validate your schemas:

• Schema Tools Overview - Introduction to schema tooling
• Schema Diffing - Compare schemas and detect changes
• Migration Analysis - Analyze migration paths and fix coverage
• Schema Validation - Validate structure and conventions
• Type Introspection - Inspect type structures

Advanced Topics

For experienced users:

• Traversal Strategies
• Custom Optics
• Performance Optimization - Benchmark results, format comparison, and tuning
• Extending the Framework

Security

Guidance for processing untrusted data safely:

• Security Overview - Introduction to security considerations
• Threat Model - Attack vectors and trust boundaries
• Format Security - Per-format security guidance
• Best Practices - Secure configuration patterns
• Secure Configuration Examples - Ready-to-use examples

Spring Boot Integration

Seamlessly integrate Aether Datafixers into Spring Boot applications:

• Spring Boot Overview - Introduction to the Spring Boot starter
• Quick Start - Add the starter and run your first migration
• Configuration Reference - All configuration properties
• MigrationService API - Fluent migration API
• Multi-Domain Setup - Managing multiple DataFixer instances
• Actuator Integration - Health indicators and endpoints
• Metrics Integration - Micrometer metrics for observability

Support

• Troubleshooting
• Migration Guide
• Common Errors
• FAQ
• Glossary

---

Modules

Module	Description
aether-datafixers-api	Core interfaces and API contracts (stable)
aether-datafixers-core	Default implementations
aether-datafixers-codec	DynamicOps for JSON, YAML, TOML, XML (Gson, Jackson, SnakeYAML)
aether-datafixers-spring-boot-starter	Spring Boot auto-configuration, MigrationService, Actuator, Metrics
aether-datafixers-cli	Command-line interface for data migration
aether-datafixers-testkit	Testing utilities for DataFix, Schema, and migration testing
aether-datafixers-schema-tools	Schema analysis, validation, and diffing utilities
aether-datafixers-examples	Practical usage examples
aether-datafixers-functional-tests	End-to-end and integration tests
aether-datafixers-bom	Bill of Materials for version management

---

Quick Example

// 1. Define type references
public static final TypeReference PLAYER = new TypeReference("player");

// 2. Create schemas for each version
public class Schema100 extends Schema {
    @Override
    protected void registerTypes() {
        registerType(PLAYER, DSL.and(
            DSL.field("playerName", DSL.string()),
            DSL.field("xp", DSL.intType())
        ));
    }
}

// 3. Create fixes for migrations
public class RenamePlayerNameFix extends SchemaDataFix {
    @Override
    protected TypeRewriteRule makeRule(Schema input, Schema output) {
        return Rules.renameField("playerName", "name");
    }
}

// 4. Bootstrap and create the fixer
AetherDataFixer fixer = new DataFixerRuntimeFactory()
    .create(CURRENT_VERSION, new MyBootstrap());

// 5. Migrate data
TaggedDynamic updated = fixer.update(
    oldData,
    new DataVersion(100),
    fixer.currentVersion()
);

---

Requirements

• Java 17 or later
• No required runtime dependencies (Gson/Jackson are optional)

License

MIT © Splatgames.de Software and Contributors