Add Schema Tools documentation covering installation, diffing, validation, analysis, and type introspection. Update glossary and installation guide.

Author: Splatcrafter

CHANGELOG.md

@@ -6,10 +6,51 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ---
 
-## [0.3.0] - 2026-01-07
+## [0.3.0] - 2026-01-08
 
 ### Added
 
+#### Schema Tools Module (`aether-datafixers-schema-tools`)
+
+New module for schema analysis, validation, and migration coverage checking.
+
+**Schema Diffing (`schematools.diff`):**
+- `SchemaDiffer` — Fluent API for comparing two schemas
+- `SchemaDiff` — Immutable result with added/removed/common types
+- `TypeDiff` — Field-level changes for types present in both schemas
+- `FieldDiff` — Individual field change (ADDED, REMOVED, MODIFIED, UNCHANGED)
+- `DiffKind` — Enumeration of change types
+- Optional field-level diffing via `includeFieldLevel(true)`
+- Type filtering via `ignoreTypes(...)`
+
+**Migration Analysis (`schematools.analysis`):**
+- `MigrationAnalyzer` — Fluent API for analyzing migration paths
+- `MigrationPath` — Complete migration sequence with all steps
+- `MigrationStep` — Single version transition with optional DataFix and SchemaDiff
+- `FixCoverage` — Analysis result showing fix coverage for schema changes
+- `CoverageGap` — Represents a schema change without corresponding DataFix
+- Coverage gap reasons: TYPE_ADDED, TYPE_REMOVED, TYPE_MODIFIED, FIELD_ADDED, FIELD_REMOVED, FIELD_TYPE_CHANGED
+- Orphan fix detection (fixes without schema changes)
+
+**Schema Validation (`schematools.validation`):**
+- `SchemaValidator` — Fluent API for validating schemas
+- `ValidationResult` — Immutable collection of validation issues
+- `ValidationIssue` — Single issue with severity, code, message, location, context
+- `IssueSeverity` — ERROR, WARNING, INFO levels
+- `StructureValidator` — Validates schema structure (cycles, version ordering, parent chains)
+- `ConventionChecker` — Validates naming conventions for types, fields, classes
+- `ConventionRules` — Configurable naming rules (STRICT, RELAXED, NONE, or custom)
+- Predefined patterns for snake_case, camelCase, class suffixes
+- Custom validators via `customTypeValidator()` and `customFieldValidator()`
+
+**Type Introspection (`schematools.introspection`):**
+- `TypeIntrospector` — Utility for analyzing type structures
+- `TypeStructure` — Normalized, comparable representation of a Type
+- `FieldInfo` — Field metadata (name, path, optionality, type)
+- `TypeKind` — Classification (PRIMITIVE, LIST, OPTIONAL, PRODUCT, SUM, FIELD, etc.)
+- Recursive field extraction with hierarchical paths
+- Structural equality comparison
+
 #### CLI Module (`aether-datafixers-cli`)
 
 New command-line interface for data migration without writing Java code.
@@ -47,6 +88,13 @@ New command-line interface for data migration without writing Java code.
 - `BootstrapLoadException` — Bootstrap class loading failures
 - `FormatParseException` — Input parsing failures
 
+### Documentation
+
+- Added comprehensive Schema Tools documentation (diffing, analysis, validation, introspection)
+- Added CLI module documentation (commands, format handlers, examples)
+- Updated glossary with Schema Tools terminology
+- Updated installation guide with new modules
+
 ---
 
 ## [0.2.0] - 2026-01-07

README.md

@@ -18,6 +18,8 @@ inspired by Minecraft's DataFixer Upper (DFU), with a focus on **simplicity**, *
 - ✅ **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
+- ✅ **CLI Tool** — Migrate and validate data files from the command line with batch processing
+- ✅ **Schema Tools** — Schema diffing, validation, migration analysis, and type introspection
 - ✅ **Migration Diagnostics** — Opt-in structured reports with timing, applied fixes, and snapshots
 - ✅ **Extended Rewrite Rules** — Batch operations, path-based transforms, conditional rules
 - ✅ **High-Performance APIs** — `Rules.batch()` for single-pass multi-operation transforms
@@ -31,6 +33,8 @@ inspired by Minecraft's DataFixer Upper (DFU), with a focus on **simplicity**, *
 - **aether-datafixers-core** — Default implementations of the API interfaces
 - **aether-datafixers-codec** — Codec implementations for serialization formats
 - **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
 - **aether-datafixers-examples** — Practical examples demonstrating real-world usage
 - **aether-datafixers-bom** — Bill of Materials for coordinated dependency management
 
@@ -418,8 +422,10 @@ mvn test
   - **Performance optimizations** — Path caching, optimized fix registry, reduced allocations
 
 - **v0.3.0** (next)
-  - **CLI module** — Migrate files and print/export a migration report (batch-friendly)
-  - **Schema tooling** — Runtime schema validation + diff utilities between versions
+  - **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**
   - **Spring Boot integration** — Auto-configuration for DataFixer in Spring apps

docs/README.md

@@ -94,6 +94,16 @@ Migrate and validate data files from the command line:
 - [Format Handlers](cli/format-handlers.md) — Custom format handler development
 - [Examples](cli/examples.md) — Practical usage examples
 
+### Schema Tools
+
+Analyze, compare, and validate your schemas:
+
+- [Schema Tools Overview](schema-tools/index.md) — Introduction to schema tooling
+- [Schema Diffing](schema-tools/schema-diffing.md) — Compare schemas and detect changes
+- [Migration Analysis](schema-tools/migration-analysis.md) — Analyze migration paths and fix coverage
+- [Schema Validation](schema-tools/schema-validation.md) — Validate structure and conventions
+- [Type Introspection](schema-tools/type-introspection.md) — Inspect type structures
+
 ### Advanced Topics
 
 For experienced users:
@@ -121,6 +131,7 @@ For experienced users:
 | `aether-datafixers-codec` | GsonOps, JacksonOps implementations |
 | `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-bom` | Bill of Materials for version management |
 

docs/appendix/changelog.md

@@ -6,6 +6,16 @@ History of documentation updates. For code changes, see the main [CHANGELOG.md](
 
 ## Version 0.3.0
 
+### New Section: Schema Tools Module
+
+Added complete documentation for the new schema tools module:
+
+- [Schema Tools Overview](../schema-tools/index.md) — Introduction, use cases, and quick start
+- [Schema Diffing](../schema-tools/schema-diffing.md) — Compare schemas and detect type/field changes
+- [Migration Analysis](../schema-tools/migration-analysis.md) — Analyze migration paths and fix coverage
+- [Schema Validation](../schema-tools/schema-validation.md) — Validate structure and naming conventions
+- [Type Introspection](../schema-tools/type-introspection.md) — Inspect type structures and extract field metadata
+
 ### New Section: CLI Module
 
 Added complete documentation for the new CLI module:
@@ -18,7 +28,7 @@ Added complete documentation for the new CLI module:
 
 ### Updated Pages
 
-- [Main README](../README.md) — Added CLI module to navigation and module table
+- [Main README](../README.md) — Added CLI and Schema Tools to navigation and module table
 - [Installation Guide](../getting-started/installation.md) — Added CLI module to overview table
 
 ---

docs/appendix/glossary.md

@@ -151,3 +151,68 @@ Terminology used in Aether Datafixers.
 **TypedAssert**
 : Custom AssertJ assertions for Typed objects (type and value checks).
 
+## Schema Tools
+
+**ConventionChecker**
+: Validates naming conventions for types, fields, and class names.
+
+**ConventionRules**
+: Configurable naming rules for convention validation (STRICT, RELAXED, NONE, or custom).
+
+**CoverageGap**
+: Represents a schema change without a corresponding DataFix.
+
+**DiffKind**
+: Enumeration of change types: ADDED, REMOVED, MODIFIED, UNCHANGED.
+
+**FieldDiff**
+: Represents a change to a single field between schema versions.
+
+**FieldInfo**
+: Metadata about a field including name, path, optionality, and type.
+
+**FixCoverage**
+: Analysis result showing which schema changes have corresponding DataFixes.
+
+**IssueSeverity**
+: Validation issue severity levels: ERROR, WARNING, INFO.
+
+**MigrationAnalyzer**
+: Entry point for analyzing migration paths and fix coverage between versions.
+
+**MigrationPath**
+: Complete migration sequence containing all steps from source to target version.
+
+**MigrationStep**
+: Single version transition in a migration path, with optional DataFix and SchemaDiff.
+
+**SchemaDiff**
+: Result of comparing two schemas, containing added/removed types and field changes.
+
+**SchemaDiffer**
+: Fluent API for comparing schemas and generating SchemaDiff results.
+
+**SchemaValidator**
+: Fluent API for validating schema structure, conventions, and fix coverage.
+
+**StructureValidator**
+: Validates schema structural integrity (cycles, version ordering, parent chains).
+
+**TypeDiff**
+: Field-level changes for a specific type present in both compared schemas.
+
+**TypeIntrospector**
+: Utility for analyzing type structure and extracting field information.
+
+**TypeKind**
+: Classification of types: PRIMITIVE, LIST, OPTIONAL, PRODUCT, SUM, FIELD, etc.
+
+**TypeStructure**
+: Normalized, comparable representation of a Type for analysis.
+
+**ValidationIssue**
+: Single validation issue with severity, code, message, location, and context.
+
+**ValidationResult**
+: Immutable collection of validation issues with filtering and status methods.
+

docs/getting-started/installation.md

@@ -12,6 +12,7 @@ Aether Datafixers is modular. Choose the modules you need:
 | `aether-datafixers-core` | Default implementations | Always needed for runtime |
 | `aether-datafixers-codec` | GsonOps, JacksonOps | When working with JSON |
 | `aether-datafixers-cli` | Command-line interface | For CLI-based data migration |
+| `aether-datafixers-schema-tools` | Schema analysis and validation | For CI/CD validation, diffing, coverage |
 | `aether-datafixers-testkit` | Testing utilities | For unit/integration testing |
 | `aether-datafixers-bom` | Version management | Recommended for multi-module projects |
 
@@ -245,6 +246,21 @@ For command-line usage without writing Java code, see the dedicated CLI document
 
 ---
 
+## Schema Tools Installation
+
+For schema analysis, validation, and migration coverage checking:
+
+```xml
+<dependency>
+    <groupId>de.splatgames.aether.datafixers</groupId>
+    <artifactId>aether-datafixers-schema-tools</artifactId>
+</dependency>
+```
+
+→ [Schema Tools Overview](../schema-tools/index.md) — Learn about schema diffing, validation, and analysis
+
+---
+
 ## Next Steps
 
 Now that you have Aether Datafixers installed, proceed to:

docs/schema-tools/index.md

@@ -0,0 +1,137 @@
+# Schema Tools
+
+The **Aether Datafixers Schema Tools** module provides utilities for analyzing, comparing, validating, and introspecting schemas. It helps ensure migration completeness, detect schema changes, and enforce naming conventions.
+
+## Overview
+
+Schema Tools (`aether-datafixers-schema-tools`) is designed for:
+
+- **Schema Diffing** — Compare two schemas to see what types and fields changed
+- **Migration Analysis** — Analyze migration paths and verify fix coverage
+- **Validation** — Validate schema structure and enforce naming conventions
+- **Introspection** — Inspect type structures and extract field metadata
+
+## Quick Start
+
+```java
+import de.splatgames.aether.datafixers.schematools.diff.SchemaDiffer;
+import de.splatgames.aether.datafixers.schematools.analysis.MigrationAnalyzer;
+import de.splatgames.aether.datafixers.schematools.validation.SchemaValidator;
+
+// Compare two schemas
+SchemaDiff diff = SchemaDiffer.compare(schemaV1, schemaV2)
+    .includeFieldLevel(true)
+    .diff();
+
+// Analyze migration path
+MigrationPath path = MigrationAnalyzer.forBootstrap(bootstrap)
+    .from(100).to(200)
+    .analyze();
+
+// Validate schemas
+ValidationResult result = SchemaValidator.forBootstrap(bootstrap)
+    .validateAll()
+    .validate();
+```
+
+## Module Contents
+
+| Package | Description |
+|---------|-------------|
+| `schematools.diff` | Schema comparison and diff generation |
+| `schematools.analysis` | Migration path analysis and fix coverage |
+| `schematools.validation` | Schema validation and convention checking |
+| `schematools.introspection` | Type structure inspection and field extraction |
+
+## Installation
+
+Add schema-tools as a dependency:
+
+**Maven:**
+```xml
+<dependency>
+    <groupId>de.splatgames.aether.datafixers</groupId>
+    <artifactId>aether-datafixers-schema-tools</artifactId>
+</dependency>
+```
+
+**Gradle:**
+```groovy
+implementation 'de.splatgames.aether.datafixers:aether-datafixers-schema-tools'
+```
+
+## Use Cases
+
+### Pre-Release Validation
+
+Before releasing a new version, validate that all schema changes have corresponding DataFixes:
+
+```java
+FixCoverage coverage = MigrationAnalyzer.forBootstrap(bootstrap)
+    .from(oldVersion)
+    .to(newVersion)
+    .analyzeCoverage();
+
+if (!coverage.isFullyCovered()) {
+    for (CoverageGap gap : coverage.gaps()) {
+        System.err.println("Missing fix: " + gap.type() + " - " + gap.reason());
+    }
+    throw new IllegalStateException("Not all schema changes are covered by fixes!");
+}
+```
+
+### CI/CD Integration
+
+Integrate schema validation into your build pipeline:
+
+```java
+ValidationResult result = SchemaValidator.forBootstrap(bootstrap)
+    .validateStructure()
+    .validateConventions()
+    .withConventions(ConventionRules.STRICT)
+    .validate();
+
+if (!result.isValid()) {
+    result.errors().forEach(error ->
+        System.err.println("[ERROR] " + error.code() + ": " + error.message())
+    );
+    System.exit(1);
+}
+```
+
+### Schema Change Documentation
+
+Generate documentation of schema changes between versions:
+
+```java
+SchemaDiff diff = SchemaDiffer.compare(schemaV1, schemaV2)
+    .includeFieldLevel(true)
+    .diff();
+
+System.out.println("Schema Changes V1 -> V2:");
+System.out.println("  Added types: " + diff.addedTypes());
+System.out.println("  Removed types: " + diff.removedTypes());
+
+for (TypeDiff typeDiff : diff.typeDiffs().values()) {
+    System.out.println("  " + typeDiff.reference().name() + ":");
+    typeDiff.addedFields().forEach(f ->
+        System.out.println("    + " + f.fieldName()));
+    typeDiff.removedFields().forEach(f ->
+        System.out.println("    - " + f.fieldName()));
+}
+```
+
+---
+
+## In This Section
+
+- [Schema Diffing](schema-diffing.md) — Compare schemas and detect changes
+- [Migration Analysis](migration-analysis.md) — Analyze migration paths and fix coverage
+- [Schema Validation](schema-validation.md) — Validate structure and conventions
+- [Type Introspection](type-introspection.md) — Inspect type structures
+
+---
+
+## Next Steps
+
+→ [Schema Diffing](schema-diffing.md) — Learn how to compare schemas