openapi: 3.1.1
info:
  title: EnergyTradeDelivery — Performance / Fulfillment Attributes (v2.0)
  version: 2.0.0
  description: >
    Fulfillment attributes for energy trade deliveries. Attached to
    Performance.performanceAttributes in on_status callbacks to report
    physical delivery of energy including status, mode, curtailment, and
    meter-reading telemetry.

    Meter readings are carried as a BecknTimeSeries in performanceTimeseries:
      BUYER_ALLOCATION  — energy consumed by buyer's meter (kWh)
      SELLER_INJECTION  — energy injected by seller's meter (kWh)
      SETTLED_QTY       — agreed settled quantity for revenue computation (kWh)

    Interval ids correspond to the seller's offerTimeseries interval ids,
    so the rego policy can match SETTLED_QTY to PRICE_PER_KWH by id.

components:
  schemas:
    EnergyTradeDelivery:
      type: object
      additionalProperties: true
      x-tags:
        - energy-trade
        - p2p-trading
        - fulfillment
        - delivery
      x-jsonld:
        "@context": ./context.jsonld
        "@type": EnergyTradeDelivery
      properties:

        deliveryStatus:
          type: string
          enum: [PENDING, IN_PROGRESS, COMPLETED, FAILED]
          description: Overall delivery status across all intervals.
          example: "COMPLETED"
          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

        performanceTimeseries:
          $ref: "https://raw.githubusercontent.com/beckn/DEG/refs/heads/main/specification/schema/BecknTimeSeries/v1.0/attributes.yaml#/components/schemas/BecknTimeSeries"
          description: >
            Per-interval meter readings as a BecknTimeSeries.
            payloadDescriptors MUST declare:
              BUYER_ALLOCATION  with units: KWH
              SELLER_INJECTION  with units: KWH
              SETTLED_QTY       with units: KWH
            Interval ids MUST correspond to the seller's offerTimeseries ids.
            The revenue rego matches SETTLED_QTY to PRICE_PER_KWH by interval id.
          x-jsonld:
            "@id": performanceTimeseries

        deliveredQuantity:
          type: number
          minimum: 0
          description: Total quantity delivered across all intervals (kWh).
          example: 32.7
          x-jsonld:
            "@id": deliveredQuantity

        curtailedQuantity:
          type: number
          minimum: 0
          description: Quantity curtailed from original contracted amount (kWh).
          example: 2.3
          x-jsonld:
            "@id": curtailedQuantity

        curtailmentReason:
          type: string
          enum: [GRID_OUTAGE, EMERGENCY, CONGESTION, MAINTENANCE, OTHER]
          description: Reason for curtailment (if any).
          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: "2026-04-26T06:30:00Z"
          x-jsonld:
            "@id": "schema:dateModified"