Verify Entity Field Types and Lengths Match ESPI 4.0 XSD Schemas

[dfcoffin]

Description

Verify that all entities extending IdentifiedObject have field data types and lengths that match the definitions in the ESPI 4.0 XSD schema files (espi.xsd and customer.xsd).

Background

The OpenESPI-GreenButton-Java implementation has been migrated to Spring Boot 4.0 and Jakarta EE 10+, with entities using Jakarta Persistence annotations. We need to ensure that all JPA entity field definitions remain compliant with the NAESB ESPI 4.0 specification.

Entities to Verify

Usage Domain (espi.xsd)

Located in openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/usage/:

1. UsagePointEntity - Metering point
2. MeterReadingEntity - Meter reading collection
3. IntervalBlockEntity - Time-series interval data
4. ReadingTypeEntity - Measurement metadata
5. ElectricPowerQualitySummaryEntity - Power quality metrics
6. UsageSummaryEntity - Usage aggregation
7. LocalTimeParametersEntity - Timezone configuration
8. RetailCustomerEntity - Customer information
9. ApplicationInformationEntity - OAuth2 application registration

Customer Domain (customer.xsd)

Located in openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/customer/entity/:

1. CustomerAccountEntity - Customer billing account
2. CustomerEntity - Customer information
3. CustomerAgreementEntity - Service agreement
4. ServiceSupplierEntity - Utility provider
5. MeterEntity - Physical meter device
6. EndDeviceEntity - End device information
7. ServiceLocationEntity - Service delivery location
8. StatementEntity - Billing statement
9. ProgramDateIdMappingsEntity - Program date mappings

XSD Schema References

• espi.xsd: openespi-common/src/main/resources/schema/ESPI_4.0/espi.xsd
• customer.xsd: openespi-common/src/main/resources/schema/ESPI_4.0/customer.xsd

Verification Requirements

For each entity, verify:

1. Field Data Types: JPA @Column types match XSD element types

   • String fields have appropriate length attribute
   • Numeric fields use correct Java types (Integer, Long, BigInteger, BigDecimal)
   • Date/time fields use appropriate temporal types
   • Enum fields map to XSD enumeration types correctly

2. Field Length Constraints: String field @Column(length=...) matches XSD maxLength facets

3. Nullable Constraints: @Column(nullable=...) matches XSD minOccurs requirements

4. Embedded Objects: @Embedded objects match XSD complex type definitions

5. Collections: @ElementCollection and @OneToMany mappings match XSD sequence/choice definitions

Acceptance Criteria

• All entity field types match XSD schema definitions
• All string field length constraints match XSD maxLength facets
• All nullable constraints match XSD minOccurs requirements
• Any discrepancies are documented with justification or corrected
• Database migration scripts (Flyway) align with corrected entity definitions
• All existing tests continue to pass after any corrections

Example Verification Pattern

For UsagePointEntity:

// Entity field
@Column(name = "service_category_kind")
private ServiceKind serviceCategory;

// XSD definition (espi.xsd)
<xs:element name="ServiceCategory" type="espi:ServiceKind" minOccurs="1"/>

// Verification:
// ✓ Type matches (ServiceKind enum)
// ✓ Nullable constraint matches (minOccurs=1 → nullable=false expected)

Related Issues

• Issue Review Current Usage and Customer Entity Classes to ensure they match their ESPI Schema XSD files #28 - Phase 17 implementation established the pattern for customer domain entities
• Recent migration to Spring Boot 4.0 and Jakarta EE 10+ may have introduced inconsistencies

Priority

Medium - This is a technical debt/compliance verification task that ensures long-term schema compliance and interoperability.

[dfcoffin]

Status Update: Phase 0 Complete ✅

Phase 0: Schema Analysis - COMPLETE

PR #104 merged to main: #104

Deliverables

Comprehensive ESPI 4.0 schema analysis reports created and merged:

Report	Lines	Description
00_SCHEMA_ANALYSIS_SUMMARY.md	246	High-level overview, statistics, and implementation guide
espi_enumerations.md	836	Complete espi.xsd analysis (35 enumerations)
customer_enumerations.md	1,107	Complete customer.xsd analysis (16 enumerations)

Key Findings

Total Schema Coverage:

• 51 enumeration types documented with all values
• 27 resource complex types
• 47 supporting complex types
• 65 global elements
• Type inheritance hierarchies mapped

Critical Enumerations for Implementation:

• Usage Domain (espi.xsd): AccumulationKind, CommodityKind, Currency, DataQualifierKind, FlowDirectionKind, MeasurementKind (100+ values), PhaseCodeKind, QualityOfReading, TimeAttributeKind, UnitMultiplierKind, UnitSymbolKind (100+ values)
• Customer Domain (customer.xsd): CustomerKind, SupplierKind, ServiceKind, EnrollmentStatus, NotificationMethodKind, MeterMultiplierKind, RevenueKind, ProgramDateKind, StatusCode
• OAuth (espi.xsd): GrantType, TokenType, OAuthError, ResponseType

Implementation Notes Added

The reports include:

• Java enum mapping strategies for union types
• Validation considerations for string lengths and hex binary types
• JAXB/Jakarta XML binding patterns
• Common ESPI patterns (IdentifiedObject hierarchy, time/money representations)

---

Next Steps

• Phase 1: Directory structure setup (branch: feature/issue-101-phase-0-enum-setup)
• Phase 2: Begin enum implementation based on schema analysis
• Phase 3: Entity field validation against schemas

The schema analysis provides the foundation for all subsequent enumeration implementation work.