feat(common): ESPI FB-scope parser + Function Block catalog (#122 PR A)#136
Merged
Merged
Conversation
Foundation for grant→subscription resolution and resource-server enforcement. New package org.greenbuttonalliance.espi.common.scope: - FunctionBlock: authoritative catalog of NAESB ESPI 4.0 §REQ.21.4.2.1.3.1 ScopeFBTerms (id, category, optional ServiceKind, spec title) with tolerant byId/categoryOf/serviceKindOf lookups. Only active FBs are enumerated; DEPRECATED_IDS records spec-deprecated ids so they resolve to DEPRECATED rather than UNKNOWN. - FunctionBlockCategory: BASE / COMMODITY / ENERGY_DATA_SHAPE / CUSTOMER_PII (load-bearing) + INTERACTION / BULK_TRANSFER / AUTHORIZATION / ADMINISTRATION / PLATFORM / DEPRECATED / UNKNOWN. - EspiScope: FB-agnostic record parser for the FB=…;IntervalDuration=…; BlockDuration=…;HistoryLength=… grammar, deriving commodityServiceKinds(), functionBlocksIn(category), includesCustomerPii(), includesEnergyData(). Spec accuracy (per GBA-confirmed table): FB_71 does not exist (customer/PII = 54–62); FB_56/57 retitled; SFTP bulk FB_34/FB_66 deprecated (REST 35/67 remain); FB_29 Temperature is COMMODITY with no ServiceKind (XSD gap). The parser carries any FB id (future/deprecated/unknown) without error; the catalog is consulted only for semantics. openespi-authserver stays scope-opaque and keeps no dependency on this package — FB semantics live solely in the DC. 50 unit tests (EspiScopeTest, FunctionBlockTest), all green. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR A — ESPI FB-scope parser + Function Block catalog
Foundation PR for the #122 grant→subscription wiring. Adds the shared value object and authoritative Function Block catalog that every downstream PR (B–F) consumes. No behavior change to existing code — purely additive in
openespi-common.What's here
New package
org.greenbuttonalliance.espi.common.scope:FunctionBlock— authoritative in-code catalog of NAESB ESPI 4.0 §REQ.21.4.2.1.3.1 ScopeFBTerms. Each constant carriesid,FunctionBlockCategory, optionalServiceKind, and the spec title. StaticbyId/categoryOf/serviceKindOflookups tolerate uncatalogued ids. Only active FBs are enumerated;DEPRECATED_IDSrecords spec-deprecated ids so they resolve toDEPRECATEDrather thanUNKNOWN.FunctionBlockCategory—BASE/COMMODITY/ENERGY_DATA_SHAPE/CUSTOMER_PII(the load-bearing four that drive resolution + enforcement) plusINTERACTION/BULK_TRANSFER/AUTHORIZATION/ADMINISTRATION/PLATFORM/DEPRECATED/UNKNOWN.EspiScope— FB-agnostic immutable record parser for theFB=4_5_15;IntervalDuration=3600;BlockDuration=monthly;HistoryLength=13grammar. Carries any FB id (future/deprecated/unknown) without error and derivescommodityServiceKinds(),functionBlocksIn(category),includesCustomerPii(),includesEnergyData().Spec accuracy (GBA-confirmed table, May 2026)
COMMODITYwith noServiceKind— the ESPI XSDServiceKindenumeration has no temperature value (documented standard gap).SCOPE_FB_36_*in DataCustodianSecurityConfiguration— flagged for the enforcement PR (F) to fix.Design notes
openespi-authserverscope-opaque with no dependency onopenespi-common— all ESPI FB semantics live solely in the Data Custodian, per the AS↔DC contract pinned on Phase 2.0 — Stand up auth-server in dev with opaque tokens + subscription-bound introspection (Phase 2 precursor) #122.Tests
50 unit tests (
EspiScopeTest,FunctionBlockTest), all green — including catalog guard tests (id uniqueness/range, deprecated-vs-active disjointness, commodity→ServiceKind mapping with the FB_29 exception) and parser robustness (case-insensitive keys, whitespace/stray-segment tolerance, null/blank + non-integer rejection, immutability).Refs #122.
🤖 Generated with Claude Code