openapi: 3.1.1
info:
  title: EnergyResourceGenerator
  version: 1.1.0
  description: |
    Typed attribute schema for generation DER energy resources.
    v1.1: nominalPowerKw → nominalPower (QuantitativeValue {value, unit});
    inherits EnergyResourceCommon/v1.1.
    CIM: GeneratingUnit subtypes (IEC 61970-301/302).
    SOLAR is a deprecated alias for SOLAR_PV.

    Optional admin attributes (non-breaking; all optional):
      dcArrayCapacity — DC nameplate capacity of a PV array at STC
                        (industry "kWp"). Encoded as QuantitativeValue with
                        unit kW; semantically a peak/STC rating, distinct
                        from the AC-side maxExport. IS 16221; IEC 61727.

components:
  schemas:

    EnergyResourceGenerator:
      description: >
        A generation DER energy resource (SOLAR_PV, WIND, HYDRO, BIOGAS, CHP,
        FUEL_CELL). CIM: GeneratingUnit 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.1#/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 deprecated — use SOLAR_PV.
              x-jsonld:
                "@id": erDeg:resourceType
            attributes:
              $ref: "#/components/schemas/EnergyResourceGeneratorAttributes"

    EnergyResourceGeneratorAttributes:
      description: >
        Attributes for generation DER resources. Common fields inherited from
        EnergyResourceCommon/v1.1 via allOf.
      x-jsonld:
        "@id": erDeg:attributes
      allOf:
        - $ref: "https://schema.nfh.global/EnergyResourceCommon/v1.1#/components/schemas/EnergyResourceCommonAttributes"
        - type: object
          additionalProperties: true
          properties:

            nominalPower:
              $ref: "https://schema.nfh.global/EnergyResourceCommon/v1.1#/components/schemas/QVPower"
              description: >
                Nominal (nameplate) power output. Use when distinct from
                maxExport (peak).
              x-standard: "CIM (IEC 61970 GeneratingUnit.nominalP)"
              x-jsonld:
                "@id": erDeg:nominalPower

            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

            dcArrayCapacity:
              $ref: "https://schema.nfh.global/EnergyResourceCommon/v1.1#/components/schemas/QVPower"
              description: >
                DC-side nameplate capacity of a photovoltaic array at Standard
                Test Conditions (industry term: "kWp"). For PV systems this is
                typically larger than the AC-side maxExport because of inverter
                clipping and DC-to-AC ratios. Relevant for SOLAR_PV resources.
                The unit is the standard QUDT power alias kW — the STC/peak
                semantic is documented here, not encoded in the unit string.
              x-standard: "IS 16221 (PV module qualification); IEC 61727 (PV grid interface)"
              x-jsonld:
                "@id": erDeg:dcArrayCapacity