Verify Entity Field Types and Lengths Match ESPI 4.0 XSD Schemas #101

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.