openapi: 3.1.1
info:
  title: EnergyResourceStorage
  version: 1.1.0
  description: |
    Typed attribute schema for stationary battery energy storage resources (BESS).
    v1.1: storageCapacityKwh → storageCapacity (QuantitativeValue {value, unit});
    inherits EnergyResourceCommon/v1.1.
    CIM: BatteryUnit (IEC 61970-302).
    BATTERY is a deprecated alias for BESS.

    Optional admin attributes (non-breaking; all optional):
      roundTripEfficiencyPct — AC-to-AC round-trip efficiency (%), per
                               IEC 62933-2-1 performance test method.
                               Distinct from stateOfHealthPct (life)
                               and storage chemistry efficiency curves.

components:
  schemas:

    EnergyResourceStorage:
      description: >
        A stationary battery energy storage resource (BESS).
        CIM: BatteryUnit (IEC 61970-302).
      x-tags: [energy-resource, energy, deg, storage, bess, battery]
      x-jsonld:
        "@context": ./context.jsonld
        "@type": EnergyResourceStorage
      allOf:
        - $ref: "https://schema.nfh.global/EnergyResourceCommon/v1.1/attributes.yaml#/components/schemas/EnergyResourceCommon"
        - type: object
          required: [id, type]
          properties:
            type:
              type: string
              enum: [BESS, BATTERY]
              description: >
                Asset-class discriminator. BATTERY is deprecated — use BESS.
                CIM: BatteryUnit (IEC 61970-302).
              x-jsonld:
                "@id": erDeg:resourceType
            attributes:
              $ref: "#/components/schemas/EnergyResourceStorageAttributes"

    EnergyResourceStorageAttributes:
      description: >
        Attributes for BESS resources. Common fields (make, model,
        ratedPower, maxExport, maxImport, telemetryProvider,
        commissioningDate, location) are inherited from
        EnergyResourceCommon/v1.1 via allOf.
      x-jsonld:
        "@id": erDeg:attributes
      allOf:
        - $ref: "https://schema.nfh.global/EnergyResourceCommon/v1.1/attributes.yaml#/components/schemas/EnergyResourceCommonAttributes"
        - type: object
          additionalProperties: true
          properties:

            storageCapacity:
              $ref: "https://schema.nfh.global/EnergyResourceCommon/v1.1/attributes.yaml#/components/schemas/QVEnergy"
              description: >
                Rated stored-energy capacity. Replaces storageCapacityKwh from v1.0.
              x-standard: "CIM (IEC 61970-302 BatteryUnit.ratedE)"
              x-jsonld:
                "@id": erDeg:storageCapacity

            storageType:
              type: string
              enum: [LithiumIon, LeadAcid, FlowBattery, NaS, NiCd, Flywheel, Other]
              description: Battery storage technology type.
              x-jsonld:
                "@id": erDeg:storageType

            stateOfHealthPct:
              type: number
              minimum: 0
              maximum: 100
              description: Battery state-of-health as a percentage (0–100).
              x-jsonld:
                "@id": erDeg:stateOfHealthPct

            roundTripEfficiencyPct:
              type: number
              minimum: 0
              maximum: 100
              description: >
                AC-to-AC round-trip efficiency as a percentage (0–100): the
                fraction of energy returned to the grid relative to energy
                drawn during a full charge/discharge cycle. Distinct from
                stateOfHealthPct (cumulative life indicator) and from inverter
                conversion efficiency.
              x-standard: "IEC 62933-2-1 (performance test method)"
              x-jsonld:
                "@id": erDeg:roundTripEfficiencyPct