openapi: 3.0.3
info:
  title: Virtual Interlining API
  version: 2.5.0
  description: |
    This API specification can be downloaded in [OpenAPI](https://openapis.org) format. Many [code generator tools](https://openapi-generator.tech/docs/generators) are available to generate client code in different programming languages based on the specification file.

    > For example, to generate client code in Java, run following command.
    > 
    > ```
    > openapi-generator-cli generate -g java -o newpathfly -i openapi.yaml
    > ```

    A SDK has been prebuilt for Java based projects. See [here](https://github.com/newpathfly/newpathfly-public-sdk) for more details.

    # Introduction

    ## What is Virtual Interlining?
    ​
    Interlining is an airline-industry-specific term. Carriers come to an agreement with others, or join an alliance, and then passengers can fly to their destination using all of those airlines in agreement. 

    Virtual interlining is where the technology behind the scenes organizes the means for passengers to travel on multiple carriers on a single itinerary even without an agreement. Our virtual interlining technology not only gives your more content in addition to GDS, it also gives contents with more competitive pricing.

  contact:
    name: newpathfly

servers:
  - url: http://uat-api.newpathfly.com/v2
  - url: http://api.newpathfly.com/v2

tags:
  - name: Shopping
    description: |
      Search for virtual interlining offerings of cheapest flights.

  - name: Booking
    description: |
      Place booking orders of virtually interlined flights.

  - name: Payments
    description: |
      Make payments to booking orders of virtually interlined flights.

  # Enums
  - name: FareClass
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/FareClass" />

  - name: SeatStatus
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/SeatStatus" />

  - name: TripType
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/TripType" />

  # Common Schemas
  - name: Flight
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Flight" />

  - name: Segment
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Segment" />

  - name: SegmentGroup
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/SegmentGroup" />

  # Shopping Schemas
  - name: SearchRequest
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/SearchRequest" />

  - name: SearchResponse
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/SearchResponse" />

  - name: PollRequest
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/PollRequest" />

  - name: PollResponse
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/PollResponse" />

  - name: IncrementalPollRequest (BETA)
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/IncrementalPollRequest" />

  - name: IncrementalPollResponse (BETA)
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/IncrementalPollResponse" />

  - name: Query
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Query" />

  - name: Trip
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Trip" />

  - name: Price
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Price" />

  # Booking Schemas
  - name: Check
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Check" />

  - name: CheckResponse
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/CheckResponse" />

  - name: CheckStatus
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/CheckStatus" />

  - name: CheckStatusResponse
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/CheckStatusResponse" />

  - name: Order
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Order" />

  - name: OrderResponse
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/OrderResponse" />

  - name: OrdersResponse
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/OrdersResponse" />

  - name: OrderStatus
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/OrderStatus" />

  - name: OrderStatusResponse
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/OrderStatusResponse" />

  - name: Customer
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Customer" />

  - name: Passenger
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Passenger" />

  - name: TravelDocument
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/TravelDocument" />

  # Payment Schemas
  - name: Payment
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Payment" />

  - name: PaymentResponse
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/PaymentResponse" />

  - name: CreditCard
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/CreditCard" />

x-tagGroups:
  - name: API
    tags:
      - Shopping
      - Booking
      - Payments

  - name: Enums
    tags:
      - FareClass
      - SeatStatus
      - TripType

  - name: Common Schemas
    tags:
      - Flight
      - Segment
      - SegmentGroup

  - name: Shopping Schemas
    tags:
      - SearchRequest
      - SearchResponse
      - PollRequest
      - PollResponse
      - IncrementalPollRequest (BETA)
      - IncrementalPollResponse (BETA)
      - Query
      - Trip
      - Price

  - name: Booking Schemas
    tags:
      - Check
      - CheckResponse
      - CheckStatus
      - CheckStatusResponse
      - Order
      - OrderResponse
      - OrdersResponse
      - OrderStatus
      - OrderStatusResponse
      - Customer
      - Passenger
      - TravelDocument

  - name: Payment Schemas
    tags:
      - Payment
      - PaymentResponse
      - CreditCard

paths:
  # Shopping
  /shopping/searches:
    post:
      summary: Create a search request
      description: |
        A `SearchResponse` containing a `requestId` will be returned given a valid `SearchRequest`.

        This `requestId` is required for polling for results later on.
      operationId: createSearch
      tags:
        - Shopping
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchRequest"
      responses:
        "200":
          $ref: "#/components/responses/SearchResponseOK"
        "400":
          $ref: "#/components/responses/SearchResponseBadRequest"

  /shopping/polls:
    post:
      summary: Poll for search results
      description: |
        A `PollResponse` containing full or partial search results will be returned, given a valid `PollRequest` including a `requestId`.

        Corresponding response status code indicates whether another poll is neccessary until all results are returned.
      operationId: createPoll
      tags:
        - Shopping
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PollRequest"
      responses:
        "200":
          $ref: "#/components/responses/PollResponseOK"
        "206":
          $ref: "#/components/responses/PollResponsePartial"
        "400":
          $ref: "#/components/responses/PollResponseBadRequest"

  /shopping/incrementalpolls:
    post:
      summary: Incremental poll for search results (BETA)
      description: |

        A `IncrementalPollResponse` will be returned, given a `IncrementalPollRequest` including a `requestId`, and zero or more `flightKey` values corresponding to zero or more selected flights from previous `IncrementalPollResponse` if applicable.

        Unlike regular poll above, incremental poll returns results based on flights previously selected by client. It can provide a better experience for the client by making incremental choices.

        Before the `IncrementalPollResponse` of entire `Trip`, which is a `Trip` that includes all `Flight` records, is returned,

        - `segmentGroups` will be empty, because it is not ready for booking.
        - `prices` will be the lowest of all `Trip` records matching the selected `Flight` records.

        >
        > For example, to search for a round-trip, in other words, a `Trip` of an departure `Flight` and a return `Flight`,
        > 
        > - First call to this endpoint without any `flightKey` would result in a list of `Trip` records with only an outbound `Flight` in each.
        >
        > - Secong call to this endpoint with the `flightKey` of a selected outbound `Flight`, would result in a list of `Trip` records with both `Flight` records in each, which forms a round-trip.
        >

        Corresponding response status code indicates whether another poll is neccessary until results are returned.

      operationId: createIncrementalPoll
      tags:
        - Shopping
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncrementalPollRequest"
      responses:
        "200":
          $ref: "#/components/responses/IncrementalPollResponseOK"
        "206":
          $ref: "#/components/responses/IncrementalPollResponsePartial"
        "400":
          $ref: "#/components/responses/IncrementalPollResponseBadRequest"

  # booking
  /booking/checks:
    post:
      summary: Create a booking check of specific trip
      description: |
        A `CheckResponse` with an unique `checkId` will be returned, given a `Check` including a list of `segmentGroups` and information of `passengers`.

        The list of `segmentGroups` should come from a specific `Trip` included in a `PollResponse`.

        An optional `extended` map of `key:value` pairs can be used to assoicate certain custom data with this particular request for future tracking.

        > For example, it is recommended to pass a client side order ID to this `extended` map, so later when a response is returned it is convenient to identify the corresponding order at client side.

      operationId: createCheck
      tags:
        - Booking
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Check"
      responses:
        "200":
          $ref: "#/components/responses/CheckResponseOK"
        "400":
          $ref: "#/components/responses/CheckResponseBadRequest"

  /booking/checks/{checkId}:
    get:
      summary: Retrieve a booking check
      description: |
        A `CheckResponse` containing a `Check` with the same `checkId` will be returned, given a `checkId` previously returned.

        The `CheckStatus` for the `checkId` should be retrieved beforehand.

        - If the `CheckStatus` is `completed`, the `Check` record should include the final `totalAmount` in specific `currency`.
        - Otherwise, the `Check` record will not include the final `totalAmount`.

        An optional `extended` map of `key:value` pairs can be used to assoicate certain custom data with this particular request for future tracking.

        > For example, it is recommended to pass a client side order ID to this `extended` map, so later when a response is returned it is convenient to identify the corresponding order at client side.

      operationId: getCheck
      tags:
        - Booking
      parameters:
        - $ref: "#/components/parameters/CheckId"
      responses:
        "200":
          $ref: "#/components/responses/CheckResponseOK"
        "404":
          $ref: "#/components/responses/CheckResponseNotFound"

  /booking/checks/{checkId}/status:
    get:
      summary: Retrieve the status of a booking check
      description: |
        A `CheckStatusResponse` containing the `CheckStatus` of a booking check will be returned, given a `checkId` previously returned.

        If the `segmentGroups` from the check request are available for booking with respect to the information of `passengers`, the a success `checkStatus` of will be returned along with a `totalAmount` in particular `currency`.

        For any reason for which the check failed, an error `checkStatus` will be returned.

      operationId: getCheckStatus
      tags:
        - Booking
      parameters:
        - $ref: "#/components/parameters/CheckId"
      responses:
        "200":
          $ref: "#/components/responses/CheckStatusResponseOK"
        "404":
          $ref: "#/components/responses/CheckStatusResponseNotFound"

  /booking/orders:
    post:
      summary: Create a booking order of specific flight
      description: |
        An `OrderResponse` containing the booking `Order` with an unique `orderId` will be returned along with `totalAmount` in particular `currency`, given an booking `Order` including the `checkId` previously returned, and information of `Customer` and information of each `Passenger`.

        An optional `extended` map of `key:value` pairs can be used to assoicate certain custom data with this particular request for future tracking.

        > For example, it is recommended to pass a client side order ID to this `extended` map, so later when a response is returned it is convenient to identify the corresponding order at client side.
      operationId: createOrder
      tags:
        - Booking
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Order"
      responses:
        "200":
          $ref: "#/components/responses/OrderResponseOK"
        "400":
          $ref: "#/components/responses/OrderResponseBadRequest"

    get:
      summary: Retrieve one or more booking orders
      description: |
        An `OrdersResponse` containing one or more matching booking `Order` records will be returned, given one or more criteria in the query string.

        Results will also be paged based on `offset` and `size`.
      operationId: getOrders
      tags:
        - Booking
      parameters:
        - $ref: "#/components/parameters/CustomerPhoneNumber"
        - $ref: "#/components/parameters/CustomerEmail"
        - $ref: "#/components/parameters/PassengerTravelDocumentNumber"
        - $ref: "#/components/parameters/Offset"
        - $ref: "#/components/parameters/Size"
        - $ref: "#/components/parameters/DateTimeStart"
        - $ref: "#/components/parameters/DateTimeEnd"
        - $ref: "#/components/parameters/OrderStatus"
      responses:
        "200":
          $ref: "#/components/responses/OrdersResponseOK"
        "400":
          $ref: "#/components/responses/OrdersResponseBadRequest"

  /booking/orders/{orderId}:
    get:
      summary: Retrieve a booking order
      description: |
        A booking `Order` with the `orderId` will be returned, given a specific `orderId`.
      operationId: getOrder
      tags:
        - Booking
      parameters:
        - $ref: "#/components/parameters/OrderId"
      responses:
        "200":
          $ref: "#/components/responses/OrderResponseOK"
        "404":
          $ref: "#/components/responses/OrderResponseNotFound"

    delete:
      summary: Cancel a booking order that is neither cancelled nor completed
      description: |
        The booking order with specified `orderId` will be cancelled, if its status is neither `cancelled` nor `completed`.

        > IMPORTANT:
        >
        > Calling this endpoint does not cancel a `completed` booking order, i.e. a booking order that is already paid. It certainly does not provide any refund because it can only cancel a booking order that is not already paid.

      operationId: cancelOrder
      tags:
        - Booking
      parameters:
        - $ref: "#/components/parameters/OrderId"
      responses:
        "200":
          $ref: "#/components/responses/EmptyOK"
        "400":
          $ref: "#/components/responses/EmptyBadRequest"
        "404":
          $ref: "#/components/responses/EmptyNotFound"

  /booking/orders/{orderId}/status:
    get:
      summary: Retrieve the status of a booking order
      description: |
        An `OrderStatusResponse` containing the `OrderStatus` of a booking order will be returned, given a specific `orderId`.
      operationId: getOrderStatus
      tags:
        - Booking
      parameters:
        - $ref: "#/components/parameters/OrderId"
      responses:
        "200":
          $ref: "#/components/responses/OrderStatusResponseOK"
        "404":
          $ref: "#/components/responses/OrderStatusResponseNotFound"

  # Payment
  /booking/payments:
    post:
      summary: Make a payment to a booking order recently placed
      description: |
        A `PaymentResponse` containing the `Payment` with an unique `paymentId` will be made and returned, given a `Payment` with `orderId`, `totalAmount` in specific `currency` along with `creditCard` information.
      operationId: createPayment
      tags:
        - Payments
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Payment"
      responses:
        "200":
          $ref: "#/components/responses/PaymentResponseOK"
        "400":
          $ref: "#/components/responses/PaymentResponseBadRequest"
        "402":
          $ref: "#/components/responses/PaymentResponseFailed"
        "409":
          $ref: "#/components/responses/PaymentResponseConflict"

  /booking/payments/{paymentId}:
    get:
      summary: Retrieve information about a payment
      description: |
        A `PaymentResponse` containing the `Payment` information will be returned, given a specific `paymentId`.
      operationId: getPayment
      tags:
        - Payments
      parameters:
        - $ref: "#/components/parameters/PaymentId"
      responses:
        "200":
          $ref: "#/components/responses/PaymentResponseOK"
        "400":
          $ref: "#/components/responses/PaymentResponseBadRequest"

components:
  parameters:
    # Booking
    CheckId:
      name: checkId
      in: path
      required: true
      schema:
        type: string
        description: UUID
        example: 23246c8e-11ad-4105-845b-07ad855649c3

    OrderId:
      name: orderId
      in: path
      required: true
      schema:
        type: string
        description: UUID
        example: a7dd1cf6-dc96-490b-bdf6-8685dbf5bb87

    OrderStatus:
      name: orderStatus
      description: |
        For status definition, see `OrderStatus` under *Order Schemas*.
      in: query
      schema:
        type: string
        enum:
          - creating
          - ready
          - cancelled
          - completed
          - error

    CustomerPhoneNumber:
      name: customerPhoneNumber
      description: Customer phone number (without country code)
      in: query
      schema:
        type: string
        example: "1234567890"

    CustomerEmail:
      name: customerEmail
      description: Customer email address
      in: query
      schema:
        type: string
        example: peter_parker@yahoo.com

    PassengerTravelDocumentNumber:
      name: passengerTravelDocumentNumber
      description: Travel document number, such as passport number, of a passenger
      in: query
      schema:
        type: string
        example: EG12345678

    # Payment
    PaymentId:
      name: paymentId
      in: path
      required: true
      schema:
        type: string
        description: UUID
        example: 956de7da-ece8-4ba1-acf4-37aeda78cb13

    # Common
    DateTimeStart:
      name: dateTimeStart
      description: |
        A start date-time earlier than any booking order returned. It should be in ISO 8601 format (UTC).
      in: query
      schema:
        type: string
        format: date-time

    DateTimeEnd:
      name: dateTimeEnd
      description: |
        A end date-time later than any booking order returned. It should be in ISO 8601 format (UTC).
      in: query
      schema:
        type: string
        format: date-time

    # Pagination
    Offset:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
        default: 0

    Size:
      name: size
      in: query
      schema:
        type: integer
        minimum: 1
        default: 20

  responses:
    # Search
    SearchResponseOK:
      description: |
        OK
        > This is a `SearchResponse` containing a `requestId` that can be referred to in `PollRequest`.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SearchResponse"

    SearchResponseBadRequest:
      description: |
        Bad Request
        > Check if anything incorrect or missing in the given `SearchRequest`. See `message` for any error message.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SearchResponse"
          example:
            message: "Bad Request"

    PollResponseOK:
      description: |
        OK
        >
        > All have been returned. There is no more result available.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PollResponse"

    PollResponsePartial:
      description: |
        Partial
        >
        > There are more results available to be polled for the same `PollRequest`.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PollResponse"

    PollResponseBadRequest:
      description: |
        Partial
        >
        > There are more results available to be polled for the same `PollRequest`.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PollResponse"
          example:
            message: "Bad Request"

    IncrementalPollResponseOK:
      description: |
        OK
        >
        > This is the last `IncrementalPollResponse` for the current `IncrementalPollRequest`. There is no more available.
        >
        > (If a non-existing `requestId` or `flightKey` was provided, a `IncrementalPollResponse` with empty result set will be returned.)
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/IncrementalPollResponse"

    IncrementalPollResponsePartial:
      description: |
        Partial
        >
        > This is a `IncrementalPollResponse` for the same `IncrementalPollRequest`. There are more available.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/IncrementalPollResponse"

    IncrementalPollResponseBadRequest:
      description: |
        Bad Request
        >
        > Check if anything incorrect or missing in the given `IncrementalPollRequest`. See `message` for any error message.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/IncrementalPollResponse"
          example:
            message: "Bad Request"

    # Booking
    CheckResponseOK:
      description: |
        OK
        > This is a `CheckResponse` containing a `Check` with unique `checkId` that can be referred to when obtaining `CheckStatus` or in creating an `Order`.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CheckResponse"

    CheckResponseBadRequest:
      description: |
        Bad Request
        > Check if anything incorrect or missing in the given `Check`. See `message` for any error message.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CheckResponse"
          example:
            message: "Bad Request"

    CheckResponseNotFound:
      description: |
        Not Found
        > No `Check` could be found for the specific `checkId`. See `message` for any error message.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CheckResponse"
          example:
            message: "Not Found"

    CheckStatusResponseOK:
      description: |
        OK
        > This is a `CheckStatusResponse` containing the `CheckStatus` for the given `checkId`.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CheckStatusResponse"

    CheckStatusResponseNotFound:
      description: |
        Not Found
        > No `CheckStatus` could be found for the specific `checkId`. See `message` for any error message.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CheckStatusResponse"
          example:
            message: "Not Found"

    OrderResponseOK:
      description: |
        OK
        > This is an `OrderResponse` containing the `Order` with a unique `orderId` that can be referred to when obtaining `OrderStatus`.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OrderResponse"

    OrderResponseBadRequest:
      description: |
        Bad Request
        > Check if anything incorrect or missing in the given `Order`. See `message` for any error message.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OrderResponse"
          example:
            message: "Bad Request"

    OrderResponseNotFound:
      description: |
        Not Found
        > No `Order` could be found for the specific `orderId`. See `message` for any error message.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OrderResponse"
          example:
            message: "Not Found"

    OrdersResponseOK:
      description: |
        OK
        > This is an `OrdersResponse` containing an array of zero or more `Order` records.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OrdersResponse"

    OrdersResponseBadRequest:
      description: |
        Bad Request
        > Check if anything incorrect or missing in the given criteria. See `message` for any error message.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OrdersResponse"
          example:
            message: "Bad Request"

    OrderStatusResponseOK:
      description: |
        OK
        > This is a `OrderStatusResponse` containing the `OrderStatus` for the given `orderId`.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OrderStatusResponse"

    OrderStatusResponseNotFound:
      description: |
        Not Found
        > No `OrderStatus` could be found for the specific `orderId`. See `message` for any error message.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OrderStatusResponse"
          example:
            message: "Not Found"

    # Payment
    PaymentResponseOK:
      description: |
        OK
        > This is an `PaymentResponse` containing the `Payment` with a unique `paymentId` that can be referred to when obtaining the `Payment`.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PaymentResponse"

    PaymentResponseBadRequest:
      description: |
        Bad Request
        > Check if anything incorrect or missing in the given `Payment`. See `message` for any error message.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PaymentResponse"
          example:
            message: "Bad Request"

    PaymentResponseFailed:
      description: |
        Payment Required
        > The given `Payment` failed for some reason. See `message` for any error message.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PaymentResponse"
          example:
            message: "Payment Required"

    PaymentResponseConflict:
      description: |
        Conflict
        > The `Order` associated with the `orderId` in the given `Payment` might have already been paid.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PaymentResponse"
          example:
            message: "Conflict"

    # Common
    EmptyOK:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BaseResponse"

    EmptyBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BaseResponse"
          example:
            message: "Bad Request"

    EmptyNotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BaseResponse"
          example:
            message: "Not Found"

  schemas:
    # Common
    BaseResponse:
      properties:
        message:
          readOnly: true
          description: message returned by server side if there is any
          type: string
          example: ""

    FareClass:
      description: This is the fare class, which is one of `Economy`, `PremiumEconomy`, `Business` and `First`.
      type: string
      default: Economy
      enum:
        - Economy
        - PremiumEconomy
        - Business
        - First

    Flight:
      description: A flight is a pair of original departure to final destination.
      properties:
        flightKey:
          description: A unique string generated for the flight
          type: string
          example: 20211128:1740:HEL:CPH:AY959-20211129:1100:CPH:BCN:VY1871-20211129:1850:BCN:CDG:VY8240
        segments:
          description: |
            A flight consists of one or more segments.

            > For example, a direct flight from Toronto (YYZ) to London (LON) is a flight consists of exactly one flight segment.
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/Segment"

    SegmentGroup:
      description: |
        A list of segment groups, where each segment group is a list of segments suggested to be placed within the same booking order.
      properties:
        segmentGroupId:
          type: string
          description: UUID
          readOnly: true
          example: 1feefb95-7b9e-49e4-828c-b1844dd9d9ec
        depDate:
          description: This is the departure date in `YYYYMMDD` format.
          type: string
          pattern: '^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$'
          example: "20210401"
        depAirport:
          description: This is the departure airport specified using its IATA code.
          type: string
          minLength: 3
          maxLength: 3
          example: LON
        arrAirport:
          description: This is the arrival airport specified using its IATA code.
          type: string
          minLength: 3
          maxLength: 3
          example: CGN
        carrier:
          description: This is the 2-letter IATA carrier code
          type: string
          minLength: 2
          maxLength: 2
          example: AC
        retDate:
          description: This is the return date in `YYYYMMDD` format. Only available when type == RT.
          type: string
          pattern: '^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$'
          example: "20210401"
        type:
          $ref: "#/components/schemas/TripType"
        segments:
          description: |
            A segment group consists of one or more segments. 

            > For example, a direct flight from Toronto (YYZ) to London (LON) is a flight consists of exactly one flight segment.
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/Segment"

    Segment:
      description: A segment is a pair of departure and arrival without any stop in-between.
      properties:
        fareClass:
          $ref: "#/components/schemas/FareClass"
        depDate:
          description: This is the departure date in `YYYYMMDD` format.
          type: string
          pattern: '^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$'
          example: "20210401"
        depTime:
          description: This is the departure time in `HH:mm` format.
          type: string
          readOnly: true
          pattern: "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$"
          example: "12:45"
        depAirport:
          description: This is the departure airport specified using its IATA code.
          type: string
          minLength: 3
          maxLength: 3
          example: LON
        arrDate:
          description: This is the arrival date in `YYYYMMDD` format.
          type: string
          pattern: '^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$'
          example: "20210401"
        arrTime:
          description: This is the arrival time in `HH:mm` format.
          type: string
          readOnly: true
          pattern: "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$"
          example: "17:50"
        arrAirport:
          description: This is the arrival airport specified using its IATA code.
          type: string
          minLength: 3
          maxLength: 3
          example: CGN
        flightNo:
          description: This is the flight number starting with carrier IATA code.
          type: string
          example: AC103
        carrier:
          description: This is the 2-letter IATA carrier code
          type: string
          minLength: 2
          maxLength: 2
          example: AC

    Extended:
      description: |
        Extended data from client side to associate. This is useful for storing some information later needs to be retrieved, such as client side order ID. The data is in form of `key:value` pairs. All data will be returned in response.
      type: object
      additionalProperties:
        type: string
        description: |
          a custom value associated with this booking order
      example:
        clientsideOrderId: O1234
        clientsideCustomField1: A
        clientsideCustomField2: B
        clientsideCustomField3: C

    # Search Request
    SearchRequest:
      description: |
        @todo
      required:
        - queries
        - adultAmount
      properties:
        queries:
          description: This is a list containing the same number of queries as the number of flights for the trip. For one-way trip there should be one query, whereas for round trip there should be two queries.
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/Query"
        type:
          $ref: "#/components/schemas/TripType"
        adultAmount:
          description: This is the number of adult passengers
          type: integer
          minimum: 1
        childAmount:
          description: This is the number of child passengers
          type: integer
          minimum: 0
        infantAmount:
          description: This is the number of infant passengers
          type: integer
          minimum: 0
        fareClass:
          $ref: "#/components/schemas/FareClass"

    SearchResponse:
      description: This is the response when a `SearchRequest` is accepted.
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
      properties:
        requestId:
          description: This value should be included in the polling later on.
          type: string
          example: OW|Economy|1-0-0|UnlimitedStarter-UnlimitedCandidate|20210901:@YTO:@AMS

    # Poll
    PollRequest:
      description: |
        @todo
      required:
        - requestId
      properties:
        requestId:
          description: This is the request ID found in the `SearchResponse`.
          type: string
          example: OW|Economy|1-0-0|UnlimitedStarter-UnlimitedCandidate|20210901:@YTO:@AMS
        offset:
          description: This is the offset of the results to be polled next.
          type: integer
          minimum: 0
          default: 100
        size:
          description: This is the maximum number of results to be polled. The actual number of results might be less when there is no more results available at the moment.
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        currency:
          description: Currency code of results to be polled.
          type: string
          minLength: 3
          maxLength: 3
          example: USD
          default: USD

    PollResponse:
      description: This result contains up to the number of flight trips specified by `size` in the request.
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
      properties:
        currencyCode:
          description: This is the 3-letter currency code in which price is provided.
          type: string
          minLength: 3
          maxLength: 3
          example: EUR
        trips:
          description: This is a list of trips based on `queries` and `TripType` in the corresponding `SearchRequest`.
          type: array
          items:
            $ref: "#/components/schemas/Trip"

    IncrementalPollRequest:
      description: |
        @todo
      required:
        - requestId
      properties:
        requestId:
          description: This is the request ID found in the `SearchResponse`.
          type: string
          example: OW|Economy|1-0-0|UnlimitedStarter-UnlimitedCandidate|20210901:@YTO:@AMS
        flightKeys:
          description: This is a list of zero or more `flightKey` values corresponding to zero or more flights selected from a trip in the previous `IncrementalPollResponse`.
          type: array
          items:
            type: string
            example: 20211128:1740:HEL:CPH:AY959-20211129:1100:CPH:BCN:VY1871-20211129:1850:BCN:CDG:VY8240
        offset:
          description: This is the offset of the results to be polled next.
          type: integer
          minimum: 0
          default: 100
        size:
          description: This is the maximum number of results to be polled. The actual number of results might be less when there is no more results available at the moment.
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        currency:
          description: Currency code of results to be polled.
          type: string
          minLength: 3
          maxLength: 3
          example: USD
          default: USD

    IncrementalPollResponse:
      description: This result contains up to the number of flight trips specified by `size` in the request.
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
      properties:
        currencyCode:
          description: This is the 3-letter currency code in which price is provided.
          type: string
          minLength: 3
          maxLength: 3
          example: EUR
        trips:
          description: This is a list of trips based on `queries` and `TripType` in the corresponding `SearchRequest`.
          type: array
          items:
            $ref: "#/components/schemas/Trip"

    # Domain Models
    Query:
      description: This is a flight query from departure airport to arrival airport on specific departure date. This query corresponding to a single flight in a trip, where a one-way trip contains only one flight and a round trip contains two flights.
      required:
        - depCity
        - depAirport
        - arrCity
        - arrAirport
        - date
      properties:
        depCity:
          description: This is the departure city specified using its IATA code.
          type: string
          minLength: 0
          maxLength: 3
          example: LON
        depAirport:
          description: This is the departure airport specified using its IATA code.
          type: string
          minLength: 0
          maxLength: 3
          example: LON
        arrCity:
          description: This is the arrival city specified using its IATA code.
          type: string
          minLength: 0
          maxLength: 3
          example: PAR
        arrAirport:
          description: This is the arrival airport specified using its IATA code.
          type: string
          minLength: 0
          maxLength: 3
          example: CGN
        date:
          description: This is the departure date in `YYYYMMDD` format
          type: string
          pattern: '^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$'
          example: "20210401"

    Trip:
      description: A `Trip` is one complete travel. It can be one-way `Trip` or a round `Trip`, depending on the number of included `Flight` records.
      properties:
        flights:
          description: A one-way `Trip` consists of one `Flight`. A round `Trip` consists of a departure `Flight` and a returning `Flight`.
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/Flight"
        segmentGroups:
          description: |
            A list of `SegmentGroup` records, where each `SegmentGroup` is a list of `Segment` records suggested to be placed within the same booking order.

          type: array
          readOnly: true
          minItems: 1
          items:
            $ref: "#/components/schemas/SegmentGroup"
        prices:
          $ref: "#/components/schemas/Prices"

    Prices:
      description: This is a map between each price type and the actual pricing information. `ADT`, `CHD` and `INF` correspond to each individual passenger type. `ALL` corresponds to all passengers. The total price in `ALL` should equal to `ADT` * `adultAmount` + `CHD` * `childAmount` + `INF` * `infantAmount`.
      properties:
        ADT:
          $ref: "#/components/schemas/Price"
        CHD:
          $ref: "#/components/schemas/Price"
        INF:
          $ref: "#/components/schemas/Price"
        ALL:
          $ref: "#/components/schemas/Price"

    Price:
      description: This is the pricing information including `price`, `tax` and `totalPrice`.
      properties:
        price:
          description: This it the before tax price.
          type: number
          format: double
          minimum: 0
          example: 123.45
        tax:
          description: This it the tax.
          type: number
          format: double
          minimum: 0
          example: 6.78
        totalPrice:
          description: This it the total price including tax.
          type: number
          format: double
          minimum: 0
          example: 130.23
        seatsStatus:
          $ref: "#/components/schemas/SeatStatus"
        currencyCode:
          description: This is the 3-letter currency code in which price is provided.
          type: string
          minLength: 3
          maxLength: 3
          example: EUR

    SeatStatus:
      description: Seat status is `EMPTY` when there is no seat. Else, it is `LIMITED` when there are less than 8 seats. Else, it is `ENOUGH`.
      type: string
      enum:
        - EMPTY
        - ENOUGH
        - LIMITED
      example: ENOUGH

    TripType:
      description: This is the trip type, where `OW` is for one-way trip and `RT` is for round trip.
      type: string
      default: OW
      enum:
        - OW
        - RT

    # Booking
    Check:
      required:
        - segmentGroups
        - passengers
      properties:
        checkId:
          type: string
          description: UUID
          readOnly: true
          example: 23246c8e-11ad-4105-845b-07ad855649c3
        currency:
          type: string
          readOnly: true
          description: |
            3-letter currency code in ISO 4217 format
          example: EUR
        totalAmount:
          type: number
          readOnly: true
          description: |
            Total price amount of all passengers for the flight, including tax and miscellaneous fees.
          example: 456.78
        segmentGroups:
          type: array
          description: |
            A list of segment groups, where each segment group is a list of segments suggested to be placed within the same booking order.
          minItems: 1
          items:
            $ref: "#/components/schemas/SegmentGroup"
        passengers:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/Passenger"
        extended:
          $ref: "#/components/schemas/Extended"

    CheckResponse:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
      properties:
        check:
          $ref: "#/components/schemas/Check"

    CheckStatus:
      properties:
        status:
          description: |
            | status     | description               |
            |------------|---------------------------|
            |`pending`   | booking check in progress |
            |`completed` | booking check succeeded   |
            |`error`     | booking check error       |
          readOnly: true
          type: string
          default: pending
          enum:
            - pending
            - completed
            - error
        lastUpdated:
          readOnly: true
          description: |
            Update date-time when check status was last changed. It should be in ISO 8601 format (UTC).
          type: string
          format: date-time

    CheckStatusResponse:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
      properties:
        checkStatus:
          $ref: "#/components/schemas/CheckStatus"

    Order:
      required:
        - checkId
        - customer
        - passengers
      properties:
        orderId:
          type: string
          description: UUID
          readOnly: true
          example: a7dd1cf6-dc96-490b-bdf6-8685dbf5bb87
        createdAt:
          type: string
          readOnly: true
          description: |
            Creation date/time of the booking order in ISO 8601 format (UTC)
          format: date-time
        currency:
          type: string
          readOnly: true
          description: |
            3-letter currency code in ISO 4217 format
          example: EUR
        totalAmount:
          type: number
          readOnly: true
          description: |
            Total price amount of all passengers for the flight, including tax and miscellaneous fees.
          example: 456.78
        checkId:
          type: string
          description: UUID
          example: 23246c8e-11ad-4105-845b-07ad855649c3
        customer:
          $ref: "#/components/schemas/Customer"
        passengers:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/Passenger"
        extended:
          $ref: "#/components/schemas/Extended"

    OrderResponse:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
      properties:
        order:
          $ref: "#/components/schemas/Order"

    OrdersResponse:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
      properties:
        orders:
          type: array
          items:
            $ref: "#/components/schemas/Order"

    OrderStatus:
      properties:
        status:
          description: |
            | status    | description                              |
            |-----------|------------------------------------------|
            |`creating` | the booking order is getting created     |
            |`ready`    | the booking order is to be paid          |
            |`cancelled`| manually cancelled or timed out          |
            |`completed`| paid booking order                       |
            |`error`    | some error happened to the booking order |

          readOnly: true
          type: string
          default: ready
          enum:
            - creating
            - ready
            - cancelled
            - completed
            - error
        paymentId:
          readOnly: true
          nullable: true
          type: string
          description: UUID
          example: 956de7da-ece8-4ba1-acf4-37aeda78cb13
        lastUpdated:
          readOnly: true
          description: |
            Update date-time when booking order status was last changed. It should be in ISO 8601 format (UTC).
          type: string
          format: date-time

    OrderStatusResponse:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
      properties:
        orderStatus:
          $ref: "#/components/schemas/OrderStatus"

    Customer:
      description: |
        Customer information, including contact information for booking order related issues
      allOf:
        - $ref: "#/components/schemas/Person"
        - properties:
            phoneCountryCode:
              type: string
              description: |
                Country calling code defined by ITU, starting with international dialing prefix `+`
              example: "+1"
            phoneNumber:
              type: string
              description: |
                Phone number including area code without any punctuation
              example: "1234567890"
            email:
              type: string
              example: "peter_parker@yahoo.com"

    Passenger:
      allOf:
        - $ref: "#/components/schemas/Person"
        - properties:
            type:
              type: string
              description: |
                - Adult
                - Child
                - Infant
              default: ADT
              enum:
                - ADT
                - CHD
                - INF
            birthday:
              type: string
              description: |
                Passenger birthday in `YYYY-MM-DD` format
              format: date
              example: "2001-01-01"
            gender:
              type: string
              enum:
                - F
                - M
            travelDocument:
              $ref: "#/components/schemas/TravelDocument"

    Person:
      properties:
        firstName:
          type: string
          example: Peter
        lastName:
          type: string
          example: Parker

    TravelDocument:
      description: |
        Passenger travel document
      properties:
        type:
          description: |
            Type of travel document
          type: string
          default: PASSPORT
          enum:
            - DRIVER_LICENSE
            - NATIONAL_ID
            - PASSPORT
        number:
          type: string
          description: |
            Travel document number
          example: EG12345678
        expiryDate:
          type: string
          description: |
            Travel document expiry date in `YYYY-MM-DD` format
          format: date
        placeOfIssue:
          type: string
          description: |
            Place (e.g. country, province, city) where the travel document was issued
          example: USA

    # Payment
    Payment:
      required:
        - orderId
        - currency
        - totalAmount
        - creditCard
      properties:
        paymentId:
          readOnly: true
          type: string
          description: UUID
          example: 956de7da-ece8-4ba1-acf4-37aeda78cb13
        createdAt:
          readOnly: true
          description: |
            Creation date/time of the payment in ISO 8601 format (UTC)
          type: string
          format: date-time
        orderId:
          type: string
          description: UUID
          example: a7dd1cf6-dc96-490b-bdf6-8685dbf5bb87
        currency:
          type: string
          example: EUR
        totalAmount:
          type: number
          example: 456.78
        creditCard:
          $ref: "#/components/schemas/CreditCard"

    PaymentResponse:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
      properties:
        payment:
          $ref: "#/components/schemas/Payment"

    CreditCard:
      properties:
        type:
          type: string
          enum:
            - MASTERCARD
            - VISA
        number:
          type: string
          example: "5250567933594297"
        cvc:
          type: string
          example: "123"
        expiryMonth:
          type: string
          example: "08"
        expiryYear:
          type: string
          example: "24"
        holderFirstName:
          type: string
          example: Peter
        holderLastName:
          type: string
          example: Parker
        address:
          type: string
          example: "738 Winter Garden Drive"
        city:
          type: string
          example: New York
        zipCode:
          type: string
          example: "11375"
        countryCode:
          type: string
          example: US
          description: |
            2-letter ISO country code (alpha-2) as listed at https://en.wikipedia.org/wiki/ISO_3166-1