openapi: 3.1.1
info:
  title: ElectricityCredential
  version: 1.2.0
  description: >
    W3C Verifiable Credential (VC Data Model 2.0) issued per meter by
    electricity distribution utilities.

    v1.2 introduces composable EnergyResource kinds. energyResources[] entries
    are now discriminated by 'type' into one of seven kinds:
      - EnergyResourceMeter     (type: METER)
      - EnergyResourceGenerator (type: SOLAR_PV | SOLAR | WIND | HYDRO | BIOGAS | CHP | FUEL_CELL)
      - EnergyResourceStorage   (type: BESS | BATTERY)
      - EnergyResourceEVCharger (type: EV_CHARGER | EV_V2G)
      - EnergyResourceInverter  (type: INVERTER)
      - EnergyResourceLoad      (type: SMART_HVAC | SMART_WATER_HEATER | CONTROLLABLE_LOAD)
      - EnergyResourceNetwork   (type: DT | BUS | FEEDER | MICROGRID)

    Each kind's attributes bag inherits EnergyResourceCommon/v1.1 via allOf.
    All power and capacity fields use QuantitativeValue {value, unit} connected
    to QUDT via JSON-LD context. Unit strings are QUDT codes (KiloW, KiloW-HR,
    KiloV-A, KiloV-A_Reactive, KiloV).

    EV_CHARGER and EV_V2G are their own kind — NOT storage.
    storageCapacity (QuantitativeValue) is ONLY on EnergyResourceStorage (BESS).

    CIM alignment: IEC 61970-301/302 (GeneratingUnit, BatteryUnit,
    PowerElectronicsConnection, EnergyConsumer, Feeder) and IEC 61968-9 (Meter, EndDevice).

    v1.1 → v1.2 field renames (all as QuantitativeValue)
    ──────────────────────────────────────────────────────
    ratedPowerKw → ratedPower, maxExportKw → maxExport, maxImportKw → maxImport
    nominalPowerKw → nominalPower, storageCapacityKwh → storageCapacity
    ratedApparentPowerKva → ratedApparentPower
    maxReactivePowerKvar → maxReactivePower, minReactivePowerKvar → minReactivePower
    nominalVoltageKv → nominalVoltage
    sanctionedLoadKw → sanctionedLoad, contractMaxDemandKw → contractMaxDemand

    consumptionProfiles[] items use MeterServiceProfile/v1.1.

jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
servers:
  - url: https://schema.nfh.global
    description: Canonical schema registry
paths: {}
components:
  schemas:

    ElectricityCredential:
      $id: https://schema.nfh.global/ElectricityCredential/v1.2
      title: ElectricityCredential
      type: object
      additionalProperties: true
      allOf:
        - $ref: "https://schema.nfh.global/EnergyCredential/v2.0"
      x-tags:
        - energy
        - credential
        - verifiable-credential
        - electricity
        - customer
        - deg
      x-jsonld:
        "@context": ./context.jsonld
        "@type": ElectricityCredential
      properties:
        credentialSubject:
          type: object
          required:
            - customerProfile
          x-jsonld:
            "@id": deg:credentialSubject
          properties:
            id:
              type: string
              format: uri
              description: Optional DID of the customer/credential subject.
              x-jsonld:
                "@id": "@id"
            customerProfile:
              $ref: "#/components/schemas/CustomerProfile"
            customerDetails:
              $ref: "#/components/schemas/CustomerDetails"

    CustomerProfile:
      type: object
      description: >
        Non-PII customer identity and asset list. Supports arbitrary topologies:
        a single customerNumber may span multiple METER entries (different premises,
        sub-meters, parallel meters) each with child DERs.
      required:
        - customerNumber
        - energyResources
      x-jsonld:
        "@id": deg:customerProfile
      properties:
        customerNumber:
          type: string
          minLength: 1
          description: Utility customer account (CA) number.
          x-jsonld:
            "@id": deg:customerNumber
        idRef:
          $ref: "#/components/schemas/IdRef"
        energyResources:
          type: array
          minItems: 1
          description: >
            All physical energy assets for this account. Each entry is
            discriminated by 'type' into one of seven composable kinds.
          x-jsonld:
            "@id": deg:energyResources
          items:
            $ref: "#/components/schemas/EnergyResource"
        consumptionProfiles:
          type: array
          minItems: 1
          description: >
            Tariff and load characteristics per meter connection.
            Each entry links to a METER via meterId.
          x-jsonld:
            "@id": deg:consumptionProfiles
          items:
            $ref: "#/components/schemas/ConsumptionProfile"

    IdRef:
      $ref: "https://schema.nfh.global/IdRef/v1.0/attributes.yaml#/components/schemas/IdRef"
      description: External identity reference for the customer. Defined in IdRef/v1.0.

    ConsumptionProfile:
      $ref: "https://schema.nfh.global/MeterServiceProfile/v1.1/attributes.yaml#/components/schemas/MeterServiceProfile"
      description: >
        Tariff and regulatory load profile for one meter connection.
        meterId links to a METER entry in customerProfile.energyResources[].
        Uses MeterServiceProfile/v1.1 (sanctionedLoad, contractMaxDemand as QuantitativeValue).

    CustomerDetails:
      $ref: "https://schema.nfh.global/CustomerDetails/v1.0/attributes.yaml#/components/schemas/CustomerDetails"
      description: >
        PII section — fullName, installationAddress, serviceConnectionDate.
        fullName appears ONLY here — never in customerProfile or resource entries.
        Defined in CustomerDetails/v1.0.

    EnergyResource:
      $ref: "https://schema.nfh.global/EnergyResource/v2.1/attributes.yaml#/components/schemas/EnergyResource"
      description: >
        Discriminated union of all seven typed EnergyResource kinds, each
        inheriting id, type, subResources, parentResources, and attributes
        from EnergyResourceCommon/v1.1. All power/capacity fields use
        QuantitativeValue. Defined in EnergyResource/v2.1.