openapi: 3.1.1
info:
  title: EnergyResourceCommon
  version: 1.1.0
  description: |
    Canonical base schemas shared by all typed EnergyResource kinds.

    v1.1 change: power fields now use QuantitativeValue {value, unit}:
      ratedPowerKw   → ratedPower   (typical unit: kW)
      maxExportKw    → maxExport    (typical unit: kW)
      maxImportKw    → maxImport    (typical unit: kW)

    Optional administrative attributes added (non-breaking; all optional):
      serialNumber — manufacturer asset serial. CIM: EndDeviceInfo.serialNumber.
      inspection   — commissioning/safety inspection record (date, result,
                     inspectorId). Aligned to IEEE 1547-2018 commissioning
                     evaluations and CEA connectivity inspection.
      aggregator   — third-party demand-flex enrolment block (id, name,
                     controllable, enrolledOn). Aligned to IEEE 2030.5 and
                     IEC 61850-7-420 DER control roles.

    The unit field holds a QUDT unit code that expands to a full IRI in
    the JSON-LD context via qudt:unit (e.g. "kW" →
    http://qudt.org/vocab/unit/KiloW).

    EnergyResourceCommonAttributes — the attributes bag base.
    EnergyResourceCommon — the structural envelope inherited by every kind.

    Canonical IRI: https://schema.nfh.global/EnergyResourceCommon/v1.1

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

    QuantitativeValue:
      $id: https://schema.nfh.global/EnergyResourceCommon/v1.1/attributes.yaml#/components/schemas/QuantitativeValue
      type: object
      description: >
        A dimensioned quantity. value is the numeric magnitude; unit is a QUDT
        unit alias (e.g. kW, kWh, kVA, kVAR, kV). Mapped to QUDT IRIs via JSON-LD context.
        The JSON-LD context maps this to qudt:QuantitativeValue with qudt:value
        and qudt:unit, expanding unit to http://qudt.org/vocab/unit/<unit>.
      required: [value, unit]
      additionalProperties: false
      properties:
        value:
          type: number
          description: Numeric magnitude.
        unit:
          type: string
          description: >
            Unit alias — one of: W, kW, MW (power); kWh, MWh (energy);
            kVA, MVA (apparent power); kVAR, MVAR (reactive power);
            V, kV (voltage). Mapped to QUDT IRIs via JSON-LD context.

    QVPower:
      $id: https://schema.nfh.global/EnergyResourceCommon/v1.1/attributes.yaml#/components/schemas/QVPower
      type: object
      description: >
        Active-power quantity {value, unit}. unit is a QUDT power alias
        (W, kW, MW) expanded to a QUDT IRI via the JSON-LD context.
      required: [value, unit]
      additionalProperties: false
      properties:
        value:
          type: number
        unit:
          type: string
          enum: [W, kW, MW]

    QVEnergy:
      $id: https://schema.nfh.global/EnergyResourceCommon/v1.1/attributes.yaml#/components/schemas/QVEnergy
      type: object
      description: >
        Energy quantity {value, unit}. unit is a QUDT energy alias
        (kWh, MWh) expanded to a QUDT IRI via the JSON-LD context.
      required: [value, unit]
      additionalProperties: false
      properties:
        value:
          type: number
          minimum: 0
        unit:
          type: string
          enum: [kWh, MWh]

    QVApparentPower:
      $id: https://schema.nfh.global/EnergyResourceCommon/v1.1/attributes.yaml#/components/schemas/QVApparentPower
      type: object
      description: >
        Apparent-power quantity {value, unit}. unit is a QUDT apparent-power
        alias (kVA, MVA) expanded to a QUDT IRI via the JSON-LD context.
      required: [value, unit]
      additionalProperties: false
      properties:
        value:
          type: number
          minimum: 0
        unit:
          type: string
          enum: [kVA, MVA]

    QVReactivePower:
      $id: https://schema.nfh.global/EnergyResourceCommon/v1.1/attributes.yaml#/components/schemas/QVReactivePower
      type: object
      description: >
        Reactive-power quantity {value, unit}. unit is a QUDT reactive-power
        alias (kVAR, MVAR) expanded to a QUDT IRI via the JSON-LD context.
        value may be negative (absorption).
      required: [value, unit]
      additionalProperties: false
      properties:
        value:
          type: number
        unit:
          type: string
          enum: [kVAR, MVAR]

    QVVoltage:
      $id: https://schema.nfh.global/EnergyResourceCommon/v1.1/attributes.yaml#/components/schemas/QVVoltage
      type: object
      description: >
        Voltage quantity {value, unit}. unit is a QUDT voltage alias
        (V, kV) expanded to a QUDT IRI via the JSON-LD context.
      required: [value, unit]
      additionalProperties: false
      properties:
        value:
          type: number
          minimum: 0
        unit:
          type: string
          enum: [V, kV]

    EnergyResourceCommonAttributes:
      $id: https://schema.nfh.global/EnergyResourceCommon/v1.1/attributes.yaml#/components/schemas/EnergyResourceCommonAttributes
      type: object
      additionalProperties: true
      description: >
        Dimensioning and provenance fields shared by all resource kinds.
        Inherited inside each kind's attributes bag via allOf.
        No field is required at this level.
      x-tags:
        - energy-resource
      properties:

        make:
          type: string
          description: Manufacturer (free text).
          x-jsonld:
            "@id": deg:make

        model:
          type: string
          description: Model (free text).
          x-jsonld:
            "@id": deg:model

        ratedPower:
          $ref: "#/components/schemas/QVPower"
          description: >
            Manufacturer-rated peak power (nameplate value in principal direction).
            Kept for backward compatibility — prefer maxExport.
          x-standard: "CIM (IEC 61968-9 EndDeviceInfo.ratedPower; IEC 61970 GeneratingUnit.maxOperatingP)"
          x-jsonld:
            "@id": deg:ratedPower

        maxExport:
          $ref: "#/components/schemas/QVPower"
          description: >
            Maximum power this resource injects to the grid (generates/discharges).
            Always ≥0. For bidirectional resources (BESS, V2G) this is the max
            discharge rate. Supersedes ratedPower.
          x-standard: "CIM (IEC 61970 GeneratingUnit.maxOperatingP; IEC 61970-302 PowerElectronicsConnection.maxP, injection)"
          x-jsonld:
            "@id": deg:maxExport

        maxImport:
          $ref: "#/components/schemas/QVPower"
          description: >
            Maximum power this resource draws from the grid (absorbs/charges).
            Always ≥0. For bidirectional resources (BESS, V2G) this is the max
            charge rate.
          x-standard: "CIM (IEC 61970-302 PowerElectronicsConnection.maxP, absorption)"
          x-jsonld:
            "@id": deg:maxImport

        telemetryProvider:
          type: string
          description: Vendor API / data source identifier for telemetry.
          x-jsonld:
            "@id": deg:telemetryProvider

        commissioningDate:
          type: string
          format: date-time
          description: ISO 8601 date-time the asset was commissioned.
          x-jsonld:
            "@id": deg:commissioningDate

        location:
          $ref: "https://schema.nfh.global/Location/v2.0/attributes.yaml#/components/schemas/Location"
          description: Physical location of this asset.
          x-jsonld:
            "@id": deg:location

        serialNumber:
          type: string
          minLength: 1
          description: >
            Manufacturer-assigned device serial number from the equipment
            nameplate. Distinct from id (which is the network-issued DID).
          x-standard: "CIM (IEC 61968-9 EndDeviceInfo.serialNumber)"
          x-jsonld:
            "@id": deg:serialNumber

        inspection:
          type: object
          additionalProperties: false
          description: >
            Commissioning / safety inspection record for the asset. Captured
            by the distribution licensee at energisation and on
            re-certification events.
          x-standard: "IEEE 1547-2018 Cl. 11 (commissioning); CEA Connectivity Regs 2013 (amended 2018)"
          properties:
            date:
              type: string
              format: date
              description: ISO 8601 date the inspection was performed.
            result:
              type: string
              enum: [pass, fail, conditional]
              description: >
                Inspection outcome. 'conditional' indicates pass subject to
                remedial action.
            inspectorId:
              type: string
              minLength: 1
              description: >
                Identifier of the inspector or inspecting body, as recorded
                by the licensee.
          x-jsonld:
            "@id": deg:inspection

        aggregator:
          type: object
          additionalProperties: false
          description: >
            Third-party flexibility / demand-response enrolment for this
            asset. Present when an aggregator is authorised to dispatch or
            observe the resource. Controllability flag is asset-level; the
            asset may still be observable even when controllable is false.
          x-standard: "IEEE 2030.5; IEC 61850-7-420 (DER control roles)"
          properties:
            id:
              type: string
              format: uri
              description: >
                Aggregator identity — typically a did:web for the
                aggregator's domain.
            name:
              type: string
              description: Human-readable aggregator name (free text).
            controllable:
              type: boolean
              description: >
                True if the aggregator is authorised to issue dispatch /
                curtailment instructions. False = observation-only.
            enrolledOn:
              type: string
              format: date
              description: ISO 8601 date the asset was enrolled with the aggregator.
          x-jsonld:
            "@id": deg:aggregator

    EnergyResourceCommon:
      $id: https://schema.nfh.global/EnergyResourceCommon/v1.1/attributes.yaml#/components/schemas/EnergyResourceCommon
      type: object
      additionalProperties: true
      description: >
        Structural envelope inherited by every typed EnergyResource kind via
        allOf. Defines top-level fields common to all kinds: id, type,
        topology (subResources, parentResources), and the attributes bag.
      x-tags:
        - energy-resource
      properties:

        id:
          type: string
          description: >
            Stable identifier for this resource. For METER resources the
            meter serial number is conventional.
          example: "did:web:bescom.karnataka.gov.in:assets:meter:MET-001"
          x-jsonld:
            "@id": "@id"

        type:
          type: string
          description: >
            Asset class discriminator. Constrained to a kind-specific enum or
            const in each typed kind schema.
          x-jsonld:
            "@id": deg:resourceType

        subResources:
          type: array
          description: >
            Topology — child resources. Each item is EITHER a bare id string
            OR an inline EnergyResource object.
          items:
            oneOf:
              - type: string
              - $ref: "https://schema.nfh.global/EnergyResource/v2.1/attributes.yaml#/components/schemas/EnergyResource"
          x-jsonld:
            "@id": deg:subResources

        parentResources:
          type: array
          description: Upward topology — ids of parent resources.
          items:
            type: string
          x-jsonld:
            "@id": deg:parentResources

        attributes:
          type: object
          additionalProperties: true
          description: >
            Attribute bag. Inherits EnergyResourceCommonAttributes via allOf
            plus kind-specific fields.
          allOf:
            - $ref: "#/components/schemas/EnergyResourceCommonAttributes"
          x-jsonld:
            "@id": deg:attributes