openapi: 3.1.1
info:
  title: EnergyTradeOffer — Offer Attributes (v2.0)
  version: 2.0.0
  description: >
    Offer attributes for P2P energy trading. Attached to Offer.offerAttributes
    to provide validity windows and role-tagged inputs.

    Each role carries a BecknTimeSeries instead of a flat offers[] array:
      • seller inputs.offerTimeseries — PRICE_PER_KWH (currency: INR) and
        AVAILABLE_QTY (units: KWH) payloads, one interval per delivery slot
      • buyer  inputs.bidTimeseries  — REQUESTED_QTY (units: KWH) payloads;
        interval ids must be a subset of the seller's offerTimeseries ids

    intervalPeriod.start marks the first slot; each subsequent interval adds
    one duration (e.g. PT1H) to get its window start. This replaces the
    per-slot deliveryWindow object, reducing a 24-slot day-ahead trade from
    ~650 lines to ~50 lines.

components:
  schemas:

    EnergyTradeOffer:
      type: object
      additionalProperties: false
      x-tags:
        - energy-trade
        - p2p-trading
        - offer
      x-jsonld:
        "@context": ./context.jsonld
        "@type": EnergyTradeOffer
      properties:

        validityWindow:
          allOf:
            - $ref: "#/components/schemas/TimePeriod"
          description: >
            Time window during which this offer can be selected/accepted.
            Typically set to expire before the earliest delivery starts.
          x-jsonld:
            "@id": validityWindow

        inputs:
          type: array
          description: >
            Per-role inputs. Each entry binds a role (seller / buyer) to a
            participantId and to a BecknTimeSeries of delivery slots.
            Seller carries offerTimeseries; buyer carries bidTimeseries.
          items:
            $ref: "#/components/schemas/RoleInputs"

        contractTerms:
          type: object
          additionalProperties: true
          description: >
            JSON-LD-aware container for contract terms attached at catalog
            publish time. MUST carry @context and @type (typically DEGContract).
          required: ["@context", "@type"]
          properties:
            "@context":
              type: string
              format: uri
            "@type":
              type: string
          x-jsonld:
            "@id": contractTerms

        gift:
          type: object
          additionalProperties: true
          description: Optional gift parameters for energy gifting.
          x-jsonld:
            "@id": gift

    # ── shared sub-schemas ─────────────────────────────────────────────────

    TimePeriod:
      type: object
      additionalProperties: false
      required: ["@type", "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$'
          example: "2026-04-26T04:30:00Z"
        "schema:endTime":
          type: string
          format: date-time
          pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$'
          example: "2026-04-26T05:30:00Z"

    RoleInputs:
      type: object
      additionalProperties: false
      required: [role]
      properties:
        role:
          type: string
          enum: [buyer, seller]
          description: Role this inputs entry applies to within the offer.
        participantId:
          type: string
          description: >
            Beckn participant id of the role-holder. Bound at select/init;
            omitted at catalog publish for the buyer side.
        inputs:
          $ref: "#/components/schemas/InputBag"
      if:
        properties:
          role:
            const: seller
      then:
        properties:
          inputs:
            required: [offerTimeseries]
      else:
        properties:
          inputs:
            required: [bidTimeseries]

    InputBag:
      type: object
      additionalProperties: false
      description: >
        Role-specific inputs bag. Single-valued, role-stable attributes
        (currency, sourceType) live flat at the top; the time-varying slots
        live in a BecknTimeSeries.

        Seller: offerTimeseries with PRICE_PER_KWH and AVAILABLE_QTY payloads.
        Buyer:  bidTimeseries  with REQUESTED_QTY payloads; interval ids must
                be a subset of the seller's offerTimeseries ids. Buyer does NOT
                repeat price or availability — those are read from the seller's
                offerTimeseries by matching interval id.
      properties:

        currency:
          type: string
          minLength: 3
          maxLength: 3
          description: >
            ISO-4217 currency code (e.g. INR). Applies to PRICE_PER_KWH values
            in the seller's offerTimeseries and is also declared as the
            payloadDescriptor currency field on that type.
          example: "INR"

        sourceType:
          type: string
          enum: [SOLAR, BATTERY, GRID, HYBRID, RENEWABLE]
          description: >
            Energy source type. Seller side: generation source (e.g. SOLAR).
            Buyer side: consumption context (e.g. GRID).

        offerTimeseries:
          $ref: "https://raw.githubusercontent.com/beckn/DEG/refs/heads/main/specification/schema/BecknTimeSeries/v1.0/attributes.yaml#/components/schemas/BecknTimeSeries"
          description: >
            Seller's time-series of delivery slots (required for role=seller).
            payloadDescriptors MUST declare EVENT_PAYLOAD_DESCRIPTOR entries for:
              PRICE_PER_KWH  with currency: INR
              AVAILABLE_QTY  with units: KWH
            Each interval id is an integer starting from 0; id N corresponds to
            the delivery window starting at intervalPeriod.start + N × duration.

        bidTimeseries:
          $ref: "https://raw.githubusercontent.com/beckn/DEG/refs/heads/main/specification/schema/BecknTimeSeries/v1.0/attributes.yaml#/components/schemas/BecknTimeSeries"
          description: >
            Buyer's bid time-series (required for role=buyer).
            payloadDescriptors MUST declare EVENT_PAYLOAD_DESCRIPTOR entries for:
              REQUESTED_QTY  with units: KWH
            Interval ids MUST be a subset of the seller's offerTimeseries ids.
            The network policy enforces the subset constraint and validates that
            REQUESTED_QTY ≤ AVAILABLE_QTY for each matched interval.