Skip to content

ESPI atom:id: every resource id a permanent, repeatable UUID v5 from business keys (no random v4, no URL or token names) #281

Open

Description

@dfcoffin

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.
  • 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:

  • EspiIdGeneratorService implements 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

  1. 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's OAuth2Authorization.id) to the DC.
  2. 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>.
  3. Namespace is immutable per deployment: moving the DC to another URL no longer changes ids, but changing the namespace would.
  4. 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.
  5. Sample data: the seeded ids are URL-based today and would all change. This only matters if fixtures or certification samples depend on them.
  6. Missing business keys: decide what each resource uses as its key when the source data has none (e.g. a derived UsagePoint).

Tasks

Related: #197 / #280 (atom:content and XSD validation), #279 (Batch/Subscription), #187 (E1 resource engine).

🤖 Generated with Claude Code

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions