From 8fc7bc23bed821f8344d412568d83b543a1edbb7 Mon Sep 17 00:00:00 2001 From: "Donald F. Coffin" Date: Tue, 3 Feb 2026 23:08:47 -0500 Subject: [PATCH] docs: Add ESPI 4.0 schema analysis reports for enum implementation 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 --- .../00_SCHEMA_ANALYSIS_SUMMARY.md | 246 ++++ reports/verification/customer_enumerations.md | 1107 +++++++++++++++++ reports/verification/espi_enumerations.md | 836 +++++++++++++ 3 files changed, 2189 insertions(+) create mode 100644 reports/verification/00_SCHEMA_ANALYSIS_SUMMARY.md create mode 100644 reports/verification/customer_enumerations.md create mode 100644 reports/verification/espi_enumerations.md diff --git a/reports/verification/00_SCHEMA_ANALYSIS_SUMMARY.md b/reports/verification/00_SCHEMA_ANALYSIS_SUMMARY.md new file mode 100644 index 00000000..3b95184d --- /dev/null +++ b/reports/verification/00_SCHEMA_ANALYSIS_SUMMARY.md @@ -0,0 +1,246 @@ +# ESPI 4.0 Schema Analysis Summary + +**Analysis Date:** 2026-02-03 +**NAESB REQ.21 ESPI Version:** 4.0 +**Schema Publication Dates:** December 13-15, 2023 + +--- + +## Overview + +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. + +## Schema Files Analyzed + +| Schema | Namespace | Purpose | Report | +|--------|-----------|---------|--------| +| `espi.xsd` | `http://naesb.org/espi` | Energy usage data (UsagePoint, MeterReading, IntervalBlock, etc.) | [espi_enumerations.md](espi_enumerations.md) | +| `customer.xsd` | `http://naesb.org/espi/customer` | Customer/PII data (Customer, CustomerAccount, Meter, etc.) | [customer_enumerations.md](customer_enumerations.md) | + +--- + +## Combined Statistics + +| Category | espi.xsd | customer.xsd | Total | +|----------|----------|--------------|-------| +| Basic Types | 7 | 8 | 15 | +| String Types | 7 | 5 | 12 | +| Hex Binary Types | 4 | 4 | 8 | +| Special Types | 2 | 2 | 4 | +| Enumeration Types | 35 | 16 | 51 | +| Complex Types (Resources) | 12 | 15 | 27 | +| Complex Types (Supporting) | 17 | 30 | 47 | +| Global Elements | 20 | 45 | 65 | + +--- + +## Key Enumeration Types + +### Usage Domain (espi.xsd) + +| Enumeration | Values | Description | +|-------------|--------|-------------| +| AccumulationKind | 14 | How readings are accumulated (instantaneous, cumulative, delta, etc.) | +| CommodityKind | 14 | Type of commodity (electricity, gas, water, etc.) | +| Currency | 100+ | ISO 4217 currency codes | +| DataQualifierKind | 16 | Data quality indicators (average, maximum, minimum, etc.) | +| FlowDirectionKind | 21 | Direction of energy flow (forward, reverse, net, etc.) | +| MeasurementKind | 100+ | Type of measurement (energy, power, voltage, current, etc.) | +| PhaseCodeKind | 20+ | Electrical phase codes (A, B, C, AB, ABC, etc.) | +| QualityOfReading | 20+ | Reading quality indicators | +| ServiceKind | 11 | Type of utility service | +| TimeAttributeKind | 8 | Time period attributes (billing, seasonal, etc.) | +| UnitMultiplierKind | 16 | SI unit multipliers (kilo, mega, milli, etc.) | +| UnitSymbolKind | 100+ | Unit of measure symbols (W, Wh, VA, VAr, etc.) | + +### Customer Domain (customer.xsd) + +| Enumeration | Values | Description | +|-------------|--------|-------------| +| CustomerKind | 15 | Type of customer (residential, commercial, industrial, etc.) | +| SupplierKind | 6 | Type of service supplier (utility, municipality, etc.) | +| ServiceKind | 11 | Type of utility service | +| EnrollmentStatus | 5 | Program enrollment status | +| NotificationMethodKind | 5 | Customer notification methods | +| MeterMultiplierKind | 6 | Types of meter multipliers | +| RevenueKind | 7 | Types of revenue (fees, rates, rebates) | +| ProgramDateKind | 4 | Types of program dates | +| CRUDOperation | 4 | CRUD operation types | +| MediaType | 15 | MIME content types | +| StatusCode | 12+ | HTTP-style status codes | + +### OAuth Enumerations (espi.xsd) + +| Enumeration | Values | Description | +|-------------|--------|-------------| +| GrantType | 3 | OAuth 2.0 grant types | +| ResponseType | 1 | OAuth response types | +| TokenType | 1 | OAuth token types | +| OAuthError | 12 | OAuth error codes | +| TokenEndPointMethod | 1 | Token endpoint authentication methods | + +--- + +## Core Resource Types + +### Usage Domain Resources (espi.xsd) + +| Resource | Base Type | Description | +|----------|-----------|-------------| +| UsagePoint | IdentifiedObject | Logical point for energy measurement | +| MeterReading | IdentifiedObject | Collection of interval blocks | +| IntervalBlock | IdentifiedObject | Time-series interval data | +| IntervalReading | (inline) | Individual reading within an interval | +| ReadingType | IdentifiedObject | Metadata describing measurements | +| ElectricPowerQualitySummary | IdentifiedObject | Power quality metrics | +| UsageSummary | IdentifiedObject | Aggregated usage statistics | +| TimeConfiguration | IdentifiedObject | Timezone and DST settings | +| Authorization | IdentifiedObject | OAuth authorization record | +| ApplicationInformation | IdentifiedObject | Third-party application registration | +| Subscription | IdentifiedObject | Data subscription | +| RetailCustomer | IdentifiedObject | Retail customer (minimal) | + +### Customer Domain Resources (customer.xsd) + +| Resource | Base Type | Description | +|----------|-----------|-------------| +| Customer | Organisation | Full customer information | +| CustomerAccount | Document | Customer billing account | +| CustomerAgreement | Agreement | Service agreement | +| ServiceSupplier | Organisation | Utility or energy provider | +| ServiceLocation | WorkLocation | Physical service location | +| Meter | EndDevice | Physical meter device | +| EndDevice | AssetContainer | End device (base for Meter) | +| Statement | Document | Billing statement | +| DemandResponseProgram | IdentifiedObject | DR program enrollment | +| PricingStructure | Document | Pricing/rate structure | +| ProgramDateIdMappings | IdentifiedObject | Program date mappings | +| TimeConfiguration | IdentifiedObject | Timezone and DST settings | +| UsagePoint | IdentifiedObject | Usage point (customer context) | + +--- + +## Type Inheritance Hierarchy + +``` +Object +└── IdentifiedObject + ├── UsagePoint + ├── MeterReading + ├── IntervalBlock + ├── ReadingType + ├── ElectricPowerQualitySummary + ├── UsageSummary + ├── TimeConfiguration + ├── Authorization + ├── ApplicationInformation + ├── Subscription + ├── RetailCustomer + ├── DemandResponseProgram + ├── ProgramDateIdMappings + └── Document + ├── CustomerAccount + ├── PricingStructure + ├── Statement + └── Agreement + └── CustomerAgreement + +Organisation (extends IdentifiedObject) +├── Customer +└── ServiceSupplier + +Location (extends IdentifiedObject) +└── WorkLocation + └── ServiceLocation + +Asset (extends IdentifiedObject) +└── AssetContainer + └── EndDevice + └── Meter +``` + +--- + +## Common Patterns + +### Union Types for Enumerations + +ESPI uses a union pattern for numeric enumerations that allows both defined values and extended values: + +```xml + + + + + + + + + + + +``` + +### IdentifiedObject Base Type + +All major resources extend `IdentifiedObject` which provides: +- `description` (String512) - Human-readable description +- Extension capability from `Object` base type + +### Time Representation + +- All timestamps use `TimeType` (xs:long) as Unix epoch seconds +- Timezone handled via `TimeConfiguration` (tzOffset, dstOffset, dstStartRule, dstEndRule) +- Duration/intervals use `DateTimeInterval` (start, end, duration) + +### Monetary Values + +- Monetary amounts stored as `Int48` in smallest currency unit (cents/pence) +- Currency specified separately using ISO 4217 numeric codes + +--- + +## Schema Location + +The schema files are located at: +``` +openespi-common/src/main/resources/schema/ESPI_4.0/ +├── espi.xsd (usage/energy data) +└── customer.xsd (customer/PII data) +``` + +--- + +## Related Documentation + +- [ESPI Enumerations Report](espi_enumerations.md) - Detailed analysis of espi.xsd +- [Customer Enumerations Report](customer_enumerations.md) - Detailed analysis of customer.xsd +- [NAESB ESPI 4.0 Specification](https://www.naesb.org/) - Official specification + +--- + +## Implementation Notes + +### Java Enum Mapping + +When implementing Java enums for ESPI types: + +1. **Numeric enumerations** (UInt16 union) - Map to Java enum with integer value field +2. **String enumerations** - Map to Java enum with string value field +3. **Large enumerations** (100+ values) - Consider using lookup maps for efficiency + +### Validation Considerations + +1. **Union types** allow undefined numeric values - implement lenient parsing +2. **String length restrictions** must be enforced (String32, String256, etc.) +3. **HexBinary types** have specific byte length requirements + +### JAXB/Jakarta XML Binding + +- Use `@XmlEnum` and `@XmlEnumValue` for enum mapping +- Consider custom adapters for union types +- Handle namespace differences between espi and customer schemas + +--- + +*Generated from NAESB REQ.21 ESPI Version 4.0 schemas (December 2023)* diff --git a/reports/verification/customer_enumerations.md b/reports/verification/customer_enumerations.md new file mode 100644 index 00000000..56c57417 --- /dev/null +++ b/reports/verification/customer_enumerations.md @@ -0,0 +1,1107 @@ +# ESPI 4.0 Customer Schema Analysis Report + +**Schema Version:** NAESB REQ.21 ESPI Version 4.0.20231215 +**Published:** December 15, 2023 +**Namespace:** `http://naesb.org/espi/customer` + +--- + +## Table of Contents + +1. [Basic Types (Primitives)](#1-basic-types-primitives) +2. [String Types](#2-string-types) +3. [Hex Binary Types](#3-hex-binary-types) +4. [Special Types](#4-special-types) +5. [Enumeration Types](#5-enumeration-types) +6. [Complex Types (Resources)](#6-complex-types-resources) +7. [Complex Types (Supporting)](#7-complex-types-supporting) +8. [Global Elements](#8-global-elements) + +--- + +## 1. Basic Types (Primitives) + +| Type Name | Base Type | Description | Range/Restriction | +|-----------|-----------|-------------|-------------------| +| `UInt8` | `xs:unsignedByte` | Unsigned 8-bit integer | 0 to 255 (2^8-1) | +| `UInt16` | `xs:unsignedShort` | Unsigned 16-bit integer | 0 to 65,535 (2^16-1) | +| `UInt32` | `xs:unsignedInt` | Unsigned 32-bit integer | 0 to 4,294,967,295 (2^32-1) | +| `UInt48` | `xs:unsignedLong` | Unsigned 48-bit integer | 0 to 281,474,976,710,655 (2^48-1) | +| `Int16` | `xs:short` | Signed 16-bit integer | -32,768 to 32,767 | +| `Int48` | `xs:long` | Signed 48-bit integer | -140,737,488,355,328 to +140,737,488,355,328 | +| `TimeType` | `xs:long` | Unix timestamp (seconds since 1970-01-01) | Signed 64-bit | +| `PerCent` | `xs:float` | Percentage value | 0.0 to 100.0 | + +--- + +## 2. String Types + +| Type Name | Base Type | Max Length | Description | +|-----------|-----------|------------|-------------| +| `String32` | `xs:string` | 32 | Character string of max length 32 | +| `String64` | `xs:string` | 64 | Character string of max length 64 | +| `String256` | `xs:string` | 256 | Character string of max length 256 | +| `String512` | `xs:string` | 512 | Character string of max length 512 | +| `name` | `xs:normalizedString` | 64 | Normalized name string with pattern `[\s\S]*` | + +--- + +## 3. Hex Binary Types + +| Type Name | Base Type | Max Bytes | Bits | Description | +|-----------|-----------|-----------|------|-------------| +| `HexBinary8` | `xs:hexBinary` | 1 | 8 | 2 hex characters | +| `HexBinary16` | `xs:hexBinary` | 2 | 16 | 4 hex characters | +| `HexBinary32` | `xs:hexBinary` | 4 | 32 | 8 hex characters | +| `HexBinary128` | `xs:hexBinary` | 16 | 128 | 32 hex characters | + +--- + +## 4. Special Types + +| Type Name | Base Type | Pattern/Restriction | Description | +|-----------|-----------|---------------------|-------------| +| `UUIDType` | `xs:string` | `[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}` | UUID pattern | +| `DstRuleType` | `HexBinary32` | N/A | Bit-encoded DST rule | + +--- + +## 5. Enumeration Types + +### 5.1 Status and Operation Enumerations + +#### CRUDOperation +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | Created | Resource was created | +| 1 | Deleted | Resource was deleted | +| 2 | Updated | Resource was updated | +| 3 | Unspecified | Operation unspecified | + +--- + +#### EnrollmentStatus +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | Enrolled | Customer is enrolled | +| 1 | EnrollmentPending | Enrollment is pending | +| 2 | UnEnrolled | Customer is not enrolled | +| 3 | UnEnrolledPending | Unenrollment is pending | +| 4 | Enrolling | Customer is in process of enrolling | + +--- + +#### StatusCode +**Base:** `String32` + +HTTP-style status codes for ESPI operations. + +| Value | Description | +|-------|-------------| +| `100` | Continue | +| `200` | OK - Successful request | +| `201` | Created - Resource created | +| `204` | No Content | +| `301` | Moved Permanently | +| `400` | Bad Request | +| `401` | Unauthorized | +| `403` | Forbidden | +| `404` | Not Found | +| `500` | Internal Server Error | +| `501` | Not Implemented | +| `503` | Service Unavailable | + +--- + +### 5.2 Customer and Service Enumerations + +#### CustomerKind +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | energyServiceScheduler | Energy service scheduler customer | +| 1 | energyServiceSupplier | Energy service supplier customer | +| 2 | other | Other customer type | +| 3 | commercialIndustrial | Commercial or industrial customer | +| 4 | internalUse | Internal use customer | +| 5 | pumpingLoad | Pumping load customer | +| 6 | residential | Residential customer | +| 7 | residentialAndCommercial | Residential and commercial customer | +| 8 | residentialAndStreetlight | Residential and streetlight customer | +| 9 | residentialFarmService | Residential farm service customer | +| 10 | residentialStreetlightOthers | Residential streetlight and others | +| 11 | streetLight | Streetlight customer | +| 12 | energyServiceConsumer | Energy service consumer | +| 13 | gridOperator | Grid operator | +| 14 | windMachine | Wind machine customer | + +--- + +#### SupplierKind +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | utility | Traditional utility supplier | +| 1 | municipality | Municipal utility | +| 2 | privateEnterprise | Private enterprise supplier | +| 3 | cooperative | Cooperative utility | +| 4 | retailer | Retail energy supplier | +| 5 | other | Other supplier type | + +--- + +#### ServiceKind +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | electricity | Electric service | +| 1 | gas | Natural gas service | +| 2 | water | Water service | +| 3 | time | Time service | +| 4 | heat | Heat service | +| 5 | refuse | Refuse/waste service | +| 6 | sewerage | Sewerage service | +| 7 | rates | Rates information | +| 8 | tvLicense | TV license service | +| 9 | internet | Internet service | +| 10 | other | Other service type | + +--- + +#### RevenueKind +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | fees | Revenue from fees | +| 1 | rates | Revenue from rates | +| 2 | cancellationFees | Revenue from cancellation fees | +| 3 | lateFees | Revenue from late fees | +| 4 | connectorFees | Revenue from connector fees | +| 5 | rebates | Rebates (negative revenue) | +| 6 | other | Other revenue type | + +--- + +### 5.3 Notification and Communication Enumerations + +#### NotificationMethodKind +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | email | Notification via email | +| 1 | inPerson | In-person notification | +| 2 | phone | Notification via phone call | +| 3 | postal | Notification via postal mail | +| 4 | sms | Notification via SMS text message | + +--- + +#### MediaType +**Base:** `String64` + +MIME media types for content negotiation. + +| Value | Description | +|-------|-------------| +| `application/atom+xml` | Atom XML feed | +| `application/pdf` | PDF document | +| `application/xml` | Generic XML | +| `application/json` | JSON data | +| `application/octet-stream` | Binary data | +| `text/html` | HTML document | +| `text/plain` | Plain text | +| `text/xml` | XML text | +| `image/gif` | GIF image | +| `image/jpeg` | JPEG image | +| `image/png` | PNG image | +| `application/vnd.ms-excel` | Excel spreadsheet | +| `application/zip` | ZIP archive | +| `multipart/form-data` | Form data | +| `text/csv` | CSV data | + +--- + +### 5.4 Program and Date Enumerations + +#### ProgramDateKind +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | signUp | Sign-up date | +| 1 | cancel | Cancellation date | +| 2 | enroll | Enrollment date | +| 3 | deferred | Deferred date | + +--- + +### 5.5 Meter and Measurement Enumerations + +#### MeterMultiplierKind +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | kH | Test dial multiplier | +| 1 | kE | Element test multiplier | +| 2 | kP | Potential transformer multiplier | +| 3 | kC | Current transformer multiplier | +| 4 | kR | Register multiplier | +| 5 | transformerRatio | Transformer ratio | + +--- + +#### UnitMultiplierKind +**Base:** `Int16` (union) + +SI unit multipliers as powers of 10. + +| Value | Name | Symbol | Multiplier | +|-------|------|--------|------------| +| -12 | pico | p | 10^-12 | +| -9 | nano | n | 10^-9 | +| -6 | micro | µ | 10^-6 | +| -3 | milli | m | 10^-3 | +| -2 | centi | c | 10^-2 | +| -1 | deci | d | 10^-1 | +| 0 | none | (none) | 10^0 = 1 | +| 1 | deca | da | 10^1 | +| 2 | hecto | h | 10^2 | +| 3 | kilo | k | 10^3 | +| 6 | mega | M | 10^6 | +| 9 | giga | G | 10^9 | +| 12 | tera | T | 10^12 | +| 15 | peta | P | 10^15 | +| 18 | exa | E | 10^18 | +| 21 | yotta | Y | 10^21 | + +--- + +#### UnitSymbolKind +**Base:** `UInt16` (union) + +Unit of measurement symbols. Comprehensive list of 100+ unit types. + +##### SI Base Units +| Value | Symbol | Description | +|-------|--------|-------------| +| 5 | A | Ampere - Electric current | +| 2 | m | Meter - Length | +| 6 | K | Kelvin - Temperature | +| 7 | mol | Mole - Amount of substance | +| 8 | cd | Candela - Luminous intensity | +| 1 | s | Second - Time | + +##### Power and Energy +| Value | Symbol | Description | +|-------|--------|-------------| +| 38 | W | Watt - Real power | +| 61 | VA | Volt-ampere - Apparent power | +| 63 | VAr | Volt-ampere reactive - Reactive power | +| 64 | Varh | Volt-ampere-reactive hour - Reactive energy | +| 72 | Wh | Watt-hour - Real energy | +| 71 | VAh | Volt-ampere-hour - Apparent energy | +| 132 | btu | BTU - British Thermal Units | +| 133 | btuPerH | BTU/h - BTU per hour | +| 169 | therm | Therm - Energy | + +##### Electrical +| Value | Symbol | Description | +|-------|--------|-------------| +| 29 | V | Volt - Electric potential | +| 30 | ohm | Ohm - Resistance | +| 31 | F | Farad - Capacitance | +| 32 | H | Henry - Inductance | +| 33 | S | Siemens - Conductance | +| 69 | A2 | Ampere squared | +| 105 | A2h | Ampere-squared hour | +| 106 | Ah | Ampere-hour | +| 67 | V2 | Volt squared | +| 104 | V2h | Volt-squared hour | + +##### Frequency and Angular +| Value | Symbol | Description | +|-------|--------|-------------| +| 27 | Hz | Hertz - Frequency | +| 10 | rad | Radian - Plane angle | +| 11 | sr | Steradian - Solid angle | +| 54 | radPerSec | Radians per second - Angular velocity | +| 75 | HzPerSec | Hertz per second - Rate of change of frequency | +| 154 | rev | Revolutions | +| 4 | revPerSec | Revolutions per second | + +##### Force, Pressure, and Mass +| Value | Symbol | Description | +|-------|--------|-------------| +| 3 | kg | Kilogram - Mass | +| 25 | N | Newton - Force | +| 26 | Pa | Pascal - Pressure | +| 140 | paG | Pascal gauge pressure | +| 155 | paA | Pascal absolute pressure | +| 141 | psiA | PSI absolute | +| 142 | psiG | PSI gauge | +| 23 | J | Joule - Energy/Work | +| 165 | jPerKg | Joules per kilogram | + +##### Volume and Flow +| Value | Symbol | Description | +|-------|--------|-------------| +| 41 | m2 | Square meter - Area | +| 42 | m3 | Cubic meter - Volume | +| 119 | ft3 | Cubic feet | +| 120 | ft3compensated | Cubic feet compensated | +| 128 | usGal | US gallons | +| 130 | imperialGal | Imperial gallons | +| 134 | litre | Litre | +| 156 | litreUncompensated | Litre uncompensated | +| 157 | litreCompensated | Litre compensated | +| 45 | m3PerSec | Cubic meters per second | +| 125 | m3PerH | Cubic meters per hour | +| 82 | litrePerSec | Litres per second | +| 137 | litrePerH | Litres per hour | + +##### Power Factor and Ratios +| Value | Symbol | Description | +|-------|--------|-------------| +| 65 | cosTheta | Power factor (cos θ) | +| 153 | WPerVA | Power factor (W/VA) | +| 148 | mPerM | Ratio of length | +| 150 | HzPerHz | Ratio of frequency | +| 151 | VPerV | Ratio of voltages | +| 152 | APerA | Ratio of current | +| 168 | WPerW | Ratio of power | + +##### Temperature and Thermal +| Value | Symbol | Description | +|-------|--------|-------------| +| 23 | degC | Degree Celsius | +| 50 | wPerMK | Thermal conductivity (W/m·K) | +| 51 | jPerK | Heat capacity (J/K) | + +##### Magnetic +| Value | Symbol | Description | +|-------|--------|-------------| +| 36 | wb | Weber - Magnetic flux | +| 37 | t | Tesla - Magnetic flux density | + +##### Miscellaneous +| Value | Symbol | Description | +|-------|--------|-------------| +| 0 | none | Not applicable | +| 76 | char | Characters | +| 77 | charPerSec | Characters per second | +| 80 | money | Generic monetary unit | +| 108 | timeStamp | ISO 8601 timestamp | +| 109 | status | Status (boolean-like) | +| 111 | count | Counter value | +| 114 | code | Encoded application value | +| 118 | meCode | EndDeviceEventCode | + +##### Metering Constants +| Value | Symbol | Description | +|-------|--------|-------------| +| 115 | WhPerRev | Active energy metering constant | +| 116 | VArhPerRev | Reactive energy metering constant | +| 117 | VAhPerRev | Apparent energy metering constant | +| 107 | WhPerM3 | Energy per volume | + +--- + +#### Currency +**Base:** `UInt16` (union) + +ISO 4217 currency codes (numeric). Selected common values: + +| Value | Code | Description | +|-------|------|-------------| +| 36 | AUD | Australian Dollar | +| 124 | CAD | Canadian Dollar | +| 156 | CNY | Chinese Yuan | +| 208 | DKK | Danish Krone | +| 978 | EUR | Euro | +| 826 | GBP | British Pound Sterling | +| 344 | HKD | Hong Kong Dollar | +| 356 | INR | Indian Rupee | +| 392 | JPY | Japanese Yen | +| 484 | MXN | Mexican Peso | +| 578 | NOK | Norwegian Krone | +| 554 | NZD | New Zealand Dollar | +| 752 | SEK | Swedish Krona | +| 756 | CHF | Swiss Franc | +| 840 | USD | United States Dollar | + +--- + +## 6. Complex Types (Resources) + +### 6.1 Core Resource Types + +#### Customer +**Extends:** `Organisation` + +Organization receiving services from a utility. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| kind | CustomerKind | 0..1 | Type of customer | +| specialNeed | String256 | 0..1 | Special needs of customer | +| vip | xs:boolean | 0..1 | VIP status flag | +| pucNumber | String256 | 0..1 | Public utility commission number | +| status | Status | 0..1 | Customer status | +| locale | String32 | 0..1 | Customer locale | + +--- + +#### CustomerAccount +**Extends:** `Document` + +Assignment of a group of products and services purchased by a customer. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| accountId | String64 | 0..1 | Legacy account identifier | +| billingCycle | String32 | 0..1 | Billing cycle designation | +| budgetBill | String32 | 0..1 | Budget billing program code | +| lastBillAmount | Int48 | 0..1 | Amount of last bill in cents | +| contactInfo | String512 | 0..1 | Contact information | +| notifications | AccountNotification | 0..* | Account notifications | + +--- + +#### CustomerAgreement +**Extends:** `Agreement` + +Agreement between customer and service supplier for services. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| loadMgmt | String256 | 0..1 | Load management code | +| isPrePay | xs:boolean | 0..1 | Prepay customer flag | +| shutOffDateTime | TimeType | 0..1 | Scheduled shutoff date/time | +| demandResponseProgram | DemandResponseProgram | 0..* | Demand response programs | +| pricingStructure | PricingStructure | 0..* | Pricing structures | +| status | Status | 0..1 | Agreement status | + +--- + +#### ServiceSupplier +**Extends:** `Organisation` + +Organization that provides services to customers. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| kind | SupplierKind | 0..1 | Type of supplier | +| issuerIdentificationNumber | String64 | 0..1 | IIN for payment cards | +| effectiveDate | TimeType | 0..1 | Date supplier became effective | + +--- + +#### ServiceLocation +**Extends:** `WorkLocation` + +Location of a customer's meter or service point. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| accessMethod | String256 | 0..1 | Method to access location | +| needsInspection | xs:boolean | 0..1 | Inspection needed flag | +| siteAccessProblem | String256 | 0..1 | Access problem description | +| usagePoint | UsagePoint | 0..* | Associated usage points | + +--- + +### 6.2 Device and Meter Types + +#### EndDevice +**Extends:** `AssetContainer` + +Asset that performs end device functions (metering, load control). + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| amrSystem | String256 | 0..1 | AMR system identifier | +| installCode | String256 | 0..1 | Installation code | +| isPan | xs:boolean | 0..1 | Part of PAN flag | +| isSmartInverter | xs:boolean | 0..1 | Smart inverter flag | +| isVirtual | xs:boolean | 0..1 | Virtual device flag | +| timeZoneOffset | Int16 | 0..1 | Timezone offset in minutes | + +--- + +#### Meter +**Extends:** `EndDevice` + +Physical meter device with associated multipliers. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| formNumber | String256 | 0..1 | Meter form number | +| meterMultipliers | MeterMultiplier | 0..* | Meter multipliers | + +--- + +### 6.3 Program and Billing Types + +#### DemandResponseProgram +**Extends:** `IdentifiedObject` + +Demand response program that customers can enroll in. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| availabilityDate | DateTimeInterval | 0..1 | Availability period | +| programName | String256 | 0..1 | Program name | +| programDescription | String512 | 0..1 | Program description | +| enrollmentStatus | EnrollmentStatus | 0..1 | Enrollment status | +| capacityReservationLevel | SummaryMeasurement | 0..1 | Reserved capacity | +| DRProgramMandatoryLevel | SummaryMeasurement | 0..1 | Mandatory participation level | +| programDates | ProgramDate | 0..* | Program dates | + +--- + +#### PricingStructure +**Extends:** `Document` + +Pricing structure for services. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| code | String32 | 0..1 | Pricing code | +| revenueKind | RevenueKind | 0..1 | Revenue type | +| taxExemption | xs:boolean | 0..1 | Tax exemption flag | +| dailyFloorUsage | Int48 | 0..1 | Daily floor usage | +| dailyCeilingUsage | Int48 | 0..1 | Daily ceiling usage | +| dailyEstimatedUsage | Int48 | 0..1 | Daily estimated usage | + +--- + +#### Statement +**Extends:** `Document` + +Billing statement for a customer account. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| statementDate | TimeType | 0..1 | Statement date | +| dueDate | TimeType | 0..1 | Payment due date | +| amountDue | Int48 | 0..1 | Amount due in cents | +| previousBalance | Int48 | 0..1 | Previous balance | +| currentBalance | Int48 | 0..1 | Current balance | + +--- + +#### ProgramDateIdMappings +**Extends:** `IdentifiedObject` + +Container for program date ID mappings. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| programDateIdMapping | ProgramDateIdMapping | 0..* | Individual mappings | + +--- + +### 6.4 Time Configuration + +#### TimeConfiguration +**Extends:** `IdentifiedObject` + +Time zone and DST configuration (also known as LocalTimeParameters). + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| dstEndRule | DstRuleType | 1 | DST end rule (hex encoded) | +| dstOffset | Int48 | 1 | DST offset in seconds | +| dstStartRule | DstRuleType | 1 | DST start rule (hex encoded) | +| tzOffset | Int48 | 1 | Timezone offset in seconds | + +--- + +### 6.5 Usage Point Types + +#### UsagePoint +**Extends:** `IdentifiedObject` + +Logical point on the network for measurement (reference to usage.xsd). + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| roleFlags | HexBinary16 | 0..1 | Role flags | +| serviceCategory | ServiceKind | 0..1 | Service category | +| status | UInt16 | 0..1 | Status | +| ServiceDeliveryPoint | ServiceDeliveryPoint | 0..1 | Service delivery point | + +--- + +#### UsagePoints +**Type:** Complex (list container) + +Container for multiple usage points. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| usagePoint | UsagePoint | 0..* | List of usage points | + +--- + +## 7. Complex Types (Supporting) + +### 7.1 Base Types + +#### Object +Base type for all ESPI objects. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| extension | String512 | 0..1 | Extension data | + +--- + +#### IdentifiedObject +**Extends:** `Object` + +Base type for identified resources. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| description | String512 | 0..1 | Description | + +--- + +#### Document +**Extends:** `IdentifiedObject` + +Parent type for document resources. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| createdDateTime | TimeType | 0..1 | Creation timestamp | +| lastModifiedDateTime | TimeType | 0..1 | Last modification timestamp | + +--- + +#### Agreement +**Extends:** `Document` + +Formal agreement for services. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| signDate | TimeType | 0..1 | Date agreement was signed | +| validityInterval | DateTimeInterval | 0..1 | Validity period | + +--- + +### 7.2 Organisation Types + +#### Organisation +**Extends:** `IdentifiedObject` + +Organization participating in the utility domain. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| phone1 | TelephoneNumber | 0..1 | Primary phone | +| phone2 | TelephoneNumber | 0..1 | Secondary phone | +| streetAddress | StreetAddress | 0..1 | Street address | +| postalAddress | StreetAddress | 0..1 | Postal address | +| electronicAddress | ElectronicAddress | 0..1 | Electronic address | + +--- + +#### OrganisationRole +**Extends:** `IdentifiedObject` + +Role played by an organization. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| organisation | Organisation | 0..1 | Associated organization | + +--- + +### 7.3 Asset Types + +#### Asset +**Extends:** `IdentifiedObject` + +Physical asset owned by an organization. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| utcNumber | String256 | 0..1 | UTC asset number | +| serialNumber | String256 | 0..1 | Serial number | +| lotNumber | String256 | 0..1 | Lot number | +| purchasePrice | Int48 | 0..1 | Purchase price in cents | +| lifecycle | LifecycleDate | 0..1 | Lifecycle dates | +| acceptanceTest | AcceptanceTest | 0..1 | Acceptance test data | + +--- + +#### AssetContainer +**Extends:** `Asset` + +Asset that contains other assets. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| (inherits from Asset) | | | | + +--- + +### 7.4 Location Types + +#### Location +**Extends:** `IdentifiedObject` + +Geographic location. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| type | String256 | 0..1 | Location type | +| mainAddress | StreetAddress | 0..1 | Main address | +| phone1 | TelephoneNumber | 0..1 | Primary phone | +| phone2 | TelephoneNumber | 0..1 | Secondary phone | +| secondaryAddress | StreetAddress | 0..1 | Secondary address | +| electronicAddress | ElectronicAddress | 0..1 | Electronic address | +| geoInfoReference | String256 | 0..1 | GIS reference | +| direction | String256 | 0..1 | Directions | +| status | Status | 0..1 | Location status | +| positionPoints | PositionPoint | 0..* | Geographic coordinates | + +--- + +#### WorkLocation +**Extends:** `Location` + +Location for work purposes. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| oneCallContact | String256 | 0..1 | One-call contact info | + +--- + +#### PositionPoint +Geographic coordinate point. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| xPosition | String32 | 0..1 | X coordinate (longitude) | +| yPosition | String32 | 0..1 | Y coordinate (latitude) | +| zPosition | String32 | 0..1 | Z coordinate (elevation) | + +--- + +### 7.5 Address Types + +#### StreetAddress +Postal street address. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| streetDetail | StreetDetail | 0..1 | Street details | +| townDetail | TownDetail | 0..1 | Town details | +| poBox | String256 | 0..1 | PO Box number | +| postalCode | String256 | 0..1 | Postal code | +| status | Status | 0..1 | Address status | + +--- + +#### StreetDetail +Street address details. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| addressGeneral | String256 | 0..1 | General address | +| addressGeneral2 | String256 | 0..1 | Additional address | +| addressGeneral3 | String256 | 0..1 | Additional address | +| buildingName | String256 | 0..1 | Building name | +| code | String64 | 0..1 | Street code | +| name | String256 | 0..1 | Street name | +| number | String64 | 0..1 | Street number | +| prefix | String64 | 0..1 | Street prefix | +| suffix | String64 | 0..1 | Street suffix | +| suiteNumber | String64 | 0..1 | Suite number | +| type | String64 | 0..1 | Street type | +| withinTownLimits | xs:boolean | 0..1 | Within town limits flag | +| floorIdentification | String32 | 0..1 | Floor identifier | + +--- + +#### TownDetail +Town/city address details. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| code | String64 | 0..1 | Town code | +| country | String256 | 0..1 | Country | +| name | String256 | 0..1 | Town name | +| section | String256 | 0..1 | Town section | +| stateOrProvince | String256 | 0..1 | State or province | + +--- + +### 7.6 Contact Types + +#### TelephoneNumber +Telephone contact information. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| areaCode | String32 | 0..1 | Area code | +| cityCode | String32 | 0..1 | City code | +| countryCode | String32 | 0..1 | Country code | +| extension | String32 | 0..1 | Extension | +| localNumber | String32 | 0..1 | Local number | +| dialOut | String32 | 0..1 | Dial-out prefix | +| ituPhone | String32 | 0..1 | ITU phone number | +| internationalPrefix | String32 | 0..1 | International prefix | + +--- + +#### ElectronicAddress +Electronic contact information. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| email1 | String256 | 0..1 | Primary email | +| email2 | String256 | 0..1 | Secondary email | +| lan | String256 | 0..1 | LAN address | +| mac | String256 | 0..1 | MAC address | +| radio | String256 | 0..1 | Radio address | +| userID | String256 | 0..1 | User ID | +| web | String256 | 0..1 | Web address | +| password | String256 | 0..1 | Password | + +--- + +### 7.7 Other Supporting Types + +#### DateTimeInterval +Time interval with start and end. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| start | TimeType | 0..1 | Start time | +| end | TimeType | 0..1 | End time | +| duration | UInt32 | 0..1 | Duration in seconds | + +--- + +#### Status +General status information. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| value | String256 | 0..1 | Status value | +| dateTime | TimeType | 0..1 | Status timestamp | +| reason | String256 | 0..1 | Status reason | +| remark | String512 | 0..1 | Additional remarks | + +--- + +#### Priority +Priority information. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| justification | String512 | 0..1 | Priority justification | +| rank | UInt32 | 0..1 | Priority rank | +| type | String64 | 0..1 | Priority type | + +--- + +#### MeterMultiplier +Meter multiplier values. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| kind | MeterMultiplierKind | 0..1 | Multiplier type | +| value | xs:float | 0..1 | Multiplier value | + +--- + +#### AcceptanceTest +Asset acceptance test data. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| dateTime | TimeType | 0..1 | Test date/time | +| success | xs:boolean | 0..1 | Test success flag | +| type | String256 | 0..1 | Test type | + +--- + +#### LifecycleDate +Asset lifecycle dates. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| installationDate | TimeType | 0..1 | Installation date | +| manufacturedDate | TimeType | 0..1 | Manufacture date | +| purchaseDate | TimeType | 0..1 | Purchase date | +| receivedDate | TimeType | 0..1 | Received date | +| removalDate | TimeType | 0..1 | Removal date | +| retiredDate | TimeType | 0..1 | Retirement date | + +--- + +#### SummaryMeasurement +Summary measurement value. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| value | Int48 | 0..1 | Measurement value | +| powerOfTenMultiplier | UnitMultiplierKind | 0..1 | Power of 10 multiplier | +| uom | UnitSymbolKind | 0..1 | Unit of measure | + +--- + +#### AccountNotification +Account notification record. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| methodKind | NotificationMethodKind | 0..1 | Notification method | +| note | String512 | 0..1 | Notification content | +| time | TimeType | 0..1 | Notification time | +| customerNotificationKind | String256 | 0..1 | Customer notification type | + +--- + +#### ProgramDate +Date associated with a program. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| programDateKind | ProgramDateKind | 0..1 | Date type | +| date | TimeType | 0..1 | Date value | + +--- + +#### ProgramDateIdMapping +Mapping of program date to identifier. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| programDate | ProgramDate | 0..1 | Program date | +| id | String256 | 0..1 | Identifier | +| programDescription | String512 | 0..1 | Program description | + +--- + +#### BatchItemInfo +Batch operation item information. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| name | String256 | 0..1 | Item name | +| operation | CRUDOperation | 0..1 | CRUD operation | +| statusCode | StatusCode | 0..1 | Status code | +| statusReason | String512 | 0..1 | Status reason | + +--- + +#### BatchListType +List of batch items. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| resource | String512 | 0..* | Resource URIs | + +--- + +#### StatementRef +Reference to a statement. + +| Element | Type | Occurrence | Description | +|---------|------|------------|-------------| +| href | String512 | 0..1 | Statement reference URI | + +--- + +## 8. Global Elements + +The customer.xsd schema defines 45 global elements: + +### Resource Elements +| Element | Type | Description | +|---------|------|-------------| +| Customer | Customer | Customer resource | +| CustomerAccount | CustomerAccount | Customer account resource | +| CustomerAgreement | CustomerAgreement | Customer agreement resource | +| EndDevice | EndDevice | End device resource | +| Meter | Meter | Meter device resource | +| ServiceLocation | ServiceLocation | Service location resource | +| ServiceSupplier | ServiceSupplier | Service supplier resource | +| Statement | Statement | Billing statement resource | +| ProgramDateIdMappings | ProgramDateIdMappings | Program date mappings resource | +| DemandResponseProgram | DemandResponseProgram | DR program resource | +| PricingStructure | PricingStructure | Pricing structure resource | +| UsagePoint | UsagePoint | Usage point resource | +| UsagePoints | UsagePoints | Usage points list | +| TimeConfiguration | TimeConfiguration | Time configuration | +| LocalTimeParameters | TimeConfiguration | Local time parameters (alias) | + +### Supporting Type Elements +| Element | Type | Description | +|---------|------|-------------| +| AcceptanceTest | AcceptanceTest | Acceptance test data | +| AccountNotification | AccountNotification | Account notification | +| Agreement | Agreement | Agreement base type | +| Asset | Asset | Asset base type | +| AssetContainer | AssetContainer | Asset container | +| BatchItemInfo | BatchItemInfo | Batch item info | +| BatchList | BatchListType | Batch list | +| DateTimeInterval | DateTimeInterval | Time interval | +| Document | Document | Document base type | +| ElectronicAddress | ElectronicAddress | Electronic address | +| IdentifiedObject | IdentifiedObject | Identified object base | +| LifecycleDate | LifecycleDate | Lifecycle dates | +| Location | Location | Location base type | +| MeterMultiplier | MeterMultiplier | Meter multiplier | +| Object | Object | Object base type | +| Organisation | Organisation | Organisation type | +| OrganisationRole | OrganisationRole | Organisation role | +| PositionPoint | PositionPoint | Geographic point | +| Priority | Priority | Priority info | +| ProgramDate | ProgramDate | Program date | +| ProgramDateIdMapping | ProgramDateIdMapping | Program date mapping | +| Status | Status | Status info | +| StatementRef | StatementRef | Statement reference | +| StreetAddress | StreetAddress | Street address | +| StreetDetail | StreetDetail | Street details | +| SummaryMeasurement | SummaryMeasurement | Summary measurement | +| TelephoneNumber | TelephoneNumber | Phone number | +| TownDetail | TownDetail | Town details | +| WorkLocation | WorkLocation | Work location | + +--- + +## Summary Statistics + +| Category | Count | +|----------|-------| +| Basic Types (Primitives) | 8 | +| String Types | 5 | +| Hex Binary Types | 4 | +| Special Types | 2 | +| Enumeration Types | 16 | +| Complex Types (Resources) | 15 | +| Complex Types (Supporting) | 30 | +| Global Elements | 45 | + +--- + +*Generated from NAESB REQ.21 ESPI Version 4.0.20231215 customer.xsd schema* diff --git a/reports/verification/espi_enumerations.md b/reports/verification/espi_enumerations.md new file mode 100644 index 00000000..eebd5e80 --- /dev/null +++ b/reports/verification/espi_enumerations.md @@ -0,0 +1,836 @@ +# ESPI 4.0 Schema Analysis Report + +**Schema Version:** NAESB REQ.21 ESPI Version 4.0.20231213 +**Published:** December 13, 2023 +**Namespace:** `http://naesb.org/espi` + +--- + +## Table of Contents + +1. [Basic Types (Primitives)](#1-basic-types-primitives) +2. [String Types](#2-string-types) +3. [Hex Binary Types](#3-hex-binary-types) +4. [Special Types](#4-special-types) +5. [Enumeration Types](#5-enumeration-types) +6. [Complex Types (Resources)](#6-complex-types-resources) +7. [Complex Types (Supporting)](#7-complex-types-supporting) +8. [Global Elements](#8-global-elements) + +--- + +## 1. Basic Types (Primitives) + +| Type Name | Base Type | Description | Range/Restriction | +|-----------|-----------|-------------|-------------------| +| `UInt8` | `xs:unsignedByte` | Unsigned 8-bit integer | 0 to 255 (2^8-1) | +| `UInt16` | `xs:unsignedShort` | Unsigned 16-bit integer | 0 to 65,535 (2^16-1) | +| `UInt32` | `xs:unsignedInt` | Unsigned 32-bit integer | 0 to 4,294,967,295 (2^32-1) | +| `UInt48` | `xs:unsignedLong` | Unsigned 48-bit integer | 0 to 281,474,976,710,655 (2^48-1) | +| `Int16` | `xs:short` | Signed 16-bit integer | -32,768 to 32,767 | +| `Int48` | `xs:long` | Signed 48-bit integer | -140,737,488,355,328 to +140,737,488,355,328 | +| `TimeType` | `xs:long` | Unix timestamp (seconds since 1970-01-01) | Signed 64-bit | + +--- + +## 2. String Types + +| Type Name | Base Type | Max Length | Description | +|-----------|-----------|------------|-------------| +| `String4` | `xs:string` | 4 | Character string of max length 4 | +| `String8` | `xs:string` | 8 | Character string of max length 8 | +| `String16` | `xs:string` | 16 | Character string of max length 16 | +| `String32` | `xs:string` | 32 | Character string of max length 32 | +| `String64` | `xs:string` | 64 | Character string of max length 64 | +| `String256` | `xs:string` | 256 | Character string of max length 256 | +| `String512` | `xs:string` | 512 | Character string of max length 512 [extension] | + +--- + +## 3. Hex Binary Types + +| Type Name | Base Type | Max Bytes | Bits | Description | +|-----------|-----------|-----------|------|-------------| +| `HexBinary8` | `xs:hexBinary` | 1 | 8 | 2 hex characters | +| `HexBinary16` | `xs:hexBinary` | 2 | 16 | 4 hex characters | +| `HexBinary32` | `xs:hexBinary` | 4 | 32 | 8 hex characters | +| `HexBinary128` | `xs:hexBinary` | 16 | 128 | 32 hex characters | + +--- + +## 4. Special Types + +| Type Name | Base Type | Pattern/Restriction | Description | +|-----------|-----------|---------------------|-------------| +| `UUIDType` | `xs:string` | `[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}` | UUID pattern | +| `DstRuleType` | `HexBinary32` | N/A | Bit-encoded DST rule (see detailed specification) | + +--- + +## 5. Enumeration Types + +### 5.1 OAuth Enumerations + +#### TokenEndPointMethod +**Base:** `String32` + +| Value | Description | +|-------|-------------| +| `client_secret_basic` | HTTP Basic authentication (RFC 6749 Section 2.3.1) | + +#### GrantType +**Base:** `String32` + +| Value | Description | +|-------|-------------| +| `authorization_code` | OAuth 2.0 Authorization Code Grant flow (RFC 6749 Section 4.1) | +| `client_credentials` | OAuth 2.0 Client Credentials Grant flow (RFC 6749 Section 4.4) | +| `refresh_token` | OAuth 2.0 Refresh Token flow (RFC 6749 Section 6) | + +#### ResponseType +**Base:** `String32` + +| Value | Description | +|-------|-------------| +| `code` | Request for authorization code (RFC 6749 Section 4.1.1) | + +#### TokenType +**Base:** `String32` + +| Value | Description | +|-------|-------------| +| `Bearer` | Bearer token (RFC6750 Section 1.2) | + +#### OAuthError +**Base:** `String32` + +| Value | Description | +|-------|-------------| +| `invalid_request` | Missing/unsupported parameter, malformed request | +| `invalid_client` | Client authentication failed | +| `invalid_grant` | Invalid/expired authorization code or refresh token | +| `unauthorized_client` | Client not authorized for grant type | +| `unsupported_grant_type` | Grant type not supported | +| `invalid_scope` | Invalid/unknown/malformed scope | +| `invalid_redirect_uri` | Invalid redirection URI | +| `invalid_client_metadata` | Invalid client metadata field | +| `invalid_client_id` | [DEPRECATED] Client authentication failed | +| `access_denied` | Resource owner denied request | +| `unsupported_response_type` | Response type not supported | +| `server_error` | Unexpected server error | +| `temporarily_unavailable` | Server temporarily unavailable | + +--- + +### 5.2 ESPI Enumerations (Numeric) + +#### ItemKind +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 1 | Energy Generation Fee | A charge for generation of energy | +| 2 | Energy Delivery Fee | A charge for delivery of energy | +| 3 | Energy Usage Fee | A charge for electricity, natural gas, water consumption | +| 4 | Administrative Fee | A fee for administrative services | +| 5 | Tax | A local, state, or federal energy tax | +| 6 | Energy Generation Credit | A credit, discount or rebate for generation | +| 7 | Energy Delivery Credit | A credit, discount or rebate for delivery | +| 8 | Administrative Credit | A credit, discount or rebate for administrative services | +| 9 | Payment | A payment for previous billing | +| 10 | Information | An informational line item | + +--- + +#### AccumulationKind +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | none | Not Applicable or implied by unit of measure | +| 1 | bulkQuantity | Bulk quantity from register (dial reading) | +| 2 | continuousCumulative | Sum of previous + present period values | +| 3 | cumulative | Sum of previous billing period values | +| 4 | deltaData | Difference between end and beginning of interval | +| 6 | indicating | Needle swing value (measured over hundreds of ms) | +| 9 | summation | Selective accumulation with respect to time | +| 10 | timeDelay | Computation with time delay characteristic | +| 12 | instantaneous | Measured over fastest period (milliseconds) | +| 13 | latchingQuantity | Time-independent cumulative that latches at max/min | +| 14 | boundedQuantity | Accumulation that stops at max/min bounds | + +--- + +#### CommodityKind +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | none | Not Applicable | +| 1 | electricitySecondaryMetered | Secondary metered electricity | +| 2 | electricityPrimaryMetered | Primary metered electricity (with external VT/CT) | +| 3 | communication | Communication infrastructure measurement | +| 4 | air | Air | +| 5 | insulativeGas | Insulative Gas | +| 6 | insulativeOil | Insulative Oil | +| 7 | naturalGas | Natural Gas | +| 8 | propane | Propane C3H8 | +| 9 | potableWater | Drinkable water | +| 10 | steam | Steam (usually for heating) | +| 11 | wasteWater | Waste Water (Sewerage) | +| 12 | heatingFluid | Heating fluid (liquid form) | +| 13 | coolingFluid | Cooling fluid | +| 14 | nonpotableWater | Reclaimed/irrigation water | +| 15 | nox | Nitrous Oxides NOX | +| 16 | so2 | Sulfur Dioxide SO2 | +| 17 | ch4 | Methane CH4 | +| 18 | co2 | Carbon Dioxide CO2 | +| 19 | carbon | Carbon | +| 20 | hch | Hexachlorocyclohexane HCH | +| 21 | pfc | Perfluorocarbons PFC | +| 22 | sf6 | Sulfurhexafluoride SF6 | +| 23 | tvLicence | Television | +| 24 | internet | Internet service | +| 25 | refuse | Trash | +| 26 | electricityTransmissionMetered | Transmission metered electricity | + +--- + +#### Currency +**Base:** `UInt16` (union) - ISO 4217 currency codes + +| Value | Code | Description | +|-------|------|-------------| +| 0 | other | Another type of currency | +| 36 | AUD | Australian dollar | +| 124 | CAD | Canadian dollar | +| 156 | CNY | Chinese yuan renminbi | +| 208 | DKK | Danish crown | +| 356 | INR | India rupees | +| 392 | JPY | Japanese yen | +| 578 | NOK | Norwegian crown | +| 643 | RUB | Russian ruble | +| 752 | SEK | Swedish crown | +| 756 | CHF | Swiss francs | +| 826 | GBP | British pound | +| 840 | USD | US dollar | +| 978 | EUR | European euro | + +--- + +#### DataQualifierKind +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | none | Not Applicable | +| 2 | average | Average value | +| 4 | excess | Amount over threshold | +| 5 | highThreshold | Programmed high threshold | +| 7 | lowThreshold | Programmed low threshold | +| 8 | maximum | Highest value observed | +| 9 | minimum | Smallest value observed | +| 11 | nominal | Nominal | +| 12 | normal | Normal | +| 16 | secondMaximum | Second highest value observed | +| 17 | secondMinimum | Second smallest value observed | +| 23 | thirdMaximum | Third highest value observed | +| 24 | fourthMaximum | Fourth highest value observed | +| 25 | fifthMaximum | Fifth highest value observed | +| 26 | sum | Accumulated sum | + +--- + +#### FlowDirectionKind +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | none | Not Applicable (N/A) | +| 1 | forward | Delivered/Imported energy | +| 2 | lagging | Lagging (inductive loading) | +| 3 | leading | Leading (capacitive loading) | +| 4 | net | Forward - Reverse | +| 5 | q1plusQ2 | Reactive positive quadrants | +| 7 | q1plusQ3 | Quadrants 1 and 3 | +| 8 | q1plusQ4 | Quadrants 1 and 4 (forward active energy) | +| 9 | q1minusQ4 | Q1 minus Q4 | +| 10 | q2plusQ3 | Quadrants 2 and 3 (reverse active energy) | +| 11 | q2plusQ4 | Quadrants 2 and 4 | +| 12 | q2minusQ3 | Q2 minus Q3 | +| 13 | q3plusQ4 | Reactive negative quadrants | +| 14 | q3minusQ2 | Q3 minus Q2 | +| 15 | quadrant1 | Q1 only | +| 16 | quadrant2 | Q2 only | +| 17 | quadrant3 | Q3 only | +| 18 | quadrant4 | Q4 only | +| 19 | reverse | Reverse/Received/Exported energy | +| 20 | total | Forward + Reverse | +| 21 | totalByPhase | Total by phase (polyphase metering) | + +--- + +#### MeasurementKind +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | none | Not Applicable | +| 2 | apparentPowerFactor | Apparent Power Factor | +| 3 | currency | Currency | +| 4 | current | Current | +| 5 | currentAngle | Current Angle | +| 6 | currentImbalance | Current Imbalance | +| 7 | date | Date | +| 8 | demand | Demand | +| 9 | distance | Distance | +| 10 | distortionVoltAmperes | Distortion Volt Amperes | +| 11 | energization | Energization | +| 12 | energy | Energy | +| 13 | energizationLoadSide | Energization Load Side | +| 14 | fan | Fan | +| 15 | frequency | Frequency | +| 16 | Funds | Funds (duplication of currency) | +| 17-28 | ieee1366* | Various IEEE 1366 reliability metrics | +| 31 | lineLosses | Line Losses | +| 32 | losses | Losses | +| 33 | negativeSequence | Negative Sequence | +| 34 | phasorPowerFactor | Phasor Power Factor | +| 35 | phasorReactivePower | Phasor Reactive Power | +| 36 | positiveSequence | Positive Sequence | +| 37 | power | Power | +| 38 | powerFactor | Power Factor | +| 40 | quantityPower | Quantity Power | +| 41 | sag | Sag (Voltage Dip) | +| 42 | swell | Swell | +| 43 | switchPosition | Switch Position | +| 44 | tapPosition | Tap Position | +| 45 | tariffRate | Tariff Rate | +| 46 | temperature | Temperature | +| 47 | totalHarmonicDistortion | Total Harmonic Distortion | +| 48 | transformerLosses | Transformer Losses | +| 49-53 | unipedeVoltageDip* | Unipede Voltage Dip ranges | +| 54 | voltage | Voltage | +| 55 | voltageAngle | Voltage Angle | +| 56 | voltageExcursion | Voltage Excursion | +| 57 | voltageImbalance | Voltage Imbalance | +| 58 | volume | Volume (fluid) | +| 59 | zeroFlowDuration | Zero Flow Duration | +| 60 | zeroSequence | Zero Sequence | +| 64 | distortionPowerFactor | Distortion Power Factor | +| 81 | frequencyExcursion | Frequency Excursion | +| 90-116 | *various* | Device/communication attributes | +| 117 | signaltoNoiseRatio | Signal to Noise Ratio | +| 118-155 | *various* | Alarms, events, billing items | + +--- + +#### PhaseCodeKind +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | none | Not applicable to any phase | +| 16 | N | Neutral | +| 32 | C | Phase C | +| 33 | CN | Phase C to neutral | +| 40 | CAv | Phase C relative to Phase A voltage | +| 41 | ACN | Phases A, C and neutral | +| 64 | B | Phase B | +| 65 | BN | Phase B to neutral | +| 66 | BC | Phases B to C | +| 72 | BAv | Phase B relative to Phase A voltage | +| 96 | AC | Phases A and C | +| 97 | BCN | BC to neutral | +| 128 | A | Phase A | +| 129 | AN | Phase A to neutral | +| 132 | AB | Phases A to B | +| 136 | AtoAv | Phase A current relative to Phase A voltage | +| 193 | ABN | AB to Neutral | +| 224 | ABC | All phases | +| 225 | ABCN | ABC to Neutral | +| 256 | S2 | Phase S2 | +| 272 | S2N | Phase S2 to neutral | +| 512 | S1 | Phase S1 | +| 528 | S1N | Phase S1 to Neutral | +| 768 | S12 | Phase S1 to S2 | +| 769 | S12N | Phase S1, S2 to N | +| 784 | S12N | Phase S1, S2 to neutral | + +--- + +#### UnitMultiplierKind +**Base:** `Int16` (union) - Power of ten multipliers + +| Value | Symbol | Name | Multiplier | +|-------|--------|------|------------| +| -12 | p | pico | 10^-12 | +| -9 | n | nano | 10^-9 | +| -6 | micro | micro | 10^-6 | +| -3 | m | milli | 10^-3 | +| -2 | c | centi | 10^-2 | +| -1 | d | deci | 10^-1 | +| 0 | none | none | 1 | +| 1 | da | deca | 10^1 | +| 2 | h | hecto | 10^2 | +| 3 | k | kilo | 10^3 | +| 6 | M | mega | 10^6 | +| 9 | G | giga | 10^9 | +| 12 | T | tera | 10^12 | + +--- + +#### QualityOfReading +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | valid | Data passed all validation checks or verified | +| 7 | manuallyEdited | Replaced or approved by human | +| 8 | estimatedUsingReferenceDay | Machine computed from historical data | +| 9 | estimatedUsingLinearInterpolation | Computed using linear interpolation | +| 10 | questionable | Failed one or more checks | +| 11 | derived | Calculated using logic or math | +| 12 | projected | Forecast of future readings | +| 13 | mixed | Mixed quality characteristics | +| 14 | raw | Not validated | +| 15 | normalizedForWeather | Adjusted for weather | +| 16 | other | Other characteristic | +| 17 | validated | Validated and possibly edited/estimated | +| 18 | verified | Failed validation but represents actual usage | +| 19 | revenueQuality | Valid and acceptable for billing | + +--- + +#### ServiceKind +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | electricity | Electricity service | +| 1 | gas | Gas service | +| 2 | water | Water service | +| 3 | time | Time service | +| 4 | heat | Heat service | +| 5 | refuse | Refuse (waste) service | +| 6 | sewerage | Sewerage service | +| 7 | rates | Rates (tax, charge, toll, duty, tariff) | +| 8 | tvLicence | TV license service | +| 9 | internet | Internet service | + +--- + +#### TimeAttributeKind +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | none | Not Applicable | +| 1 | tenMinute | 10-minute | +| 2 | fifteenMinute | 15-minute | +| 3 | oneMinute | 1-minute | +| 4 | twentyfourHour | 24-hour | +| 5 | thirtyMinute | 30-minute | +| 6 | fiveMinute | 5-minute | +| 7 | sixtyMinute | 60-minute | +| 10 | twoMinute | 2-minute | +| 14 | threeMinute | 3-minute | +| 15 | present | Within present period of time | +| 16 | previous | Previous monthly cycle | +| 31 | twentyMinute | 20-minute interval | +| 50-56 | fixedBlock* | Fixed block intervals (1-60 min) | +| 57-77 | rollingBlock* | Rolling block intervals with sub-intervals | + +--- + +#### TimePeriodOfInterest +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | none | Not Applicable | +| 8 | billingPeriod | Billing period starting at midnight | +| 11 | daily | Daily period starting at midnight | +| 13 | monthly | Monthly period starting first day of month | +| 22 | seasonal | Season spanning multiple months | +| 24 | weekly | Weekly period starting at midnight | +| 32 | specifiedPeriod | Defined by TimePeriod element | + +--- + +#### UnitSymbolKind +**Base:** `UInt16` (union) - **Over 100 enumeration values** + +Key units include: + +| Value | Symbol | Description | +|-------|--------|-------------| +| 0 | none | N/A | +| 2 | m | Length, meter | +| 3 | g | Mass, gram | +| 5 | A | Current, ampere | +| 6 | K | Temperature, Kelvin | +| 23 | degC | Degrees Celsius | +| 27 | sec | Time, seconds | +| 29 | V | Electric potential, Volt | +| 30 | ohm | Electric resistance, Ohm | +| 33 | Hz | Frequency, hertz | +| 38 | W | Real power, Watt | +| 42 | m3 | Volume, cubic meter | +| 61 | VA | Apparent power, Volt Ampere | +| 63 | VAr | Reactive power, Volt Ampere reactive | +| 65 | cosTheta | Power factor | +| 71 | VAh | Apparent energy, Volt Ampere hours | +| 72 | Wh | Real energy, Watt hours | +| 73 | VArh | Reactive energy, Volt Ampere reactive hours | +| 111 | count | Counter value | +| 119 | ft3 | Volume, cubic feet | +| 159 | min | Time, minute | +| 160 | h | Time, hour | +| 169 | therm | Energy, Therm | + +*(See full schema for complete list of 100+ unit symbols)* + +--- + +#### StatusCode +**Base:** `UInt16` (union) - HTTP-style status codes + +| Value | Name | +|-------|------| +| 200 | Ok | +| 201 | Created | +| 202 | Accepted | +| 204 | No Content | +| 301 | Moved Permanently | +| 302 | Redirect | +| 304 | Not Modified | +| 400 | Bad Request | +| 401 | Unauthorized | +| 403 | Forbidden | +| 404 | Not Found | +| 405 | Method Not Allowed | +| 410 | Gone | +| 500 | Internal Server Error | + +--- + +#### CRUDOperation +**Base:** `UInt16` (union) + +| Value | Name | +|-------|------| +| 0 | Create | +| 1 | Read | +| 2 | Update | +| 3 | Delete | + +--- + +#### DataCustodianApplicationStatus +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 1 | Review | Under review | +| 2 | Production | Production (Live) | +| 3 | OnHold | On Hold | +| 4 | Revoked | Revoked | + +--- + +#### ThirdPartyApplicatonStatus +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 1 | Development | Development | +| 2 | ReviewTest | Review/Test | +| 3 | Production | Live | +| 4 | Retired | Removed | + +--- + +#### ThirdPartyApplicationType +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 1 | Web | Web application | +| 2 | Desktop | Desktop application | +| 3 | Mobile | Mobile device application | +| 4 | Device | Other device application | + +--- + +#### ThirdPartyApplicationUse +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 1 | EnergyManagement | Energy Management | +| 2 | Comparisons | Analytical | +| 3 | Government | Governmental | +| 4 | Academic | Academic | +| 5 | LawEnforcement | Law Enforcement | + +--- + +#### AuthorizationStatus +**Base:** `UInt16` (union) + +| Value | Name | +|-------|------| +| 0 | Revoked | +| 1 | Active | +| 2 | Denied | + +--- + +#### ESPIServiceStatus +**Base:** `UInt16` (union) + +| Value | Name | Description | +|-------|------|-------------| +| 0 | Unavailable | Unavailable | +| 1 | Normal | Normal; operational | + +--- + +### 5.3 String-Based Enumerations + +#### AmiBillingReadyKind +**Base:** `String32` + +| Value | Description | +|-------|-------------| +| `amiCapable` | AMI capable meter without communications module | +| `amiDisabled` | AMI functionality disabled or not used | +| `billingApproved` | Operating AMI meter certified for billing | +| `enabled` | AMI capable meter with communications | +| `nonAmi` | Non-AMI capable meter | +| `nonMetered` | Not currently equipped with meter | +| `operable` | AMI meter functioning and communicating | + +--- + +#### UsagePointConnectedKind +**Base:** `String32` + +| Value | Description | +|-------|-------------| +| `connected` | Connected to network, able to receive/send commodity | +| `logicallyDisconnected` | Disconnected via meter disconnect function | +| `physicallyDisconnected` | Disconnected upstream of meter (field crew) | + +--- + +#### ApnodeType +**Base:** `String8` - Aggregate Node Types (Pricing) + +| Value | Description | +|-------|-------------| +| `AG` | Aggregated Generation | +| `CPZ` | Custom Price Zone | +| `DPZ` | Default Price Zone | +| `LAP` | Load Aggregation Point | +| `TH` | Trading Hub | +| `SYS` | System Zone | +| `CA` | Control Area | +| `DCA` | Designated Congestion Area | +| `GA` | Generic Aggregation | +| `GH` | Generic Hub | +| `EHV` | 500 kV (Extra High Voltage) | +| `ZN` | Zone | +| `INT` | Interface | +| `BUS` | Bus | + +--- + +#### AnodeType +**Base:** `String8` - Aggregated Node Types + +| Value | Description | +|-------|-------------| +| `SYS` | System Zone/Region | +| `RUC` | RUC Zone | +| `LFZ` | Load Forecast Zone | +| `REG` | Market Energy/Ancillary Service Region | +| `AGR` | Aggregate Generation Resource | +| `POD` | Point of Delivery | +| `ALR` | Aggregate Load Resource | +| `LTAC` | Load Transmission Access Charge Group | +| `ACA` | Adjacent Control Area | +| `ASR` | Aggregated System Resource | +| `ECA` | Embedded Control Area | + +--- + +#### tOUorCPPorConsumptionTier +**Base:** `xs:string` + +| Value | Description | +|-------|-------------| +| `tou` | Time of Use | +| `cpp` | Consumption Peak Period | +| `consumptiontier` | Consumption Tier | + +--- + +#### ParticipationCategoryMPM +**Base:** `String4` + +| Value | Description | +|-------|-------------| +| `Y` | Participates in both LMPM and SMPM | +| `N` | Not included in LMP price measures | +| `S` | Participates in SMPM price measures | +| `L` | Participates in LMPM price measures | + +--- + +#### EnrollmentStatus +**Base:** `String32` + +| Value | Description | +|-------|-------------| +| `unenrolled` | Currently NOT enrolled in Tariff Rider | +| `enrolled` | Currently enrolled in Tariff Rider | +| `enrolledPending` | Currently pending enrollment | + +--- + +## 6. Complex Types (Resources) + +### 6.1 ESPI Core Resources (extend IdentifiedObject) + +| Type | Description | Key Fields | +|------|-------------|------------| +| `ApplicationInformation` | Third Party Application registration | dataCustodianId, client_id, client_secret, scope, grant_types | +| `Authorization` | OAuth authorization grant | authorizedPeriod, status, expires_at, scope, token_type | +| `IntervalBlock` | Time sequence of readings | interval (DateTimeInterval), IntervalReading[] | +| `MeterReading` | Set of values from meter | (extends IdentifiedObject only) | +| `ReadingType` | Characteristics of readings | accumulationBehaviour, commodity, currency, uom, phase, etc. | +| `UsagePoint` | Logical metering point | roleFlags, ServiceCategory, status, serviceDeliveryPoint, phaseCode | +| `ElectricPowerQualitySummary` | Power quality metrics | flickerPlt/Pst, harmonicVoltage, longInterruptions, etc. | +| `ElectricPowerUsageSummary` | [DEPRECATED] Usage summary | billingPeriod, billLastPeriod, various consumption metrics | +| `UsageSummary` | Usage for billing period | Same as above + tariffProfile, tariffRiderRefs | +| `TimeConfiguration` | Time/DST configuration | dstEndRule, dstOffset, dstStartRule, tzOffset | +| `ProgramIdMappings` | TOU/CPP/Tier code mappings | programIdMapping[] | + +### 6.2 Supporting Complex Types (extend Object) + +| Type | Description | Key Fields | +|------|-------------|------------| +| `Object` | Base superclass | extension[] | +| `IdentifiedObject` | Named object base | batchItemInfo | +| `DateTimeInterval` | Time interval | duration (UInt32), start (TimeType) | +| `IntervalReading` | Individual reading value | cost, ReadingQuality[], timePeriod, value, tou, cpp | +| `ReadingQuality` | Quality indicator | quality (QualityOfReading) | +| `ServiceCategory` | Service classification | kind (ServiceKind) | +| `SummaryMeasurement` | Aggregated measurement | powerOfTenMultiplier, timeStamp, uom, value | +| `BatchItemInfo` | Batch transaction info | name, operation, statusCode, statusReason | +| `ServiceDeliveryPoint` | Revenue UsagePoint info | name, tariffProfile, customerAgreement, tariffRiderRefs | +| `RationalNumber` | Fraction representation | numerator, denominator | +| `ReadingInterharmonic` | Harmonic/interharmonic | numerator, denominator | +| `LineItem` | Billing line item detail | amount, rounding, dateTime, note, itemKind, unitCost | +| `PnodeRefs` | Pricing node references | pnodeRef[] | +| `PnodeRef` | Single pricing node | apnodeType, ref, startEffectiveDate, endEffectiveDate | +| `AggregateNodeRefs` | Aggregate node references | aggregateNodeRef[] | +| `AggregateNodeRef` | Single aggregate node | anodeType, ref, pnodeRef[] | +| `TariffRiderRefs` | Tariff rider references | tariffRiderRef[] | +| `TariffRiderRef` | Single tariff rider | riderType, enrollmentStatus, effectiveDate | +| `BillingChargeSource` | Billing source info | agencyName | +| `ServiceStatus` | ESPI service status | currentStatus (ESPIServiceStatus) | +| `BatchListType` | Resource URI list | resources[] (xs:anyURI) | + +--- + +## 7. Complex Types (Supporting) + +### Inheritance Hierarchy + +``` +Object +├── IdentifiedObject +│ ├── ApplicationInformation +│ ├── Authorization +│ ├── IntervalBlock +│ ├── MeterReading +│ ├── ReadingType +│ ├── UsagePoint +│ ├── ElectricPowerQualitySummary +│ ├── ElectricPowerUsageSummary [DEPRECATED] +│ ├── UsageSummary +│ ├── TimeConfiguration +│ └── ProgramIdMappings +├── IntervalReading +├── ReadingQuality +├── ServiceCategory +├── SummaryMeasurement +├── BatchItemInfo +├── ServiceDeliveryPoint +├── RationalNumber +├── ReadingInterharmonic +├── LineItem +├── PnodeRefs +├── PnodeRef +├── AggregateNodeRefs +├── AggregateNodeRef +├── TariffRiderRefs +├── TariffRiderRef +├── BillingChargeSource +├── ServiceStatus +└── DateTimeInterval +``` + +--- + +## 8. Global Elements + +The schema defines the following global elements that can appear at the root of XML documents: + +| Element | Type | +|---------|------| +| `ApplicationInformation` | ApplicationInformation | +| `Authorization` | Authorization | +| `IntervalBlock` | IntervalBlock | +| `IntervalReading` | IntervalReading | +| `MeterReading` | MeterReading | +| `ReadingQuality` | ReadingQuality | +| `ReadingType` | ReadingType | +| `IdentifiedObject` | IdentifiedObject | +| `UsagePoint` | UsagePoint | +| `ElectricPowerQualitySummary` | ElectricPowerQualitySummary | +| `ElectricPowerUsageSummary` | ElectricPowerUsageSummary | +| `UsageSummary` | UsageSummary | +| `DateTimeInterval` | DateTimeInterval | +| `SummaryMeasurement` | SummaryMeasurement | +| `BatchItemInfo` | BatchItemInfo | +| `Object` | Object | +| `ServiceStatus` | ServiceStatus | +| `LocalTimeParameters` | TimeConfiguration | +| `ProgramIdMappings` | ProgramIdMappings | +| `BatchList` | BatchListType | + +--- + +## Summary Statistics + +| Category | Count | +|----------|-------| +| Basic/Primitive Types | 7 | +| String Types | 7 | +| Hex Binary Types | 4 | +| Special Types | 2 | +| Enumeration Types (Total) | 35 | +| - OAuth Enumerations | 5 | +| - Numeric Enumerations (UInt16) | 20 | +| - String-Based Enumerations | 10 | +| Complex Types (Resources) | 10 | +| Complex Types (Supporting) | 19 | +| Global Elements | 20 | + +--- + +*Generated from ESPI 4.0 Schema (espi.xsd) - Version 4.0.20231213*