Repository navigation
Open
Description
Requirement
Every ESPI resource's atom:id must be a permanent, repeatable, unique UUID version 5 (GBA, Generating Persistent UUIDs):
- An entry's
<id>is "established once, when the resource is created". It does not change between reads, when an access token is issued or refreshed, or under a different Subscription. - No two resources share an
<id>. UUIDs are written in lowercase, and Third Parties accept any case. - A feed's
<id>"is not required to be repeatable". - IntervalBlock: the id "should be based on a repeatable timestamp value, such as the interval's start".
- Authorization:
- Each access token issued by the authorization_code or client_credentials flow creates a new Authorization, with a new
<id>and address. A refresh keeps the same Authorization. - The name is built "from something unique to its grant, never from the client, the registration or the Third Party alone".
- The access token value must not be used: it changes on refresh, which would break repeatability.
- Each access token issued by the authorization_code or client_credentials flow creates a new Authorization, with a new
- The namespace belongs to the utility, e.g.
uuidV5(NameSpace_DNS, "<utility domain>")("you should use your own here").
Current state (audit, 2026-11-17)
Correct:
EspiIdGeneratorServiceimplements v5 correctly. It reproduces the page's three worked examples exactly, e.g.uuidV5(DNS, "imaginary-power-and-light.com")=f30ad8b1-8eb6-56d9-a95e-aba961ce074f.- Feed ids are v5 of the feed URL.
- Entry ids are
urn:uuid:plus the stored entity id (BaseExportService.buildFeed). - Sample-data ids are v5 of fixed URLs.
Defects:
| # | Where | Problem |
|---|---|---|
| 1 | IdentifiedObject() constructor |
It assigns UUID.randomUUID() (v4) to every new entity, so every service's if (getId() == null) v5 branch never runs, including MeterServiceImpl's serial-number v5. Any resource not given an explicit id is v4 and cannot be regenerated. |
| 2 | CustomerServiceImpl, EndDeviceServiceImpl, ServiceLocationServiceImpl |
They fall back to UUID.randomUUID() (v4). |
| 3 | SubscriptionProvisioningServiceImpl.newAuthorization |
It sets UUID.randomUUID() (v4) as the Authorization id. |
| 4 | generateSubscriptionId (Subscription, and CustomerAccountServiceImpl) |
The name includes currentTimeMillis/nanoTime: v5 and unique, but not repeatable. The CustomerAccount fallback name is time-based too. |
| 5 | Single-resource endpoints (/UsagePoint/{id}, /MeterReading/{id}, ...) |
They return the bare resource with no <entry>, so there is no atom:id. Only /Authorization/{id} returns an entry. |
| 6 | DtoExportServiceImpl / DtoExportServiceFacade createAtomFeed/createAtomEntry |
The feed id is random v4, and entry ids are time-based, new on every export. No live DC endpoint uses them (the only caller is commented out). |
| 7 | ESPI_NAMESPACE = 6ba7b810-… (NameSpace_DNS) with a full URL as the name |
Valid v5, but not a utility namespace. Because the host is part of the name, every id changes if the DC's base URL changes. |
Proposed naming scheme
The namespace is the Data Custodian's configured namespace, uuidV5(NameSpace_DNS, "<utility domain>"), set once per deployment. The name is built from business keys, not from URLs, tokens or timestamps of the request.
| Resource | v5 name |
|---|---|
| CustomerAccount | CustomerAccount:{accountId} |
| Customer | Customer:{customer number in the utility's system} |
| ServiceLocation | ServiceLocation:{premise or location id} |
| Meter / EndDevice | Meter:{serialNumber} (as MeterServiceImpl intends) |
| UsagePoint | UsagePoint:{service point id} |
| MeterReading | {UsagePoint uuid}:MeterReading:{reading type key} |
| ReadingType | ReadingType:{its defining values: kind, unit, interval length, ...} |
| IntervalBlock | {MeterReading uuid}:IntervalBlock:{interval start} (the page's rule) |
| UsageSummary / ElectricPowerQualitySummary | {UsagePoint uuid}:{type}:{summary interval start} |
| Authorization | Authorization:{correlationId} |
| Subscription | Subscription:{Authorization uuid}:{energy or customer} |
- Page-prescribed rows: IntervalBlock and Authorization ("something unique to its grant"). The page's examples (a meter as service address plus label, an account by its number) support the business-key approach.
- Our choice: the other rows, and putting the parent uuid in child names. The parent uuid keeps the same child key under different parents distinct.
- Authorization
correlationId: the AS sends it with each authorization_code grant over the back-channel, and the DC stores it on the Authorization as a unique key. It is new per grant, unchanged by a refresh, and not the client, registration or Third Party.
Points to settle
- client_credentials (FB=34_35): these tokens do not go through the grant back-channel, so they have no
correlationId. Proposal: the AS passes its own record id for that grant (e.g. Spring Authorization Server'sOAuth2Authorization.id) to the DC. - Generate once, store forever: the id is computed at creation and stored. A later change to an account number or serial number must not change the
<id>. - Namespace is immutable per deployment: moving the DC to another URL no longer changes ids, but changing the namespace would.
- Guessable names: account numbers and serial numbers come from small sets, so anyone who knows the namespace can try candidates against an
<id>. Decide whether the namespace should be non-public configuration before business keys become names. - Sample data: the seeded ids are URL-based today and would all change. This only matters if fixtures or certification samples depend on them.
- Missing business keys: decide what each resource uses as its key when the source data has none (e.g. a derived UsagePoint).
Tasks
- Remove the random v4 default from
IdentifiedObject. A new resource must be given its v5 id explicitly (fail fast if it isn't). -
EspiIdGeneratorService: a configurable DC namespace (uuidV5(NameSpace_DNS, domain)), plus one method per resource that builds the name above. - Replace the v4 fallbacks (Bump org.postgresql:postgresql from 42.7.4 to 42.7.7 in /openespi-datacustodian/OpenESPI-GreenButton-Workspace/OpenESPI-DataCustodian-java #2, Clean up legacy Spring XML and webapp files after Spring Boot 3.5 mig… #3) and the time-based names (Feature/spring boot 3.5 migration #4) with the scheme.
- Authorization id from
correlationId. Settle the client_credentials input with the AS. - Seed data uses the scheme.
- Single-resource endpoints return
<entry>with itsatom:id,<content>and links (with E1: DC resource engine + Atom entry-assembly (GET-first) — UsagePoint & Customer verticals, scope-enforced #187 / DC: serve Batch/Subscription/{id} (the customer token's resourceURI) as one subscription-scoped Atom feed #279). - Delete
DtoExportServiceImpl/DtoExportServiceFacadecreateAtomFeed/createAtomEntry, or make them use stored ids. - Tests:
- every
atom:idthe DC writes for a resource is a lowercaseurn:uuidv5; - it is identical on a second request and after a token refresh;
- it differs between two Authorizations of the same client and customer;
- an IntervalBlock re-requested for the same interval keeps its id.
- every
Related: #197 / #280 (atom:content and XSD validation), #279 (Batch/Subscription), #187 (E1 resource engine).
🤖 Generated with Claude Code
Metadata
Metadata
Assignees
Labels
No labels
Activity