$id: "https://schema.nfh.global/EnergyTradeDelivery/v0.3"
$schema: "https://json-schema.org/draft/2020-12/schema"
title: EnergyTradeDelivery
description: >
  Fulfillment attributes for energy trade deliveries. Attached to
  orderItemAttributes.fulfillmentAttributes to track physical transfer of energy
  including delivery status, meter readings, and energy allocation data.
  consumedEnergy = energy TO customer (imported),
  producedEnergy = energy FROM customer (exported to grid).

  This is the v0.3 schema, originally defined as a component in EnergyTrade/v0.3/attributes.yaml.
x-tags:
  - energy-trade
  - p2p-trading
  - fulfillment
  - delivery
type: object
additionalProperties: false
x-jsonld:
  "@context": ./context.jsonld
  "@type": EnergyTradeDelivery
properties:

  deliveryStatus:
    type: string
    enum: [PENDING, IN_PROGRESS, COMPLETED, FAILED]
    description: Delivery status for the energy transfer.
    example: "IN_PROGRESS"
    x-jsonld:
      "@id": deliveryStatus

  deliveryMode:
    type: string
    enum: [EV_CHARGING, BATTERY_SWAP, V2G, GRID_INJECTION]
    description: Mode of energy delivery for this fulfillment.
    example: "GRID_INJECTION"
    x-jsonld:
      "@id": deliveryMode

  deliveredQuantity:
    type: number
    minimum: 0
    description: Total quantity delivered so far in kilowatt-hours (kWh).
    example: 15.0
    x-jsonld:
      "@id": deliveredQuantity

  meterReadings:
    type: array
    description: >
      Array of meter readings for this orderItem. Each reading covers a time window
      and reports energy delivered/received during that period. Times are in UTC (ISO 8601 with Z suffix).
    items:
      type: object
      additionalProperties: false
      required: ["beckn:timeWindow", "allocatedEnergy", "unit"]
      properties:
        "beckn:timeWindow":
          type: object
          description: Time period for this meter reading (UTC).
          additionalProperties: false
          required: ["schema:startTime", "schema:endTime"]
          properties:
            "@type":
              type: string
              enum: ["beckn:TimePeriod"]
            "schema:startTime":
              type: string
              format: date-time
              pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$'
              description: Start time in UTC (ISO 8601 with Z suffix).
            "schema:endTime":
              type: string
              format: date-time
              pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$'
              description: End time in UTC (ISO 8601 with Z suffix).
        consumedEnergy:
          type: number
          minimum: 0
          description: >
            Energy consumed by the customer (imported from grid) in this time window (kWh).
            Per IEC 61968/ESPI flowDirection=1.
          x-jsonld:
            "@id": consumedEnergy
        producedEnergy:
          type: number
          minimum: 0
          description: >
            Energy produced by the customer (exported to grid) in this time window (kWh).
            Per IEC 61968/ESPI flowDirection=19.
          x-jsonld:
            "@id": producedEnergy
        allocatedEnergy:
          type: number
          minimum: 0
          description: Net energy allocated for this trade in this time window (kWh).
          x-jsonld:
            "@id": allocatedEnergy
        unit:
          type: string
          enum: ["kWh", "MWh", "Wh"]
          default: "kWh"
          description: Unit of measurement for energy values.
          x-jsonld:
            "@id": "schema:unitText"
    x-jsonld:
      "@id": meterReadings

  curtailedQuantity:
    type: number
    minimum: 0
    description: >
      Quantity curtailed from original contracted amount (kWh).
      Used by BAP/BPP to reconcile payment vs. original contracted quantity.
    example: 5.0
    x-jsonld:
      "@id": curtailedQuantity

  curtailmentReason:
    type: string
    enum: [GRID_OUTAGE, EMERGENCY, CONGESTION, MAINTENANCE, OTHER]
    description: Reason for curtailment. Useful for audit trail and dispute resolution.
    example: "GRID_OUTAGE"
    x-jsonld:
      "@id": curtailmentReason

  lastUpdated:
    type: string
    format: date-time
    description: Last delivery update timestamp in UTC (ISO 8601 with Z suffix).
    example: "2024-10-04T15:30:00Z"
    x-jsonld:
      "@id": "schema:dateModified"