openapi: 3.1.1
info:
  title: Beckn Core Schemas v2
  description: |
    Core schemas for the Beckn Protocol v2. This file contains the fundamental
    data structures used across discovery, transaction, and other Beckn services.
  version: 2.0.0
  contact:
    name: Beckn Protocol
    url: https://becknprotocol.io
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

components:
  schemas:
    Catalog:
      type: object
      required: ["@context", "@type", "beckn:id", "beckn:descriptor", "beckn:bppId", "beckn:bppUri", "beckn:items"]
      additionalProperties: false
      properties:
        "@context":
          type: string
          format: uri
          description: JSON-LD context URI for the core Catalog schema
        "@type":
          type: string
          description: Type of the catalog
          example: "beckn:Catalog"
        "beckn:id":
          type: string
          description: Unique identifier for the catalog
          example: "catalog-electronics-001"
        "beckn:descriptor":
          $ref: '#/components/schemas/Descriptor'
        "beckn:providerId":
          type: string
          description: Reference to the provider that owns this catalog
          example: "tech-store-001"
        "beckn:bppId":
          type: string
          description: BPP (Beckn Protocol Provider) identifier that publishes this catalog
          example: "bpp.example.com"
        "beckn:bppUri":
          type: string
          format: uri
          description: BPP (Beckn Protocol Provider) URI endpoint
          example: "https://bpp.example.com"
        "beckn:validity":
          $ref: '#/components/schemas/TimePeriod'
        "beckn:isActive":
          type: boolean
          description: Whether the catalog is active
          default: true
        beckn:items:  # semantic entities
          type: array
          description: >
            Array of beckn core Item entities in this catalog, returned directly without
            ItemResult wrapper for improved performance and simplified response structure
          items: { $ref: "#/components/schemas/Item" }
        beckn:offers: # commercial wrappers referencing items
          type: array
          items: { $ref: "#/components/schemas/Offer" }

    Item:
      type: object
      required: ["@context", "@type", "beckn:id", "beckn:descriptor", "beckn:provider", "beckn:itemAttributes"]
      additionalProperties: false
      properties:
        "@context":
          type: string
          format: uri
          description: JSON-LD context URI for the core Item schema
        "@type":
          type: string
          description: Type of the core item
          enum: ["beckn:Item"]
        "beckn:id":
          type: string
          description: Unique identifier for the item
          example: "gaming-laptop-001"
        "beckn:descriptor":
          $ref: '#/components/schemas/Descriptor'
        "beckn:category":
          $ref: '#/components/schemas/CategoryCode'
        "beckn:availableAt":
          type: array
          items:
            $ref: '#/components/schemas/Location'
          description: Physical locations where the item is available
        "beckn:availabilityWindow":
          type: array
          items:
            $ref: '#/components/schemas/TimePeriod'
          description: Time periods when the item is available
        "beckn:rateable":
          type: boolean
          description: Whether the item can be rated by customers
          example: true
        "beckn:rating":
          $ref: '#/components/schemas/Rating'
        "beckn:isActive":
          type: boolean
          description: Whether the item is active
          default: true
        "beckn:networkId":
          type: array
          items:
            type: string
          description: Array of network identifiers for the BAP (Beckn App Provider) that offers this item
          example: ["bap.net/electronics", "bap.net/tech"]
        "beckn:provider":
          $ref: '#/components/schemas/Provider'
        "beckn:itemAttributes":
          $ref: '#/components/schemas/Attributes'

    Offer:
      type: object
      additionalProperties: false
      required:
        - "@context"
        - "@type"
        - beckn:id
        - beckn:descriptor
        - beckn:provider
        - beckn:items
      properties:
        "@context":
          type: string
          format: uri
          example: "https://raw.githubusercontent.com/beckn/protocol-specifications-v2/refs/tags/core-2.0.0-rc-eos-release/schema/core/v2/context.jsonld"
        "@type":
          type: string
          enum: ["beckn:Offer"]
          x-jsonld: { "@id": "schema:Offer" }
        beckn:id:
          type: string
          description: Unique id for this offer
          x-jsonld: { "@id": "schema:identifier" }
        beckn:descriptor:
          $ref: "#/components/schemas/Descriptor"
        beckn:provider:
          $ref: "#/components/schemas/Provider/properties/beckn:id"
          description: Seller / provider of this offer
          x-jsonld: { "@id": "schema:seller" }
        # Single source of truth for base item(s)
        beckn:items:
          type: array
          minItems: 1
          items: { $ref: "#/components/schemas/Item/properties/beckn:id" }
          description: Base item(s) the offer applies to (single or bundle)
          x-jsonld: { "@id": "schema:itemOffered" }
        # Optional extras
        beckn:addOns:
          type: array
          items: { $ref: "#/components/schemas/Offer/properties/beckn:id" }
          description: Optional extra Offers that can be attached (e.g., warranty, gift wrap)
          x-jsonld: { "@id": "schema:addOn" }
        beckn:addOnItems:
          type: array
          items: { $ref: "#/components/schemas/Item/properties/beckn:id" }
          description: Optional extras modeled as items (e.g., toppings, accessories)
          x-jsonld: { "@id": "schema:addOn" }
        beckn:isActive:
          type: boolean
          description: Whether the offer is active
          default: true
        beckn:validity:
          $ref: "#/components/schemas/TimePeriod"
          description: Offer validity window
          x-jsonld: { "@id": "schema:availabilityStarts|schema:availabilityEnds" }
        beckn:price:
          $ref: "#/components/schemas/PriceSpecification"
          description: Price snapshot; detailed models can live in offerAttributes
          x-jsonld: { "@id": "schema:priceSpecification" }
        beckn:eligibleRegion: 
          type: array
          items:
            $ref: '#/components/schemas/Location'
          description: Regions where the offer is eligible
        beckn:acceptedPaymentMethod:
          $ref: '#/components/schemas/AcceptedPaymentMethod'
        beckn:offerAttributes:
          $ref: "#/components/schemas/Attributes"
          description: Attribute Pack attachment (pricing models, discounts, rail terms, etc.)          
              
    Attributes:
      type: object
      description: >
        JSON-LD aware bag for domain-specific attributes of an Item.
        MUST include @context (URI) and @type (compact or full IRI).
        Any additional properties are allowed and interpreted per the provided JSON-LD context.
      required: ["@context", "@type"]
      minProperties: 2
      additionalProperties: true
      properties:
        "@context":
          type: string
          format: uri
          description: JSON-LD context URI for the specific domain schema (e.g., ElectronicItem)
          example: "https://example.org/schema/items/v1/ElectronicItem/schema-context.jsonld"
        "@type":
          type: string
          description: JSON-LD type within the domain schema
          example: "beckn:ElectronicItem"              

    AcceptedPaymentMethod:
      type: array
      description: Payment methods accepted for this offer
      items:
        type: string
        enum: ["UPI", "CREDIT_CARD", "DEBIT_CARD", "WALLET", "BANK_TRANSFER", "CASH", "APPLE_PAY"]
      example: ["UPI", "Card", "Wallet"]
      x-jsonld: { "@id": "beckn:acceptedPaymentMethod" }

    Provider:
      type: object
      required: ["beckn:id", "beckn:descriptor"]
      additionalProperties: false
      properties:
        "beckn:id":
          type: string
          description: Unique identifier for the provider
          example: "tech-store-001"
        "beckn:descriptor":
          $ref: '#/components/schemas/Descriptor'
        "beckn:validity":
          $ref: '#/components/schemas/TimePeriod'
        "beckn:locations":
          type: array
          items:
            $ref: '#/components/schemas/Location'
          description: Physical locations where the provider operates
        "beckn:rateable":
          type: boolean
          description: Whether the provider can be rated by customers
          example: true
        "beckn:rating":
          $ref: '#/components/schemas/Rating'
        "beckn:providerAttributes":
          $ref: '#/components/schemas/Attributes'

    Quantity:
      type: object
      additionalProperties: false
      properties:
        unitText:
          type: string
          description: Unit for the quoted price (e.g., kWh, minute, hour, month)
          example: "kWh"
          x-jsonld: { "@id": "schema:unitText" }
        unitCode:
          type: string
          description: Unit code for the quoted price (e.g., KWH, MIN, H, MON)
          example: "KWH"
          x-jsonld: { "@id": "schema:unitCode" }
        unitQuantity:
          type: number
          description: Quantity of the unit
          example: 1
          x-jsonld: { "@id": "schema:Number" }
        minQuantity:
          type: number
          description: Minimum quantity for this price
          example: 1
          x-jsonld: { "@id": "schema:Number" }
        maxQuantity:
          type: number
          description: Maximum quantity for this price
          example: 100
          x-jsonld: { "@id": "schema:Number" }
      x-jsonld: { "@id": "schema:QuantitativeValue" }

    PriceSpecification:
      type: object
      additionalProperties: true
      properties:
        currency: { type: string, description: ISO 4217 code }
        value:    { type: number, description: Total value for this price specification }
        applicableQuantity:
          $ref: '#/components/schemas/Quantity'
          x-jsonld: { "@id": "schema:eligibleQuantity" }
        components:
          type: array
          description: Optional components (tax, shipping, discount, fee, surcharge)
          items:
            type: object
            properties:
              type: { type: string, enum: ["UNIT","TAX","DELIVERY","DISCOUNT","FEE","SURCHARGE"] }
              value: { type: number }
              currency: { type: string }
              description: { type: string }
      x-jsonld: { "@id": "schema:PriceSpecification" }
      
    Eligibility:
      type: object
      properties:
        eligibleRegion: { type: string }
        eligibleQuantity:
          type: object
          properties:
            min: { type: number }
            max: { type: number }
      x-jsonld: { "@id": "schema:DefinedRegion|schema:QuantitativeValue" }

    Descriptor:
      type: object
      required: ["@type"]
      properties:
        "@type":
          type: string
          enum: ["beckn:Descriptor"]
          description: Type of the descriptor
          example: "beckn:Descriptor"
        "schema:name":
          type: string
          description: Name of the item
          example: "Premium Gaming Laptop Pro"
        "beckn:shortDesc":
          type: string
          description: Short description of the item
          example: "High-performance gaming laptop with RTX graphics"
        "beckn:longDesc":
          type: string
          description: Detailed description of the item
          example: "Powerful gaming laptop with NVIDIA RTX graphics, fast SSD storage, and high-refresh display"
        "schema:image":
          type: array
          items: { type: string, format: uri }

    CategoryCode:
      type: object
      required: ["@type", "schema:codeValue"]
      properties:
        "@type":
          type: string
          enum: ["schema:CategoryCode"]
          description: Type of the category code
          example: "schema:CategoryCode"
        "schema:codeValue":
          type: string
          description: Category code value
          example: "electronics"
        "schema:name":
          type: string
          description: Category name
          example: "Electronics"
        "schema:description":
          type: string
          description: Category description
          example: "Electronic devices and equipment"

    TimePeriod:
      type: object
      description: Time window with date-time precision for availability/validity
      required: ["@type"]
      properties:
        "@type":
          type: string
          description: JSON-LD type for a date-time period
          example: "beckn:TimePeriod"
        "schema:startDate":
          type: string
          format: date-time
          description: Start instant (inclusive)
          example: "2025-01-27T09:00:00Z"
        "schema:endDate":
          type: string
          format: date-time
          description: End instant (exclusive or inclusive per domain semantics)
          example: "2025-12-31T23:59:59Z"
        "schema:startTime":
          type: string
          format: time
          description: Start time of the time period
          example: "09:00:00"
        "schema:endTime":
          type: string
          format: time
          description: End time of the time period
          example: "22:00:00"
      anyOf:
        - required: ["schema:startDate"]
        - required: ["schema:endDate"]
        - required: ["schema:startTime", "schema:endTime"]

    Rating:
      type: object
      required: ["@type"]
      properties:
        "@type":
          type: string
          enum: ["beckn:Rating"]
          description: Type of the rating
          example: "beckn:Rating"
        "beckn:ratingValue":
          type: number
          minimum: 0
          maximum: 5
          description: Rating value (0-5)
          example: 4.8
        "beckn:ratingCount":
          type: integer
          minimum: 0
          description: Number of ratings
          example: 1250

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          $ref: '#/components/schemas/Error'

    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          description: Error code
          example: "INVALID_SCHEMA_FIELD"
        message:
          type: string
          description: Human-readable error message
          example: "Field 'electronic:invalidField' not found in ElectronicItem schema"
        details:
          type: object
          description: Additional error details

    AckResponse:
      type: object
      additionalProperties: false
      properties:
        transaction_id:
          type: string
        timestamp:
          type: string
          format: date-time
        ack_status:
          type: string
          enum: [ACK, NACK]
        error:
          $ref: '#/components/schemas/Error'
      required: [transaction_id, timestamp, ack_status]
      allOf:
        - if:
            properties:
              ack_status:
                const: NACK
            required: [ack_status]
          then:
            required: [error]
        - if:
            properties:
              ack_status:
                const: ACK
            required: [ack_status]
          then:
            not:
              required: [error]

    # Location schema from discover.yaml
    Location:
      type: object
      description: >
        A **place** represented by **GeoJSON geometry** (Point/Polygon/Multi*) and optional
        human-readable `address`. This unifies all Beckn location fields into a single,
        widely-adopted representation (GeoJSON).
      properties:
        "@type":
          type: string
          enum: ["beckn:Location"]
        geo:
          $ref: '#/components/schemas/GeoJSONGeometry'
        address:
          oneOf:
            - type: string
            - $ref: '#/components/schemas/Address'
          description: Optional human-readable address for the same place/area.
      required: [geo]
      additionalProperties: false
      examples:
        site_point:
          value:
            geo: { type: Point, coordinates: [77.5946, 12.9716] }
            address: "MG Road, Bengaluru"
        service_area:
          value:
            geo:
              type: Polygon
              coordinates:
                - [[77.6100, 12.9200], [77.6400, 12.9200], [77.6400, 12.9500], [77.6100, 12.9500], [77.6100, 12.9200]]

    # Address schema from discover.yaml
    Address:
      type: object
      description: >
        **Postal address** aligned with schema.org `PostalAddress`. Use for human-readable
        addresses. Geometry lives in `Location.geo` as GeoJSON.
      properties:
        streetAddress:
          type: string
          description: Street address (building name/number and street).
          example: "123 Tech Street"
        extendedAddress:
          type: string
          description: Address extension (apt/suite/floor, C/O).
          example: "Apt 4B"
        addressLocality:
          type: string
          description: City/locality.
          example: "Bengaluru"
        addressRegion:
          type: string
          description: State/region/province.
          example: "Karnataka"
        postalCode:
          type: string
          description: Postal/ZIP code.
          example: "560001"
        addressCountry:
          type: string
          description: Country name or ISO-3166-1 alpha-2 code.
          example: "IN"
      additionalProperties: false

    # GeoJSONGeometry schema from discover.yaml
    GeoJSONGeometry:
      type: object
      description: >
        **GeoJSON geometry** per RFC 7946. Coordinates are in **EPSG:4326 (WGS-84)**
        and MUST follow **[longitude, latitude, (altitude?)]** order.

        Supported types:
        - Point, LineString, Polygon
        - MultiPoint, MultiLineString, MultiPolygon
        - GeometryCollection (uses `geometries` instead of `coordinates`)

        Notes:
        - For rectangles, use a Polygon with a single linear ring where the first
          and last positions are identical.
        - Circles are **not native** to GeoJSON. For circular searches, use
          `SpatialConstraint` with `op: s_dwithin` and a Point + `distanceMeters`,
          or approximate the circle as a Polygon.
        - Optional `bbox` is `[west, south, east, north]` in degrees.

      required: [type]
      properties:
        type:
          type: string
          enum:
            - Point
            - LineString
            - Polygon
            - MultiPoint
            - MultiLineString
            - MultiPolygon
            - GeometryCollection
        coordinates:
          type: array
          description: >
            Coordinates per RFC 7946 for all types **except** GeometryCollection.
            Order is **[lon, lat, (alt)]**. For Polygons, this is an array of
            linear rings; each ring is an array of positions.
        geometries:
          type: array
          description: >
            Member geometries when `type` is **GeometryCollection**.
          items:
            $ref: '#/components/schemas/GeoJSONGeometry'
        bbox:
          type: array
          description: Optional bounding box `[west, south, east, north]` in degrees.
          minItems: 4
          maxItems: 4
      additionalProperties: true
      examples:
        point:
          value:
            type: Point
            coordinates: [77.5946, 12.9716]
        polygon_rectangle:
          value:
            type: Polygon
            coordinates:
              - [[77.6100, 12.9200], [77.6400, 12.9200], [77.6400, 12.9500], [77.6100, 12.9500], [77.6100, 12.9200]]
        geometry_collection:
          value:
            type: GeometryCollection
            geometries:
              - { type: Point, coordinates: [77.60, 12.95] }
              - { type: LineString, coordinates: [[77.60, 12.95], [77.62, 12.97]] }

    # --------------------------------
    # ORDER (core)
    # --------------------------------
    Order:
      type: object
      additionalProperties: false
      required:
        - "@context"
        - "@type"
        - beckn:orderStatus
        - beckn:seller
        - beckn:buyer
        - beckn:orderItems
      properties:
        "@context":
          type: string
          format: uri
          example: "https://raw.githubusercontent.com/beckn/protocol-specifications-v2/refs/tags/core-2.0.0-rc-eos-release/schema/core/v2/context.jsonld"
        "@type":
          type: string
          enum: ["beckn:Order"]
          x-jsonld: { "@id": "schema:Order" }

        beckn:id:
          type: string
          x-jsonld: { "@id": "schema:identifier" }

        beckn:orderStatus:
          type: string
          description: Order status/state
          enum: ["CREATED","PENDING","CONFIRMED","INPROGRESS","PARTIALLYFULFILLED","COMPLETED","CANCELLED","REJECTED","FAILED","RETURNED","REFUNDED","ONHOLD"]
          x-jsonld: { "@id": "beckn:orderStatus" }

        beckn:orderNumber:
          type: string
          description: Human-visible order number
          x-jsonld: { "@id": "schema:orderNumber" }

        beckn:seller:
          $ref: "#/components/schemas/Provider/properties/beckn:id"
          x-jsonld: { "@id": "schema:seller" }

        beckn:buyer:
          $ref: "#/components/schemas/Buyer"
          x-jsonld: { "@id": "schema:customer" }

        beckn:orderItems:
          type: array
          minItems: 1
          items: { $ref: "#/components/schemas/OrderItem" }
          x-jsonld: { "@id": "schema:orderItem" }

        beckn:acceptedOffers:
          type: array
          items: { $ref: "#/components/schemas/Offer" }
          description: Offers accepted at order-level (optional if captured per line)
          x-jsonld: { "@id": "schema:acceptedOffer" }

        beckn:orderValue:
          $ref: "#/components/schemas/PriceSpecification"
          description: Order totals snapshot (derivable from lines; optional)
          x-jsonld: { "@id": "schema:priceSpecification" }

        beckn:invoice:
          $ref: '#/components/schemas/Invoice/properties/beckn:id'
          description: Invoice reference/summary
          x-jsonld: { "@id": "schema:Invoice" }

        beckn:payment:
          $ref: "#/components/schemas/Payment"
          description: Method/status; rail-specific payloads go to packs
          x-jsonld: { "@id": "schema:PaymentMethod|schema:PaymentStatusType" }

        beckn:fulfillment:
          $ref: "#/components/schemas/Fulfillment"
          description: Parcel delivery or reservation summary
          x-jsonld: { "@id": "schema:ParcelDelivery|schema:Reservation" }

        beckn:orderAttributes:
          $ref: "#/components/schemas/Attributes"
          description: Order-level Attribute Pack (vertical/regulatory specifics)

    OrderItem:
      type: object
      required: ["beckn:orderedItem"]
      properties:
        beckn:lineId:
          type: string
          description: Unique line id within order
        beckn:orderedItem:
          $ref: "#/components/schemas/Item/properties/beckn:id"
          x-jsonld: { "@id": "schema:orderedItem" }
        beckn:acceptedOffer:
          $ref: "#/components/schemas/Offer"
          description: Offer applied to this line (if different from order-level)
          x-jsonld: { "@id": "schema:acceptedOffer" }
        beckn:quantity:
          $ref: "#/components/schemas/Quantity"
          x-jsonld: { "@id": "beckn:quantity" }
        beckn:price:
          $ref: "#/components/schemas/PriceSpecification"
          description: Line price composition (unit/tax/delivery/discount)
          x-jsonld: { "@id": "schema:priceSpecification" }
        beckn:orderItemAttributes:
          $ref: "#/components/schemas/Attributes"
          description: Line-level Attribute Pack (options, substitutions, ESG, etc.)

    # --------------------------------
    # Shared refs
    # --------------------------------

    Invoice:
      type: object
      additionalProperties: false
      required: ["@context","@type","beckn:id","beckn:number","beckn:issueDate","beckn:totals","beckn:payee","beckn:payer"]
      # A commercial document snapshot for billing/tax. Rich tax regimes go in attribute packs.
      properties:
        "@context":
          type: string
          format: uri
          example: "https://raw.githubusercontent.com/beckn/protocol-specifications-v2/refs/tags/core-2.0.0-rc-eos-release/schema/core/v2/context.jsonld"
        "@type":
          type: string
          enum: ["beckn:Invoice"]
          x-jsonld: { "@id": "schema:Invoice" }
        beckn:id:
          type: string
          description: Stable invoice identifier (system id)
          x-jsonld: { "@id": "schema:identifier" }
        beckn:number:
          type: string
          description: Human-visible invoice number
          x-jsonld: { "@id": "schema:confirmationNumber" } # schema.org commonly uses confirmationNumber on docs/tickets
        beckn:issueDate:
          type: string
          format: date
          x-jsonld: { "@id": "schema:dateIssued" }
        beckn:dueDate:
          type: string
          format: date
          nullable: true
          x-jsonld: { "@id": "schema:paymentDueDate" }
        beckn:payee:
          $ref: "#/components/schemas/Provider/properties/beckn:id"
          description: Seller / issuer of the invoice
          x-jsonld: { "@id": "schema:provider" }
        beckn:payer:
          $ref: "#/components/schemas/Buyer/properties/beckn:id"
          description: Buyer being invoiced
          x-jsonld: { "@id": "schema:customer" }
        beckn:totals:
          $ref: "#/components/schemas/PriceSpecification"
          description: Invoice grand totals (tax/shipping/discount components inside)
          x-jsonld: { "@id": "schema:priceSpecification" }
        beckn:invoiceAttributes:
          $ref: "#/components/schemas/Attributes"
          description: Attribute Pack for tax regime (e.g., GST/VAT), e-invoice refs, legal boilerplate, etc. 

    # ---------------------------------
    # FULFILLMENT (core)
    # ---------------------------------
    # A single polymorphic envelope with 'type' indicating the mode. The FULL details
    # for each mode are expected to come from fulfillment attribute packs (logistics, reservation, digital).
    Fulfillment:
      type: object
      additionalProperties: false
      required: ["@context","@type","beckn:mode"]
      properties:
        "@context":
          type: string
          format: uri
          example: "https://raw.githubusercontent.com/beckn/protocol-specifications-v2/refs/tags/core-2.0.0-rc-eos-release/schema/core/v2/context.jsonld"
        "@type":
          type: string
          enum: ["beckn:Fulfillment"]
          x-jsonld: { "@id": "schema:Thing" } # Fulfillment is Beckn-native; specific packs map to ParcelDelivery/Reservation/etc.
        beckn:id:
          type: string
          description: Fulfillment identifier
          x-jsonld: { "@id": "schema:identifier" }
        # Optional minimal status/links that are mode-agnostic. Rich details live in packs.
        beckn:fulfillmentStatus:
          type: string
          description: Fulfillment status code (e.g., OutForDelivery, ReadyForPickup, Confirmed)
          x-jsonld: { "@id": "beckn:fulfillmentStatus" }
        beckn:mode:
          type: string
          enum: ["DELIVERY","PICKUP","RESERVATION","DIGITAL"]
          description: |
            DELIVERY    → last-mile / parcel logistics
            PICKUP      → customer collects from a place
            RESERVATION → entitlement/booking is fulfilled (tickets, seats, appointments)
            DIGITAL     → digital good / license access
          x-jsonld: { "@id": "beckn:mode" }
        trackingAction:
          $ref: '#/components/schemas/TrackAction'
          description: >
            Tracking entrypoint for this fulfillment, modeled as schema.org TrackAction.
            Use target.url for a clickable tracking URL; may also include deliveryMethod.
          x-jsonld:
            '@type': 'schema:TrackAction'
        beckn:deliveryAttributes:
          $ref: "#/components/schemas/Attributes"
          description: > 
            Bundle of attributes for the chosen mode: 
            # DELIVERY: endpoints, slot windows, route & events → map to schema:ParcelDelivery / schema:DeliveryEvent
            # PICKUP: pickupPlace, counter codes, time windows → map to schema:Place + schema:openingHoursSpecification
            # RESERVATION: reservationStatus, reservedTicket → map to schema:Reservation
            # DIGITAL: contentUrl/license/expiry → map to schema:DataDownload/schema:MediaObject

    TrackAction:
      type: object
      description: Minimal schema.org TrackAction for clickable tracking.
      x-jsonld:
        '@type': 'schema:TrackAction'
      properties:
        id:
          type: string
          description: Tracking action identifier
          x-jsonld: { "@id": "schema:identifier" }
        url:
          type: string
          format: uri
          description: Tracking page URL
          x-jsonld:
            '@id': 'schema:url'
      additionalProperties: true            

    # -----------------------------
    # PAYMENT (core)
    # -----------------------------
    Payment:
      type: object
      additionalProperties: false
      required: ["@context","@type","beckn:paymentStatus"]
      # Core payment semantics: rail + status + references. Rail payloads live in payment packs (UPI/Card/BNPL/Wallet).
      properties:
        "@context":
          type: string
          format: uri
          example: "https://raw.githubusercontent.com/beckn/protocol-specifications-v2/refs/tags/core-2.0.0-rc-eos-release/schema/core/v2/context.jsonld"
        "@type":
          type: string
          enum: ["beckn:Payment"]
          x-jsonld: { "@id": "schema:Thing" } # specific aspects map to PaymentMethod/PaymentStatusType
        beckn:id:
          type: string
          description: Payment record identifier
          x-jsonld: { "@id": "schema:identifier" }
        beckn:paymentStatus:
          type: string
          description: Payment lifecycle status (Pending | Authorized | Captured | Failed | Refunded | PartialRefund …)
          enum: ["INITIATED","PENDING","AUTHORIZED","CAPTURED","COMPLETED","FAILED","CANCELLED","REFUNDED","PARTIALLY_REFUNDED","CHARGEBACK","DISPUTED","EXPIRED","REVERSED","VOIDED","SETTLED","ON_HOLD","ADJUSTED"]
          x-jsonld: { "@id": "beckn:paymentStatus" }
        beckn:amount:
          type: object
          description: Amount associated with this payment action
          properties:
            currency: { type: string, x-jsonld: { "@id": "schema:priceCurrency" } }
            value:    { type: number, x-jsonld: { "@id": "schema:price" } }
        beckn:paymentURL:
          type: string
          format: uri
          description: URL for payment processing/redirection
          example: "https://payments.example.com/pay?transaction_id=123&amount=100"
          x-jsonld: { "@id": "schema:url" }
        beckn:txnRef:
          type: string
          description: PSP/gateway/bank transaction reference
          x-jsonld: { "@id": "schema:transactionNumber" }
        beckn:paidAt:
          type: string
          format: date-time
          nullable: true
          description: When the last terminal event (capture/refund) happened
          x-jsonld: { "@id": "schema:paymentDueDate" } # closest temporal anchor for payment events
        beckn:acceptedPaymentMethod:
          $ref: '#/components/schemas/AcceptedPaymentMethod'
        beckn:beneficiary:
          type: string
          description: Who will be the beneficiary or recipient of the payment
          enum: ["BPP","BAP","BUYER"]
          example: "BPP"
          x-jsonld: { "@id": "schema:beneficiary" }
        beckn:paymentAttributes:
          $ref: "#/components/schemas/Attributes"
          description: > 
            Rail-specific attribute pack (e.g., UPI: VPA/UTR; CARD: token/3DS; BNPL: plan/schedule)

    # -----------------------------
    # Buyer (core)
    # -----------------------------
    Buyer:
      type: object
      additionalProperties: false
      required: ["@context","@type","beckn:id"]
      # A minimal entity that can represent either a Person or an Organization.
      # Full identity, contact, or KYC details are supplied via buyer attribute packs.
      properties:
        "@context":
          type: string
          format: uri
          example: "https://raw.githubusercontent.com/beckn/protocol-specifications-v2/refs/tags/core-2.0.0-rc-eos-release/schema/core/v2/context.jsonld"
        "@type":
          type: string
          enum: ["beckn:Buyer"]
          x-jsonld: { "@id": "schema:Thing" } # resolved through @role into schema:Person or schema:Organization
        beckn:id:
          type: string
          description: Unique identifier for the buyer (personId or orgId in legacy schema)
          x-jsonld: { "@id": "schema:identifier" }
        beckn:role:
          type: string
          enum: ["BUYER","SELLER","INTERMEDIARY","PAYER","PAYEE","FULFILLER"]
          description: The functional role of the buyer in the transaction.
          x-jsonld: { "@id": "schema:roleName" }
        beckn:displayName:
          type: string
          description: Human-readable display name
          x-jsonld: { "@id": "schema:name" }
        beckn:telephone:
          type: string
          description: Telephone number
          x-jsonld: { "@id": "schema:telephone" }
        beckn:email:
          type: string
          format: email
          description: Email Address
          x-jsonld: { "@id": "schema:email" }
        beckn:taxID:
          type: string
          description: Tax identifier for the buyer.
          x-jsonld: { "@id": "schema:taxID" }
        beckn:buyerAttributes:
          $ref: "#/components/schemas/Attributes"
          description: > 
            Attribute Pack reference for richer identity:
            # buyer/identity.v1 (contact details: email, phone, address)
            # buyer/org-ids.v1 (LEI, GSTIN, ISIN, CUSIP…)
            # buyer/kyc.v1 (jurisdictional compliance fields)
            # buyer/preferences.v1 (delivery preferences, accessibility needs, etc.)

    SupportInfo:
      type: object
      description: >
        Canonical support contact for an entity, mapped to schema.org ContactPoint.
      additionalProperties: false
      required: ["@context", "@type"]
      properties:
        "@context":
          type: string
          format: uri
          example: "https://raw.githubusercontent.com/beckn/protocol-specifications-v2/refs/tags/core-2.0.0-rc-eos-release/schema/core/v2/context.jsonld"
        "@type":
          type: string
          enum: ["beckn:SupportInfo"]
          x-jsonld: { "@id": "beckn:SupportInfo" }
        name:
          type: string
          description: Name of the support organization or contact.
        phone:
          type: string
          description: Telephone number.
        email:
          type: string
          format: email
          description: Support email address.
        url:
          type: string
          format: uri
          description: Webpage or chat endpoint for support.
        hours:
          type: string
          description: Human-readable support hours (local time).
        channels:
          type: array
          description: Available support channels.
          items:
            type: string
            enum: ["PHONE","EMAIL","WEB","CHAT","WHATSAPP","IN_APP","OTHER"]
      example:
        name: "Acme Support"
        phone: "+91-80-1234-5678"
        email: "support@acme.example"
        url: "https://acme.example/support"
        hours: "Mon–Sat 09:00–20:00 IST"
        channels: ["web", "phone", "email"]
      x-jsonld:
        '@type': 'schema:ContactPoint'
        'schema:contactType': '"Customer Support"'
        'schema:telephone': '$.phone'
        'schema:email': '$.email'
        'schema:url': '$.url'
        'schema:name': '$.name'
        'schema:hoursAvailable': '$.hours'

    Tracking:
      type: object
      description: >
        Non-streaming tracking handle per legacy semantics (url/transport/status).
      additionalProperties: false
      required: ["@context", "@type", "tl_method", "url", "trackingStatus"]
      properties:
        "@context":
          type: string
          format: uri
          example: "https://raw.githubusercontent.com/beckn/protocol-specifications-v2/refs/tags/core-2.0.0-rc-eos-release/schema/core/v2/context.jsonld"
        "@type":
          type: string
          enum: ["beckn:Tracking"]
          x-jsonld: { "@id": "beckn:Tracking" }
        tl_method:
          type: string
          enum: [http/get, http/post, http/redirect, ws/handle, custom]
          description: Transport/method used to access the tracking handle.  # mirrors legacy tl_method concept
        url:
          type: string
          format: uri
          description: Link/handle to off-network tracking UI or endpoint.
        trackingStatus:
          type: string
          enum: [ACTIVE, DISABLED, COMPLETED]
        expires_at:
          type: string
          format: date-time
          description: ISO 8601 expiry timestamp for the tracking handle.
      example:
        tl_method: "http/get"
        url: "https://track.bpp.example?order_id=ORD-123"
        trackingStatus: "active"
        expires_at: "2025-10-16T18:30:00Z"
      x-jsonld:
        '@type': 'schema:TrackAction'
        'schema:target':    '$.url'           # URL to track → EntryPoint(target)
        'schema:deliveryMethod': '$.tl_method'
        'beckn:trackingStatus': '$.trackingStatus'

    RatingInput:
      type: object
      additionalProperties: false
      required: ["@context","@type","id","ratingValue"]
      properties:
        "@context":
          type: string
          format: uri
          example: "https://raw.githubusercontent.com/beckn/protocol-specifications-v2/refs/tags/core-2.0.0-rc-eos-release/schema/core/v2/context.jsonld"
        "@type":
          type: string
          enum: ["beckn:RatingInput"]
          x-jsonld: { "@id": "beckn:RatingInput" }
        id:
          type: string
          description: Target entity ID being rated (order/item/fulfillment/provider/agent).
        ratingValue:
          type: number
          description: Numeric rating value (legacy usually 1–5).  # remains permissive
          minimum: 0
        bestRating:
          type: number
          description: Maximum of the rating scale (default 5 if omitted).
        worstRating:
          type: number
          description: Minimum of the rating scale (default 1 or 0 if omitted).
        category:
          type: string
          description: What is being rated.
          enum: [ORDER, FULFILLMENT, ITEM, PROVIDER, AGENT, OTHER]
        feedback:
          type: object
          additionalProperties: false
          properties:
            comments: { type: string }
            tags:
              type: array
              items: { type: string }
      x-jsonld:
        '@type': 'schema:Rating'
        'schema:itemReviewed': '$.id'
        'schema:ratingValue':  '$.value'
        'schema:bestRating':   '$.best'
        'schema:worstRating':  '$.worst'
    
    Form:
      description: Describes a form
      type: object
      required: ["@context", "@type"]
      properties:
        "@context":
          type: string
          format: uri
          example: "https://raw.githubusercontent.com/beckn/protocol-specifications-v2/refs/tags/core-2.0.0-rc-eos-release/schema/core/v2/context.jsonld"
        "@type":
          type: string
          enum: ["beckn:Form"]
          x-jsonld: { "@id": "beckn:Form" }
        url:
          description: The URL from where the form can be fetched. The content fetched from the url must be processed as per the mime_type specified in this object. Once fetched, the rendering platform can choosed to render the form as-is as an embeddable element; or process it further to blend with the theme of the application. In case the interface is non-visual, the the render can process the form data and reproduce it as per the standard specified in the form.
          type: string
          format: uri
        data:
          description: The form submission data
          type: object
          additionalProperties:
            type: string
        mime_type:
          description: This field indicates the nature and format of the form received by querying the url. MIME types are defined and standardized in IETF's RFC 6838.
          type: string
          enum:
            - text/html
            - application/xml
        submission_id:
          type: string
          format: uuid