$id: https://schema.beckn.io/FnBPriceSpecification/v2.0
$schema: https://json-schema.org/draft/2020-12/schema
description: |
  A price specification for food and beverage (F&B) delivery orders.

  FnBPriceSpecification specializes beckn:PriceSpecification for the specific price
  calculation structure of a food ordering and delivery transaction. It is derived
  from extensive research into how food delivery platforms (Domino's, Zomato, Swiggy,
  UberEats) model itemised bills, including:

  - Size-dependent item and topping pricing (a topping on a Regular pizza costs less
    than on a Large pizza; add-on price = f(size, topping_type))
  - Crust upcharges (premium crusts like Cheese Burst or Pan cost more)
  - Combo discount mechanics (bundle savings expressed as negative values)
  - Delivery and packaging fees distinct from item charges
  - Platform convenience charges

  **Component type codes:**

  Item-level charges (may appear multiple times — once per line item):
  - BASE_ITEM         — Base price of a food or beverage item at its selected size
  - SIZE_UPCHARGE     — Premium for selecting a larger size over the base size (e.g. Regular → Medium)
  - TOPPING           — Individual topping or ingredient add-on; price varies by item size
  - ADDON             — Optional add-on item (dip, sauce, condiment packet)
  - CUSTOMIZATION     — Surcharge for a special preparation request
  - SIDE              — A side dish added to the order

  Combo and offer adjustments (typically negative):
  - COMBO_SAVINGS     — Discount from applying a bundle/meal combo deal (negative)
  - COMBO_UPCHARGE    — Premium for upgrading within a combo (e.g. regular to medium pizza)
  - OFFER_DISCOUNT    — Time-limited promotional discount applied at order level (negative)
  - COUPON_DISCOUNT   — Discount from a promo/coupon code (negative)
  - LOYALTY_DISCOUNT  — Discount from loyalty points redemption (negative)

  Order-level charges:
  - DELIVERY_FEE      — Delivery charge (flat, distance-based, or surge-adjusted)
  - PACKAGING_FEE     — Restaurant packaging charge (boxes, insulated bags, eco-packaging)
  - SMALL_ORDER_FEE   — Surcharge applied when order value is below the minimum
  - PLATFORM_FEE      — App/platform convenience service charge

  Gratuity:
  - TIP               — Customer gratuity (added voluntarily by the consumer)

  Notes:
  - Tax components (GST, VAT, etc.) are jurisdiction-specific and MUST be modelled
    using PriceSpecificationComponent variants, not as codes in this schema.
  - For TOPPING components, referenceItemId SHOULD be set to the ID of the base
    item to which the topping belongs, since topping price varies by item size.
  - Negative values MUST be used for COMBO_SAVINGS, OFFER_DISCOUNT, COUPON_DISCOUNT,
    and LOYALTY_DISCOUNT.

  Inheritance: beckn:PriceSpecification ← beckn:FnBPriceSpecification
  schema.org alignment: schema:PriceSpecification (via inheritance)
  Use in: beckn:Consideration.considerationAttributes for F&B orders
title: FnBPriceSpecification
x-tags: [retail, food-and-beverages, pricing]
allOf:
  - $ref: 'https://schema.beckn.io/PriceSpecification/v2.0'
  - type: object
    properties:
      '@context':
        type: string
        format: uri
        const: 'https://schema.beckn.io/FnBPriceSpecification/v2.0/context.jsonld'
      '@type':
        type: string
        const: 'beckn:FnBPriceSpecification'
      currency:
        type: string
        description: ISO 4217 currency code for the order (e.g. INR, USD, EUR, GBP).
        example: INR
        x-jsonld:
          '@id': 'schema:priceCurrency'
      value:
        type: number
        description: >
          Total order amount inclusive of all item charges, delivery fees,
          platform fees, and applicable discounts.
        example: 833
        x-jsonld:
          '@id': 'schema:price'
      components:
        type: array
        description: >
          Ordered list of itemised price components that explain how the total
          order value is computed. Each component represents one charge or
          discount line on the bill.
          
          Components SHOULD appear in order from top-level items to discounts
          to fees to total.
        items:
          type: object
          required: [type, value]
          properties:
            type:
              type: string
              description: >
                Line-item type code classifying this price component.
                See schema description for full definitions.
              enum:
                # Item-level charges
                - BASE_ITEM
                - SIZE_UPCHARGE
                - TOPPING
                - ADDON
                - CUSTOMIZATION
                - SIDE
                # Combo and offer adjustments (use negative values)
                - COMBO_SAVINGS
                - COMBO_UPCHARGE
                - OFFER_DISCOUNT
                - COUPON_DISCOUNT
                - LOYALTY_DISCOUNT
                # Order-level charges
                - DELIVERY_FEE
                - PACKAGING_FEE
                - SMALL_ORDER_FEE
                - PLATFORM_FEE
                # Gratuity
                - TIP
            value:
              type: number
              description: >
                Monetary value of this component in the order currency.
                MUST be negative for COMBO_SAVINGS, OFFER_DISCOUNT,
                COUPON_DISCOUNT, and LOYALTY_DISCOUNT.
            currency:
              type: string
              description: Currency code (defaults to parent object currency).
            description:
              type: string
              description: Human-readable label for this line item.
              example: "1x Medium Peppy Paneer"
            referenceItemId:
              type: string
              description: >
                ID of the base item this component belongs to or modifies.
                Required for TOPPING, SIZE_UPCHARGE, and CRUST_UPCHARGE since
                these prices are a function of the base item's size.
                Also useful for COMBO_SAVINGS to identify which combo was applied.
            quantity:
              type: number
              description: Quantity multiplier (default 1). Use for multi-quantity line items.
              default: 1
              minimum: 1
        x-jsonld:
          '@id': 'beckn:components'