openapi: 3.1.1
info:
  title: MeterServiceProfile
  version: 1.1.0
  description: |
    Tariff, regulatory load, and connection profile for a single meter
    connection point. Links to a METER resource via meterId.

    v1.1 change: power/demand fields now use QuantitativeValue {value, unit}
    instead of unit-suffixed scalars (sanctionedLoadKw → sanctionedLoad, etc.).
    The unit field holds a QUDT unit code (e.g. KiloW). This connects to
    qudt:QuantitativeValue / qudt:unit in the JSON-LD context.

    Aligns with CIM UsagePoint (IEC 61968-9).
    Used by ElectricityCredential/v1.2 consumptionProfiles[].
    Formerly called ConsumptionProfile — that alias is preserved.

    Optional admin attribute (non-breaking; optional):
      serviceStatus — service-connection lifecycle state (active | suspended
                      | closed). CIM: UsagePoint.status.

    Canonical IRI: https://schema.nfh.global/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:

    QVPower:
      $id: https://schema.nfh.global/EnergyResourceCommon/v1.1#/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]

    MeterServiceProfile:
      $id: https://schema.nfh.global/MeterServiceProfile/v1.1#/components/schemas/MeterServiceProfile
      type: object
      description: >
        Tariff and regulatory load profile for one meter connection point.
        meterId links to a METER entry in energyResources[].
        CIM: UsagePoint (IEC 61968-9).
      required:
        - meterId
        - sanctionedLoad
        - tariffCategoryCode
      x-tags:
        - electricity
        - credential
        - tariff
        - meter
      x-jsonld:
        "@id": deg:MeterServiceProfile
      properties:
        meterId:
          type: string
          minLength: 1
          description: Matches the id of a METER entry in customerProfile.energyResources[].
          x-jsonld:
            "@id": deg:meterId
        sanctionedLoad:
          $ref: "#/components/schemas/QVPower"
          description: "Sanctioned/approved import load."
          x-standard: "CIM (IEC 61968-9 UsagePoint)"
          x-jsonld:
            "@id": deg:sanctionedLoad
        sanctionedExportLoad:
          $ref: "#/components/schemas/QVPower"
          description: "Sanctioned/approved grid export limit."
          x-jsonld:
            "@id": deg:sanctionedExportLoad
        billingCycleDay:
          type: integer
          minimum: 1
          maximum: 31
          description: Day of month on which the billing cycle resets.
          x-jsonld:
            "@id": deg:billingCycleDay
        contractMaxDemand:
          $ref: "#/components/schemas/QVPower"
          description: "Maximum demand contracted with the utility for this connection."
          x-jsonld:
            "@id": deg:contractMaxDemand
        tariffCategoryCode:
          type: string
          minLength: 1
          description: "Billing/tariff category code assigned by the utility."
          x-standard: "CIM (IEC 61968-9 UsagePoint.serviceCategory)"
          x-jsonld:
            "@id": deg:tariffCategoryCode
        premisesType:
          type: string
          enum:
            - Residential
            - Commercial
            - Industrial
            - Agricultural
          description: Type of premises at the metering point.
          x-jsonld:
            "@id": deg:premisesType
        connectionType:
          type: string
          enum:
            - Single-phase
            - Three-phase
          description: "Electrical connection type."
          x-standard: "CIM (IEC 61968-9 UsagePoint.phaseCode)"
          x-jsonld:
            "@id": deg:connectionType
        paymentMode:
          type: string
          enum:
            - POSTPAID
            - PREPAID
          description: >
            Billing/payment modality. POSTPAID: consume now, pay later.
            PREPAID: pay-before-use.
          x-standard: "CIM (IEC 61968-9 AmiBillingReadyKind, ESPI)"
          x-jsonld:
            "@id": deg:paymentMode

        serviceStatus:
          type: string
          enum:
            - active
            - suspended
            - closed
          description: >
            Lifecycle state of the service connection (the UsagePoint), not
            of the meter device itself. 'active' = currently energised and
            billable; 'suspended' = temporarily disconnected (non-payment,
            inspection, fault) with the contract still on record; 'closed' =
            permanently terminated. Distinct from the meter device's
            operational state.
          x-standard: "CIM (IEC 61968-9 UsagePoint.status)"
          x-jsonld:
            "@id": deg:serviceStatus