Skip to content

Commit 53f68c3

Browse files
dfcoffinclaude
dfcoffin
and
claude
authored
docs: Add ESPI 4.0 schema analysis reports for enum implementation (#104)
Comprehensive analysis of espi.xsd and customer.xsd schemas: - 51 enumeration types documented with all values - 27 resource complex types - 47 supporting complex types - Type inheritance hierarchy - Implementation notes for Java enum mapping Reports: - 00_SCHEMA_ANALYSIS_SUMMARY.md - Overview and index - espi_enumerations.md - Usage/energy schema (35 enums) - customer_enumerations.md - Customer/PII schema (16 enums) Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 4441d92 commit 53f68c3

3 files changed

Lines changed: 2189 additions & 0 deletions

File tree

‎reports/verification/00_SCHEMA_ANALYSIS_SUMMARY.md‎

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
# ESPI 4.0 Schema Analysis Summary
2+
3+
**Analysis Date:** 2026-02-03
4+
**NAESB REQ.21 ESPI Version:** 4.0
5+
**Schema Publication Dates:** December 13-15, 2023
6+
7+
---
8+
9+
## Overview
10+
11+
This directory contains comprehensive analysis reports for the NAESB ESPI 4.0 XML schemas used in the OpenESPI-GreenButton-Java implementation. The schemas define the data model for energy usage data exchange under the Green Button standard.
12+
13+
## Schema Files Analyzed
14+
15+
| Schema | Namespace | Purpose | Report |
16+
|--------|-----------|---------|--------|
17+
| `espi.xsd` | `http://naesb.org/espi` | Energy usage data (UsagePoint, MeterReading, IntervalBlock, etc.) | [espi_enumerations.md](espi_enumerations.md) |
18+
| `customer.xsd` | `http://naesb.org/espi/customer` | Customer/PII data (Customer, CustomerAccount, Meter, etc.) | [customer_enumerations.md](customer_enumerations.md) |
19+
20+
---
21+
22+
## Combined Statistics
23+
24+
| Category | espi.xsd | customer.xsd | Total |
25+
|----------|----------|--------------|-------|
26+
| Basic Types | 7 | 8 | 15 |
27+
| String Types | 7 | 5 | 12 |
28+
| Hex Binary Types | 4 | 4 | 8 |
29+
| Special Types | 2 | 2 | 4 |
30+
| Enumeration Types | 35 | 16 | 51 |
31+
| Complex Types (Resources) | 12 | 15 | 27 |
32+
| Complex Types (Supporting) | 17 | 30 | 47 |
33+
| Global Elements | 20 | 45 | 65 |
34+
35+
---
36+
37+
## Key Enumeration Types
38+
39+
### Usage Domain (espi.xsd)
40+
41+
| Enumeration | Values | Description |
42+
|-------------|--------|-------------|
43+
| AccumulationKind | 14 | How readings are accumulated (instantaneous, cumulative, delta, etc.) |
44+
| CommodityKind | 14 | Type of commodity (electricity, gas, water, etc.) |
45+
| Currency | 100+ | ISO 4217 currency codes |
46+
| DataQualifierKind | 16 | Data quality indicators (average, maximum, minimum, etc.) |
47+
| FlowDirectionKind | 21 | Direction of energy flow (forward, reverse, net, etc.) |
48+
| MeasurementKind | 100+ | Type of measurement (energy, power, voltage, current, etc.) |
49+
| PhaseCodeKind | 20+ | Electrical phase codes (A, B, C, AB, ABC, etc.) |
50+
| QualityOfReading | 20+ | Reading quality indicators |
51+
| ServiceKind | 11 | Type of utility service |
52+
| TimeAttributeKind | 8 | Time period attributes (billing, seasonal, etc.) |
53+
| UnitMultiplierKind | 16 | SI unit multipliers (kilo, mega, milli, etc.) |
54+
| UnitSymbolKind | 100+ | Unit of measure symbols (W, Wh, VA, VAr, etc.) |
55+
56+
### Customer Domain (customer.xsd)
57+
58+
| Enumeration | Values | Description |
59+
|-------------|--------|-------------|
60+
| CustomerKind | 15 | Type of customer (residential, commercial, industrial, etc.) |
61+
| SupplierKind | 6 | Type of service supplier (utility, municipality, etc.) |
62+
| ServiceKind | 11 | Type of utility service |
63+
| EnrollmentStatus | 5 | Program enrollment status |
64+
| NotificationMethodKind | 5 | Customer notification methods |
65+
| MeterMultiplierKind | 6 | Types of meter multipliers |
66+
| RevenueKind | 7 | Types of revenue (fees, rates, rebates) |
67+
| ProgramDateKind | 4 | Types of program dates |
68+
| CRUDOperation | 4 | CRUD operation types |
69+
| MediaType | 15 | MIME content types |
70+
| StatusCode | 12+ | HTTP-style status codes |
71+
72+
### OAuth Enumerations (espi.xsd)
73+
74+
| Enumeration | Values | Description |
75+
|-------------|--------|-------------|
76+
| GrantType | 3 | OAuth 2.0 grant types |
77+
| ResponseType | 1 | OAuth response types |
78+
| TokenType | 1 | OAuth token types |
79+
| OAuthError | 12 | OAuth error codes |
80+
| TokenEndPointMethod | 1 | Token endpoint authentication methods |
81+
82+
---
83+
84+
## Core Resource Types
85+
86+
### Usage Domain Resources (espi.xsd)
87+
88+
| Resource | Base Type | Description |
89+
|----------|-----------|-------------|
90+
| UsagePoint | IdentifiedObject | Logical point for energy measurement |
91+
| MeterReading | IdentifiedObject | Collection of interval blocks |
92+
| IntervalBlock | IdentifiedObject | Time-series interval data |
93+
| IntervalReading | (inline) | Individual reading within an interval |
94+
| ReadingType | IdentifiedObject | Metadata describing measurements |
95+
| ElectricPowerQualitySummary | IdentifiedObject | Power quality metrics |
96+
| UsageSummary | IdentifiedObject | Aggregated usage statistics |
97+
| TimeConfiguration | IdentifiedObject | Timezone and DST settings |
98+
| Authorization | IdentifiedObject | OAuth authorization record |
99+
| ApplicationInformation | IdentifiedObject | Third-party application registration |
100+
| Subscription | IdentifiedObject | Data subscription |
101+
| RetailCustomer | IdentifiedObject | Retail customer (minimal) |
102+
103+
### Customer Domain Resources (customer.xsd)
104+
105+
| Resource | Base Type | Description |
106+
|----------|-----------|-------------|
107+
| Customer | Organisation | Full customer information |
108+
| CustomerAccount | Document | Customer billing account |
109+
| CustomerAgreement | Agreement | Service agreement |
110+
| ServiceSupplier | Organisation | Utility or energy provider |
111+
| ServiceLocation | WorkLocation | Physical service location |
112+
| Meter | EndDevice | Physical meter device |
113+
| EndDevice | AssetContainer | End device (base for Meter) |
114+
| Statement | Document | Billing statement |
115+
| DemandResponseProgram | IdentifiedObject | DR program enrollment |
116+
| PricingStructure | Document | Pricing/rate structure |
117+
| ProgramDateIdMappings | IdentifiedObject | Program date mappings |
118+
| TimeConfiguration | IdentifiedObject | Timezone and DST settings |
119+
| UsagePoint | IdentifiedObject | Usage point (customer context) |
120+
121+
---
122+
123+
## Type Inheritance Hierarchy
124+
125+
```
126+
Object
127+
└── IdentifiedObject
128+
├── UsagePoint
129+
├── MeterReading
130+
├── IntervalBlock
131+
├── ReadingType
132+
├── ElectricPowerQualitySummary
133+
├── UsageSummary
134+
├── TimeConfiguration
135+
├── Authorization
136+
├── ApplicationInformation
137+
├── Subscription
138+
├── RetailCustomer
139+
├── DemandResponseProgram
140+
├── ProgramDateIdMappings
141+
└── Document
142+
├── CustomerAccount
143+
├── PricingStructure
144+
├── Statement
145+
└── Agreement
146+
└── CustomerAgreement
147+
148+
Organisation (extends IdentifiedObject)
149+
├── Customer
150+
└── ServiceSupplier
151+
152+
Location (extends IdentifiedObject)
153+
└── WorkLocation
154+
└── ServiceLocation
155+
156+
Asset (extends IdentifiedObject)
157+
└── AssetContainer
158+
└── EndDevice
159+
└── Meter
160+
```
161+
162+
---
163+
164+
## Common Patterns
165+
166+
### Union Types for Enumerations
167+
168+
ESPI uses a union pattern for numeric enumerations that allows both defined values and extended values:
169+
170+
```xml
171+
<xs:simpleType name="AccumulationKind">
172+
<xs:union memberTypes="UInt16">
173+
<xs:simpleType>
174+
<xs:restriction base="xs:string">
175+
<xs:enumeration value="0"/> <!-- none -->
176+
<xs:enumeration value="1"/> <!-- bulkQuantity -->
177+
<!-- ... -->
178+
</xs:restriction>
179+
</xs:simpleType>
180+
</xs:union>
181+
</xs:simpleType>
182+
```
183+
184+
### IdentifiedObject Base Type
185+
186+
All major resources extend `IdentifiedObject` which provides:
187+
- `description` (String512) - Human-readable description
188+
- Extension capability from `Object` base type
189+
190+
### Time Representation
191+
192+
- All timestamps use `TimeType` (xs:long) as Unix epoch seconds
193+
- Timezone handled via `TimeConfiguration` (tzOffset, dstOffset, dstStartRule, dstEndRule)
194+
- Duration/intervals use `DateTimeInterval` (start, end, duration)
195+
196+
### Monetary Values
197+
198+
- Monetary amounts stored as `Int48` in smallest currency unit (cents/pence)
199+
- Currency specified separately using ISO 4217 numeric codes
200+
201+
---
202+
203+
## Schema Location
204+
205+
The schema files are located at:
206+
```
207+
openespi-common/src/main/resources/schema/ESPI_4.0/
208+
├── espi.xsd (usage/energy data)
209+
└── customer.xsd (customer/PII data)
210+
```
211+
212+
---
213+
214+
## Related Documentation
215+
216+
- [ESPI Enumerations Report](espi_enumerations.md) - Detailed analysis of espi.xsd
217+
- [Customer Enumerations Report](customer_enumerations.md) - Detailed analysis of customer.xsd
218+
- [NAESB ESPI 4.0 Specification](https://www.naesb.org/) - Official specification
219+
220+
---
221+
222+
## Implementation Notes
223+
224+
### Java Enum Mapping
225+
226+
When implementing Java enums for ESPI types:
227+
228+
1. **Numeric enumerations** (UInt16 union) - Map to Java enum with integer value field
229+
2. **String enumerations** - Map to Java enum with string value field
230+
3. **Large enumerations** (100+ values) - Consider using lookup maps for efficiency
231+
232+
### Validation Considerations
233+
234+
1. **Union types** allow undefined numeric values - implement lenient parsing
235+
2. **String length restrictions** must be enforced (String32, String256, etc.)
236+
3. **HexBinary types** have specific byte length requirements
237+
238+
### JAXB/Jakarta XML Binding
239+
240+
- Use `@XmlEnum` and `@XmlEnumValue` for enum mapping
241+
- Consider custom adapters for union types
242+
- Handle namespace differences between espi and customer schemas
243+
244+
---
245+
246+
*Generated from NAESB REQ.21 ESPI Version 4.0 schemas (December 2023)*

0 commit comments

Comments
 (0)