Skip to content

feat(common): ESPI resources inside atom:content, and XSD validation of ESPI XML (#197) - #280

Merged
dfcoffin merged 2 commits into
mainfrom
feature/197-atom-content-wrapper
Nov 18, 2026
Merged

dfcoffin merged 2 commits into
mainfrom
feature/197-atom-content-wrapper

Conversation

@dfcoffin

Copy link
Copy Markdown
Contributor

Closes #197

Summary

ESPI resources are now carried inside <atom:content>, as REQ.21, the GBA atom.xsd (the DMD validator's) and certified feeds require. Before, the DTOs wrote the resource as a direct child of <atom:entry>. This PR also adds a shared XSD validator for ESPI XML.

Atom <content> wrapper (openespi-common)

  • UsageAtomEntryDto and CustomerAtomEntryDto each map a nested Content class as atom:content. Its @XmlElements list holds the usage.xsd or customer.xsd resource types, so each entry still declares only its own namespace.
  • AtomEntryDto no longer holds content. getContent()/setContent() are abstract, and getResource() returns the content.
  • As in the ESPI profile, <atom:content> has no type and there is no atom:author. Both are intentional; see the docs below.

EspiXmlSchemaValidator (openespi-common xml/)

  • Validates a feed or entry against atom.xsd, espi.xsd and customer.xsd, the same schema files the DMD validator uses. Every issue is reported with its line and column.
  • The schemas load from the classpath only:
    • An LSResourceResolver resolves the Atom and xml.xsd imports. A local ESPI_4.1/xml.xsd is added, copied from the DMD validator.
    • External DTDs and schemas are never fetched, and secure processing is on.
  • The schemas are compiled once, and the validator is thread-safe.

Export defects found by the validator

  • The feed had a <published> element, which atom.xsd doesn't allow. It is now @XmlTransient (RFC 4287 4.1.1 doesn't define one either).
  • The empty feed's self link had no type, which atom.xsd requires. BaseExportService.buildFeed now sets espi-feed/{resource}, using the last path segment of the href when no resource name is given.

Third Party reader

  • UsagePointRESTRepositoryImpl reads UsagePoints from atom:content through AtomEntryDto::getResource. A null or empty feed returns an empty list.
  • The new UsagePointRESTRepositoryImplTests uses a real WebClient with a stubbed exchange function. It replaces the old disabled-style integration test.

Documentation

  • New docs/ESPI_ATOM_PROFILE.md, linked from CLAUDE.md. It covers:
    • where ESPI deliberately differs from RFC 4287: no author (privacy), bare content, and link rel/type required;
    • what atom.xsd can't enforce;
    • known atom.xsd issues;
    • the open REQ.21 p.168 related-link type question.
  • Javadoc on the DTOs and the validator points maintainers to that document.

Not in this PR

Test plan

  • New AtomContentAndSchemaValidationTest (9 tests):

    • each wrapper is written as expected;
    • a feed in the certified style validates and unmarshals;
    • a round trip keeps the resource;
    • a bare resource is not read as the content;
    • an enumeration error is reported at the correct line;
    • an empty feed is valid;
    • malformed XML is reported as FATAL;
    • an external DTD is not followed.
  • AtomFeedExportTest validates the real usage, customer and empty feed output against the XSDs.

  • Full suite on Docker (WSL), with Testcontainers for MySQL and PostgreSQL:

    Module Tests Failed Skipped
    handoff 22 0 0
    common 917 0 0
    Data Custodian 217 0 0
    Third Party 121 0 2

    The About controller tests were excluded (AboutControllerTest fails on a JDK whose java.version is exactly "25" (matches Bootstrap w-25) #277).

🤖 Generated with Claude Code

…of ESPI XML (#197)

Atom entries now carry their ESPI resource as the single child of
<atom:content>, as REQ.21's examples and CMD-certified Data Custodian feeds
do, for both usage (UsageAtomEntryDto) and customer (CustomerAtomEntryDto)
entries. The constructors and getContent() keep taking and returning the
resource; getResource() now returns it after unmarshalling (it read a
base-class field that was never set, so it was always null).

- EspiXmlSchemaValidator (openespi-common xml/) validates a feed or entry
  against atom.xsd + espi.xsd + customer.xsd (the GBA DMD validator's files)
  from the classpath, with a local xml.xsd, reporting every issue with its
  line and column. It never fetches external DTDs or schemas.
- The validator found two DC export defects, now fixed: feeds wrote a
  feed-level atom:published (RFC 4287 has none; atom.xsd rejects it), and an
  empty feed's self link had no type (atom.xsd requires one; it is now taken
  from the feed href).
- AtomFeedExportTest checks that UsagePoint, empty and Customer feeds from
  the DC export validate; AtomContentAndSchemaValidationTest covers the
  content wrapper, a certified-style feed, round trips, error reporting
  with lines, and that external DTDs are not followed.
- Third Party: UsagePointRESTRepositoryImpl handles an empty feed and skips
  entries that are not UsagePoints. The two @disabled tests of
  UsagePointRESTRepositoryIntegrationTest are replaced by
  UsagePointRESTRepositoryImplTests (real WebClient, stubbed exchange).
- docs/ESPI_ATOM_PROFILE.md records how ESPI deliberately differs from
  RFC 4287 (no atom:author for privacy, bare atom:content, link rel/type
  required) so they are not "fixed"; the DTOs, BaseExportService, the
  validator and CLAUDE.md point to it.

ServiceCategory and other enums are still written as Java constant names
(#278).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
#197)

- Third Party: each UsagePoint takes its id from the entry's atom:id (the
  mapper copies only espi.xsd fields), so findByHashedId no longer fails on
  a null id; entries that are not UsagePoints are counted in a warning
  (never logged as content). The test's mapper no longer sets the id.
- EspiXmlSchemaValidator: validate(String) reads characters, so a declared
  encoding cannot garble the text; a SAXParseException thrown without the
  error handler is recorded as FATAL, never reported as valid.
- AtomFeedDto: the unused, never-written feed published field is removed
  (RFC 4287 4.1.1, atom.xsd), with its setters and constructor arguments.
- Tests: AssertJ assertions on one object chained (CLAUDE.md); new tests
  for the entry id, a declared ISO-8859-1 encoding, and a non-uuid id.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dfcoffin
dfcoffin merged commit 4f8ed36 into main Nov 18, 2026
11 checks passed
@dfcoffin
dfcoffin deleted the feature/197-atom-content-wrapper branch November 18, 2026 08:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Third Party cannot unmarshal any ESPI Atom feed (AtomFeedDto date adapters + abstract entry type)

1 participant