Add ESPI-native Meter Data and Billing Summary Verifiable Credential schemas

[ameetdesh]

Summary

Closes #185

Adds two energy Verifiable Credentials — Meter Data and Billing Summary — that use ESPI/Green Button types natively, plus the full ESPI reference schema and CIM meter telemetry extension. All schemas are published-ready for schema.beckn.io.

Credentials

• MeterDataCredential (meterDataVC/v1.0/) — historical interval meter readings (15-min, hourly) using ESPI IntervalBlock, ReadingType, IntervalReading with native numeric/string enum codes
• BillingSummaryCredential (billingSummaryVC/v1.0/) — aggregated monthly billing data using ESPI UsageSummary, SummaryMeasurement, LineItem with hundred-thousandths (1e-5) cost encoding

Both import shared identity from EnergyCustomerProfile (aligned with PR #208's CustomerCredential) and ESPI types from espiGreenButton.

ESPI Reference Schemas

• espiGreenButton/ — full OpenAPI 3.1.1 representation of NAESB ESPI XSD (~30 types), JSON-LD context mapping to http://naesb.org/espi# IRIs with skos:exactMatch links, and comprehensive README with enum lookup tables. Code fields (commodity, flowDirection, uom, accumulationBehaviour, currency, kind, phase, qualityOfReading, itemKind) accept both ESPI integer codes and human-readable camelCase string aliases via oneOf unions; timestamp fields accept both Unix epoch integers and ISO-8601 date-time strings.
• espiGreenButtonWithCIM/ — optional CIM (IEC 61968/61970) extension: device models, SCADA telemetry, instrument transformers, events (38 classes)

Publishable Schema Packs (beckn/schemas format)

Under specification/schema/:

• EnergyCustomerProfile/v1.0/ — customerNumber, meterNumber, meterType (enum: AMR, AMI, Electromechanical, ...), idRef — shared with PR Unify energy VCs into Electricity Credentials #208
• EnergyMeterDataGB/v1.0/ — ServiceCategory, timeZone, ReadingType, IntervalBlock, qualityOfReading
• EnergyBillingSummary/v1.0/ — ServiceCategory, timeZone, currency, UsageSummary[]

Each pack has: attributes.yaml, context.jsonld, vocab.jsonld, README.md — ready for schema.beckn.io deployment.

Key design decisions

• OpenAPI 3.1.1 for every attributes.yaml, single source of truth — all schema packs and the ESPI reference schemas are OpenAPI 3.1.1 documents (with jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema) so they render in Swagger UI and serve as the canonical input for schema validation. No parallel standalone schema.json files; cross-refs use relative-file $refs with #/components/schemas/<Name> JSON Pointer fragments so they resolve locally in both Swagger and validators. Canonical identity preserved via $id on each schema object.
• ESPI-native with human-readable aliases: the oneOf unions live in espiGreenButton/attributes.yaml itself so DEG credentials referencing the base ESPI types inherit the relaxation without needing overlay schemas. Integer codes remain ESPI-faithful; string aliases follow ESPI camelCase naming.
• Cost encoding: type: number — integer = hundred-thousandths (1e-5) of currency (ESPI native); float (decimal point) = exact currency amount. Convention documented, not schema-enforceable (JSON has one number type)
• ISO 8601 timestamps with optional timezone offset (+05:30) accepted alongside ESPI Unix epoch integers via oneOf
• Shared identity imported from EnergyCustomerProfile/context.jsonld using the deg: namespace (https://schema.beckn.io/deg/), aligning with the prefix convention used in schema.beckn.io/P2PTrade/2.0/vocab.jsonld
• PR Unify energy VCs into Electricity Credentials #208 alignment: customerProfile, customerNumber, meterNumber, meterType, idRef terms resolve to same namespace. maskedIdType/maskedIdNumber removed (replaced by idRef). meterType enum matches PR Unify energy VCs into Electricity Credentials #208
• Versioned VC schemas: Both meterDataVC/ and billingSummaryVC/ use v1.0/ subdirectories, with all schema URLs updated to include /v1.0/ (e.g., https://schema.beckn.io/EnergyMeterDataGB/v1.0/context.jsonld)

Files added/modified

Directory	Files	Purpose
meterDataVC/v1.0/	attributes.yaml, context.jsonld, vocab.jsonld, examples/*, ndjson-transport.md, README.md	Interval meter data VC
billingSummaryVC/v1.0/	attributes.yaml, context.jsonld, vocab.jsonld, examples/*, README.md	Billing summary VC
energy-credentials/	readme.md	Credential family overview
external/schema/espiGreenButton/	attributes.yaml, context.jsonld, vocab.jsonld, README.md	Full ESPI/NAESB schema with DEG relaxations
external/schema/espiGreenButtonWithCIM/	attributes.yaml, context.jsonld, vocab.jsonld, README.md	CIM meter telemetry extension
specification/schema/EnergyCustomerProfile/	v1.0/{attributes.yaml, context.jsonld, vocab.jsonld, README.md}	Shared customer identity schema pack
specification/schema/EnergyMeterDataGB/	v1.0/{attributes.yaml, context.jsonld, vocab.jsonld, README.md}	Meter data schema pack
specification/schema/EnergyBillingSummary/	v1.0/{attributes.yaml, context.jsonld, vocab.jsonld, README.md}	Billing summary schema pack
scripts/validate_vc_examples.py	validate_vc_examples.py	Bundle-and-validate harness: redocly bundle --dereferenced + jsonschema Draft 2020-12

Validation harness

scripts/validate_vc_examples.py replaces the old standalone schema.json + pytest harness. It bundles any attributes.yaml via @redocly/cli bundle --dereferenced (inlining cross-schema $refs into one self-contained document) and validates each example with jsonschema. Any residual remote $refs Redocly leaves unresolved are fetched lazily via a referencing.Registry retrieve callable.

python3 scripts/validate_vc_examples.py \
  specification/schema/EnergyMeterDataCredential/v1.0/attributes.yaml

Examples auto-discovered from <attributes-dir>/examples/; schema picked as the single entry in components.schemas or the one matching info.title (override with --schema).

Test plan

• JSON-LD context keyword trace verified — all ESPI terms resolve to espi: IRIs, identity terms to deg: IRIs
• CIM extension types reviewed against IEC 61968-9 / IEC 61970 class definitions
• All schema $id and @context URLs use versioned /v1.0/ paths
• Every attributes.yaml validates as OpenAPI 3.1.1 via @redocly/cli lint (in-PR refs resolve; residual errors in the 2 VC envelopes are transitive through upstream schema.beckn.io/Credential/v2.0, unrelated to this PR)
• scripts/validate_vc_examples.py wired up end-to-end against both credentials
• All 6 examples (5 for MeterDataCredential: example.json + example-decimal.json + example.ndjson line 1/2/3; 1 for BillingSummaryCredential) now pass validation after:
  • Loosening espiGreenButton/attributes.yaml code fields to oneOf: [integer, string] unions (commodity, uom, currency, flowDirection, accumulationBehaviour, kind, phase, qualityOfReading, itemKind) and timestamp fields to oneOf: [integer epoch, ISO-8601 string] (DateTimeInterval.start, statusTimeStamp, timeStamp, LineItem.dateTime); loosening IntervalReading.value/cost and SummaryMeasurement.value from integer to number; and array-wrapping IntervalBlock.IntervalReading and UsageSummary.costAdditionalDetailLastPeriod (XSD maxOccurs=unbounded elements the generator had emitted as single $refs).
  • Populating issuer.licenseNumber (required upstream) and changing credentialStatus.type literal from "dedi" to "dediregistry" in all examples; adding statusTimeStamp to each UsageSummary entry in the billing summary example.

🤖 Generated with Claude Code

[Anusree-J]

Some comments:

1. Seems like https://naesb.org/espi/ is not an open URL; schema validation will fail
2. Terms like serviceKind, intervalBlocks, intervalBlock are mapped to class IRIs (espi:ServiceKind, espi:IntervalBlock) instead of property IRIs. In JSON-LD, context terms must map to properties, not
   classes. Fix mappings to use the correct property IRIs (e.g., meter:serviceKind, meter:intervalBlocks).
3. Fix coveragePeriod structure mismatch

• attributes.yaml defines coveragePeriod with start + end
• vocab.jsonld declares its range as meter:DateTimeInterval
• But DateTimeInterval (from Green Button) uses start + duration, not start + end

4. credential subject id is seperate from DID - i think we used customer id in other VCs
5. intervalBlocks can be moved underreadingType instead of credentialSubject
6. do we need interval length since we have interval blocks?
7. Little confused about the reasoning behind keeping value as int and having powerOfTenMultiplier property

[ameetdesh]

Some comments:

1. Seems like https://naesb.org/espi/ is not an open URL; schema validation will fail

replaced this by https://nfh-trust-labs.github.io/vc-schemas/energy-credentials/billing-summary-vc/context.jsonld

2. Terms like serviceKind, intervalBlocks, intervalBlock are mapped to class IRIs (espi:ServiceKind, espi:IntervalBlock) instead of property IRIs. In JSON-LD, context terms must map to properties, not
   classes. Fix mappings to use the correct property IRIs (e.g., meter:serviceKind, meter:intervalBlocks).

fixed this.

3. Fix coveragePeriod structure mismatch

• attributes.yaml defines coveragePeriod with start + end
• vocab.jsonld declares its range as meter:DateTimeInterval

fixed.

• But DateTimeInterval (from Green Button) uses start + duration, not start + end

Interval blocks now use start + duration

4. credential subject id is seperate from DID - i think we used customer id in other VCs

Can you check if this resolves it? I did not understand this fully.

5. intervalBlocks can be moved underreadingType instead of credentialSubject

Per Green button examples that Vish shared of his actual bills,intervalBlocks and readingType are in parallel, and not nested.

6. do we need interval length since we have interval blocks?

https://utilityapi.com/docs/greenbutton/xml#ReadingType If intervalLength is not provided in interval blcoks, one from ReadingType seems to be the default one.

7. Little confused about the reasoning behind keeping value as int and having powerOfTenMultiplier property

Now keeping both float & int values, at slight deviation from GB schema, but making it backward compatible. Thanks for suggesting.

[ameetdesh]

Hi @Anusree-J this was the closest to the smart meter type I found.

See AMR vs. AMI difference here.