GreenButtonAlliance · dfcoffin · Jan 4, 2026 · Jan 4, 2026
diff --git a/MULTI_PHASE_SCHEMA_COMPLIANCE_PLAN.md b/MULTI_PHASE_SCHEMA_COMPLIANCE_PLAN.md
@@ -14,7 +14,8 @@ This plan reviews domain entities in `/domain/usage`, `/domain/customer`, and `/
 - **Jakarta EE**: 11
 - **Maven**: 3.9+
 - **MapStruct**: 1.6.3
-- **JAXB**: jakarta.xml.bind-api 4.x
+- **Jackson 3 XML**: tools.jackson.dataformat:jackson-dataformat-xml:3.0.3
+- **Jackson JAXB Module**: tools.jackson.module:jackson-module-jakarta-xmlbind-annotations:3.0.3
 - **TestContainers**: 1.20.x
 
 **Testing Framework:**
@@ -28,8 +29,11 @@ This plan reviews domain entities in `/domain/usage`, `/domain/customer`, and `/
   - `spring-boot-starter-restclient-test`
 
 **DTO Marshalling Approach:**
-- **JAXB (Jakarta XML Binding)** - Selected for all 26 phases
-- **Rationale**: Jackson 3.0 XML support is immature in Spring Boot 4.0; JAXB provides proven, stable XML schema compliance with strict XSD element sequencing
+- **Jackson 3 (jackson-dataformat-xml)** with Jakarta XML Bind annotations - Selected for all 26 phases
+- **Serialization Engine**: Jackson XmlMapper (jackson-dataformat-xml)
+- **DTO Annotations**: Jakarta XML Bind (JAXB 3.0) annotations (jakarta.xml.bind.annotation.*)
+- **Bridge Module**: jackson-module-jakarta-xmlbind-annotations (enables Jackson to process JAXB annotations)
+- **Rationale**: Combines Jackson 3's modern features and performance with JAXB's standardized annotations, leveraging Spring Boot 4's managed dependencies
 
 **IMPORTANT:** All 26 phases are implemented against the Spring Boot 4.0 + Java 25 baseline established by PR #50 (merged 2025-12-29).
 
@@ -68,12 +72,13 @@ This plan reviews domain entities in `/domain/usage`, `/domain/customer`, and `/
 1. **Entity Updates** (TimeConfigurationEntity.java):
    - Review field order against espi.xsd TimeConfiguration element sequence
    - Verify JPA annotations match schema constraints
-   - Ensure JAXB annotations align with XML element names and order
    - Update field JavaDoc to reference XSD documentation
 
 2. **DTO Updates** (TimeConfigurationDto.java):
    - Match DTO field order to espi.xsd TimeConfiguration element sequence
-   - Verify JAXB annotations for XML marshalling
+   - Verify Jakarta XML Bind annotations for XML marshalling (jakarta.xml.bind.annotation.*)
+     - `@XmlRootElement`, `@XmlElement`, `@XmlAttribute`, `@XmlType(propOrder)`
+     - Jackson will process these annotations via jackson-module-jakarta-xmlbind-annotations
    - Add XSD constraint validation annotations
 
 3. **MapStruct Mapper Updates** (TimeConfigurationMapper.java):
@@ -104,8 +109,10 @@ This plan reviews domain entities in `/domain/usage`, `/domain/customer`, and `/
      - Add `@AutoConfigureMockMvc` if using `@SpringBootTest` with web layer
    - **Integration Tests**: Add/update tests using TestContainers
      - TestContainers dependency: `org.testcontainers:testcontainers-junit-jupiter` (artifact ID changed in Spring Boot 4.0)
-   - **XML Marshalling Tests**: Create JAXB XML marshalling/unmarshalling tests
+   - **XML Marshalling Tests**: Create Jackson 3 XML marshalling/unmarshalling tests with JAXB annotations
      - Use pure JUnit 5 (no Spring Boot test dependencies required)
+     - Use Jackson XmlMapper for serialization (processes Jakarta XML Bind annotations)
+     - Ensure jackson-module-jakarta-xmlbind-annotations is available
      - Verify element sequence matches espi.xsd
      - Test round-trip serialization (marshal → unmarshal → verify equality)
    - **XSD Validation**: Validate generated XML against espi.xsd using schema validation
@@ -735,11 +742,12 @@ This plan reviews domain entities in `/domain/usage`, `/domain/customer`, and `/
 1. **Entity Updates** (ProgramDateIdMappingsEntity.java):
    - Review field order against customer.xsd ProgramDateIdMappings element sequence
    - Verify JPA annotations match schema constraints
-   - Verify JAXB annotations align with XML element names and order
 
 2. **DTO Updates** (ProgramDateIdMappingsDto.java):
    - Match DTO field order to customer.xsd ProgramDateIdMappings element sequence
-   - Verify JAXB annotations for XML marshalling
+   - Verify Jakarta XML Bind annotations for XML marshalling (jakarta.xml.bind.annotation.*)
+     - `@XmlRootElement`, `@XmlElement`, `@XmlAttribute`, `@XmlType(propOrder)`
+     - Jackson will process these annotations via jackson-module-jakarta-xmlbind-annotations
 
 3. **MapStruct Mapper Updates** (ProgramDateIdMappingsMapper.java):
    - Update Entity-to-DTO conversion mapping
@@ -1132,12 +1140,12 @@ This plan reviews domain entities in `/domain/usage`, `/domain/customer`, and `/
 This 26-phase plan ensures comprehensive schema compliance review for all NAESB ESPI 4.0 domain entities and associated classes. Each phase focuses on a single entity and includes:
 
 1. Entity field order verification against XSD schema
-2. DTO field order verification and JAXB annotations
+2. DTO field order verification with Jakarta XML Bind (JAXB 3.0) annotations
 3. Bidirectional MapStruct mapper updates (Entity-to-DTO and DTO-to-Entity)
 4. Repository query simplification (index fields only)
 5. Service method schema compliance review
 6. Flyway migration script updates (original scripts, no new scripts)
-7. Comprehensive testing including XML marshalling/unmarshalling and XSD validation
+7. Comprehensive testing including Jackson 3 XML marshalling/unmarshalling and XSD validation
 8. Git workflow (branch, commit, push, PR merge)
 
 **Processing Order**:
@@ -1165,8 +1173,11 @@ This 26-phase plan ensures comprehensive schema compliance review for all NAESB
   - `@AutoConfigureMockMvc` annotation required when using `@SpringBootTest` with web layer
 - **Integration Tests**: TestContainers for MySQL, PostgreSQL, H2
   - Dependency: `org.testcontainers:testcontainers-junit-jupiter` (artifact ID changed from `junit-jupiter`)
-- **XML Marshalling Tests**: JAXB XML marshalling/unmarshalling tests for ALL 26 phases
+- **XML Marshalling Tests**: Jackson 3 XML marshalling/unmarshalling tests for ALL 26 phases
   - Pure JUnit 5 tests (no Spring Boot test dependencies needed)
+  - Use Jackson XmlMapper (from jackson-dataformat-xml)
+  - DTOs use Jakarta XML Bind annotations (jakarta.xml.bind.annotation.*)
+  - Requires jackson-module-jakarta-xmlbind-annotations module
   - Verify XSD element sequence compliance
   - Test round-trip serialization
 - **XSD Schema Validation**:

diff --git a/openespi-common/DTO_APPROACH_COMPARISON.md b/openespi-common/DTO_APPROACH_COMPARISON.md
@@ -1,12 +1,52 @@
 # DTO Approach Comparison: JAXB vs Jackson XML
 
-**Status:** Phase 1 Prototype Evaluation
-**Date:** 2025-12-26
-**Purpose:** Evaluate two alternative approaches for ESPI 4.0 DTO implementation across 26 phases
+**Status:** ✅ **DECISION MADE** - Hybrid Approach (Jackson 3 Engine + JAXB Annotations)
+**Original Evaluation Date:** 2025-12-26
+**Decision Date:** 2026-01-02 (PR #59)
+**Purpose:** Archive of evaluation process for ESPI 4.0 DTO implementation
 
 ---
 
-## Executive Summary
+## 🎯 CHOSEN APPROACH: Jackson 3 with JAXB Annotations
+
+**Implementation:** PR #59 (merged 2026-01-02)
+
+The team chose a **hybrid approach** that combines the best of both worlds:
+
+### What Was Chosen
+- **XML Serialization Engine**: Jackson 3 XmlMapper (`tools.jackson.dataformat:jackson-dataformat-xml:3.0.3`)
+- **DTO Annotations**: Jakarta XML Bind (JAXB 3.0) annotations (`jakarta.xml.bind.annotation.*`)
+- **Bridge Module**: `tools.jackson.module:jackson-module-jakarta-xmlbind-annotations:3.0.3`
+
+### Why This Approach
+✅ **Modern Performance**: Jackson 3's high-performance serialization engine
+✅ **Standard Annotations**: JAXB annotations remain the industry standard for XML mapping
+✅ **No Annotation Rewrites**: Existing DTOs keep their JAXB annotations
+✅ **Spring Boot 4.0 Ready**: Native Jackson 3 support in Spring Boot 4.0
+✅ **Records Compatible**: Works with both classes and Java Records
+✅ **Proven**: Successfully implemented and tested in PR #59
+
+### How It Works
+```java
+// DTOs use JAXB annotations (no change needed!)
+@XmlRootElement(name = "IntervalBlock", namespace = "http://naesb.org/espi")
+@XmlType(propOrder = {...})
+public record IntervalBlockDto(...) { }
+
+// Jackson XmlMapper processes JAXB annotations
+XmlMapper xmlMapper = XmlMapper.xmlBuilder()
+    .annotationIntrospector(new JakartaXmlBindAnnotationIntrospector())
+    .addModule(new JakartaXmlBindAnnotationModule())
+    .build();
+```
+
+**See:** `DtoExportServiceImpl.java:154-172` for complete implementation
+
+---
+
+## Historical Evaluation Summary
+
+This section preserves the original evaluation that led to the decision.
 
 Both **JAXB (Jakarta XML Binding)** and **Jackson XML** approaches successfully:
 - ✅ Marshal/unmarshal TimeConfiguration XML correctly
@@ -333,83 +373,84 @@ Time elapsed: 0.213 s
 
 ---
 
-## Recommendations
-
-### For Senior Spring Boot Developer Consideration:
+## ~~Recommendations~~ FINAL DECISION
 
-**If prioritizing:**
+### ✅ Chosen Approach: Hybrid (Jackson 3 + JAXB Annotations)
 
-1. **Long-term Maintainability → Choose Jackson XML**
-   - 24% less code to maintain across 26 phases
-   - Immutability reduces bugs
-   - Aligned with Spring Boot 3.x/4.0 direction
-   - Modern recruitment advantage
+The team chose **Option D: Hybrid Approach** (not originally listed) which provides:
 
-2. **Short-term Delivery & Stability → Choose JAXB**
-   - Proven XSD compliance
-   - Team already familiar
-   - Matches existing pattern
-   - Lower risk for Phase 1 completion
+**✅ Best of Both Worlds:**
+1. **Jackson 3 Performance**: Modern, high-performance XML serialization engine
+2. **JAXB Standard Annotations**: Keep industry-standard XML mapping annotations
+3. **No Refactoring Required**: Existing DTOs continue using JAXB annotations
+4. **Spring Boot 4.0 Ready**: Native Jackson 3 support
+5. **XSD Compliance**: JAXB annotations ensure schema compliance
 
-3. **ESPI XSD Strict Compliance → Choose JAXB**
-   - Built specifically for XML Schema
-   - Better validation tooling
-   - Industry standard for schema-first development
+**✅ Addresses All Concerns:**
+- **Maintainability**: Jackson 3 is the future for Spring Boot 4.0
+- **Stability**: JAXB annotations are proven and stable
+- **Consistency**: All DTOs use same annotation style
+- **Compliance**: JAXB annotations guarantee ESPI 4.0 XSD compliance
+- **No Retraining**: Team continues using familiar JAXB annotations
 
-### Decision Timeline
+### Implementation Status
 
-**Recommendation:** Make decision **now at Phase 1**, not after multiple phases are complete.
+**✅ Completed (PR #59):**
+- Jackson 3 XML dependencies added to `openespi-common/pom.xml`
+- `DtoExportServiceImpl` updated with Jackson 3 XmlMapper configuration
+- All existing DTOs continue using JAXB annotations (no changes needed)
+- Integration tests passing with Jackson 3 serialization
+- Production XML output verified against ESPI 4.0 schema
 
-**If choosing Jackson XML:**
-- Budget time to refactor existing DTOs (`UsagePointDto`, etc.) for consistency
-- Create team training on Jackson XML annotations
-- Update DTO_PATTERN_GUIDE.md with Jackson patterns
-
-**If choosing JAXB:**
-- Accept higher LOC count across remaining 25 phases
-- Document defensive copying patterns for byte arrays
-- Plan future migration to Jackson if Spring Boot 4.0 shifts direction
+**📋 Next Steps:**
+- All 26 phases will use JAXB annotations on DTOs
+- Jackson 3 XmlMapper handles serialization/deserialization
+- See `MULTI_PHASE_SCHEMA_COMPLIANCE_PLAN.md` for phase-by-phase plan
 
 ---
 
-## Files for Review
+## Implementation Files
 
-### JAXB Implementation
-- **DTO:** `src/main/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDto.java`
-- **Tests:** `src/test/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDtoTest.java`
-- **Mapper:** `src/main/java/org/greenbuttonalliance/espi/common/mapper/usage/TimeConfigurationMapper.java`
+### Jackson 3 Configuration
+- **Service:** `DtoExportServiceImpl.java` - XmlMapper configuration with JAXB annotation support
+- **Dependencies:** `openespi-common/pom.xml` - Jackson 3 XML and JAXB module
+- **Tests:** `DtoExportServiceImplTest.java` - Integration tests with sample XML output
 
-### Jackson XML Implementation
-- **DTO:** `src/main/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDtoJackson.java`
-- **Tests:** `src/test/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDtoJacksonTest.java`
-- **Dependencies:** Added `jackson-dataformat-xml` to `pom.xml`
+### DTO Examples (Using JAXB Annotations)
+- **IntervalBlockDto.java** - Record with JAXB annotations
+- **UsagePointDto.java** - DTO with JAXB annotations
+- **AtomEntryDto.java** - Atom wrapper with JAXB annotations
 
-### Comparison Document
-- **This file:** `DTO_APPROACH_COMPARISON.md`
+### Sample Output
+- **testdata.xml** - ESPI-compliant Atom XML produced by Jackson 3
 
----
+### Planning Documents
+- **MULTI_PHASE_SCHEMA_COMPLIANCE_PLAN.md** - Updated with Jackson 3 approach
+- **This file:** `DTO_APPROACH_COMPARISON.md` - Decision rationale
 
-## Next Steps
+---
 
-1. **Team Review:** Distribute this document for review
-2. **Decision Meeting:** Schedule architecture discussion
-3. **Consensus:** Choose one approach for all 26 phases
-4. **Update Plan:** Modify `SPRING_BOOT_CONVERSION_PLAN.md` with chosen approach
-5. **Phase 1 Completion:** Implement chosen approach for TimeConfiguration
-6. **Phases 2-26:** Apply chosen pattern consistently
+## Decision Rationale
 
----
+**Why Not Pure JAXB?**
+- Requires JAXB runtime (javax.xml.bind implementation)
+- Slower performance compared to Jackson 3
+- Not the direction of Spring Boot 4.0
 
-## Questions for Discussion
+**Why Not Pure Jackson XML?**
+- Would require rewriting all JAXB annotations to Jackson annotations
+- Jackson XML annotations less mature for strict XSD compliance
+- Team would need retraining on new annotation styles
 
-1. How important is strict XSD validation vs code maintainability?
-2. Are we comfortable requiring Java 17+ records?
-3. Should we refactor existing DTOs for consistency?
-4. What is the team's experience level with Jackson XML?
-5. Do we expect ESPI schema changes that would benefit from JAXB's validation?
+**Why Hybrid (Jackson 3 + JAXB Annotations)?**
+- ✅ Jackson 3 processes JAXB annotations via bridge module
+- ✅ Keep proven JAXB annotations for XSD compliance
+- ✅ Gain Jackson 3 performance and Spring Boot 4.0 alignment
+- ✅ Zero annotation rewrites needed
+- ✅ Best long-term maintainability
 
 ---
 
 **Author:** Claude Sonnet 4.5 (Senior Spring Boot Architecture Consultant)
-**Review Status:** Awaiting Team Decision
+**Review Status:** ✅ **DECISION MADE AND IMPLEMENTED** (PR #59, merged 2026-01-02)
 **Impact:** High (affects all 26 DTO implementation phases)
diff --git a/openespi-common/PR50_MULTI_PHASE_IMPACT.md b/openespi-common/PR50_MULTI_PHASE_IMPACT.md
@@ -2,7 +2,28 @@
 
 **Date:** 2025-12-29
 **Critical Issue:** PR #50 performs FULL PROJECT CONVERSION to Spring Boot 4.0 + Java 25
-**Status:** 🔴 **BLOCKS PHASE 1 DECISION** - Must validate against Spring Boot 4.0
+**Original Status:** 🔴 **BLOCKS PHASE 1 DECISION** - Must validate against Spring Boot 4.0
+
+---
+
+## ✅ RESOLUTION (2026-01-02)
+
+**PR #50 Status:** ✅ Merged (2025-12-29)
+**DTO Decision Status:** ✅ Made and Implemented (PR #59, merged 2026-01-02)
+
+**Final Decision:**
+- **Approach**: Jackson 3 XmlMapper + JAXB annotations (hybrid approach)
+- **Rationale**: Best of both worlds - Jackson 3 performance + JAXB standard annotations
+- **Implementation**: See `DtoExportServiceImpl.java` and `DTO_APPROACH_COMPARISON.md`
+- **Validated**: Successfully tested on Spring Boot 4.0.1 + Java 25
+
+**Documentation Updated:**
+- ✅ MULTI_PHASE_SCHEMA_COMPLIANCE_PLAN.md - Updated with Jackson 3 approach
+- ✅ DTO_APPROACH_COMPARISON.md - Decision documented with rationale
+
+---
+
+## Historical Context (Pre-Resolution)
 
 ---