openapi: 3.1.1
info:
  title: EnergyResourceGenerator
  version: 1.0.0
  description: |
    Typed attribute schema for generation DER energy resources.

    CIM alignment (IEC 61970-301/302):
      SOLAR_PV        → cim:PhotovoltaicUnit
      SOLAR           → cim:PhotovoltaicUnit (deprecated alias for SOLAR_PV)
      WIND            → cim:WindGeneratingUnit
      HYDRO           → cim:HydroGeneratingUnit
      BIOGAS          → cim:ThermalGeneratingUnit
      CHP             → cim:ThermalGeneratingUnit
      FUEL_CELL       → IEC 62933-2 fuel cell unit

    SOLAR is a deprecated alias for SOLAR_PV; new payloads should use SOLAR_PV.

    Common attributes (make, model, ratedPowerKw, maxExportKw, maxImportKw,
    telemetryProvider, commissioningDate, location) are inherited from
    EnergyResourceCommon/v1.0 via allOf.

components:
  schemas:

    EnergyResourceGenerator:
      description: >
        A generation DER energy resource (solar PV, wind, hydro, biogas, CHP,
        fuel cell). Corresponds to GeneratingUnit and its CIM subtypes
        (IEC 61970-301).
      x-tags:
        - energy-resource
        - energy
        - deg
        - generation
        - der
      x-jsonld:
        "@context": ./context.jsonld
        "@type": EnergyResourceGenerator
      allOf:
        - $ref: "https://schema.nfh.global/EnergyResourceCommon/v1.0#/components/schemas/EnergyResourceCommon"
        - type: object
          required: [id, type]
          properties:
            type:
              type: string
              enum:
                - SOLAR_PV
                - SOLAR
                - WIND
                - HYDRO
                - BIOGAS
                - CHP
                - FUEL_CELL
              description: >
                Asset-class discriminator. SOLAR is a deprecated alias for SOLAR_PV;
                new payloads should use SOLAR_PV.
                CIM classes: SOLAR_PV/SOLAR → PhotovoltaicUnit,
                WIND → WindGeneratingUnit, HYDRO → HydroGeneratingUnit,
                BIOGAS/CHP → ThermalGeneratingUnit, FUEL_CELL → IEC 62933-2.
              x-cim-class: cim:GeneratingUnit
              x-jsonld:
                "@id": erDeg:resourceType
            attributes:
              $ref: "#/components/schemas/EnergyResourceGeneratorAttributes"

    EnergyResourceGeneratorAttributes:
      description: >
        Attributes for generation DER resources. Common fields (make, model,
        ratedPowerKw, maxExportKw, maxImportKw, telemetryProvider, commissioningDate,
        location) are inherited from EnergyResourceCommonAttributes via allOf.
        Only generator-specific fields are defined here.
      x-jsonld:
        "@id": erDeg:attributes
      allOf:
        - $ref: "https://schema.nfh.global/EnergyResourceCommon/v1.0#/components/schemas/EnergyResourceCommonAttributes"
        - type: object
          additionalProperties: true
          properties:

            # ── Generator-specific attributes ────────────────────────────────

            nominalPowerKw:
              type: number
              minimum: 0
              description: >
                Nominal (nameplate) power output, kW. CIM: GeneratingUnit.nominalP.
                Typically equals the DC STC rating for solar PV.
              x-jsonld:
                "@id": erDeg:nominalPowerKw

            efficiency:
              type: number
              minimum: 0
              maximum: 100
              description: >
                Conversion efficiency as a percentage (0–100). Most relevant for
                FUEL_CELL and CHP resources.
              x-jsonld:
                "@id": erDeg:efficiency