TOMP-API.yaml

openapi: 3.0.0
info:
  title: Transport Operator MaaS Provider API
  description:
    An API between MaaS providers and transport operators for booking trips and corresponding assets.
    <p>The documentation (examples, process flows and sequence diagrams) can be found at <a href="https://github.com/TOMP-WG/TOMP-API/">github</a>.
  version: "0.9.0"
  license:
    name: Apache 2.0
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"

tags:
  - name: planning
    description: gives information about transport asset availability and pricing [free_bike_status and system_pricing_plans in GBFS].<p> The endpoints in this part can give information about the availability of assets (or assetTypes) and can provide information to take the next step - the booking part.

  - name: booking
    description: a booking is the main object exchanged between MaaS and a TO [from MaaS-API]. <br>See also <a href='https://github.com/maasglobal/maas-tsp-api/blob/master/specs/Booking.md'>Booking.md</a><p>This section contains functionality to book a leg (part of a trip) for one asset (or assetType), including the non-happy paths (cancel, expire etc).

  - name: booking [optional]
    description: endpoints that can faciliate processes in the booking process, but are not necessary for a minimal viable product. You can think of getting information, updating (parts of) a booking (not the state!), adding and removing subscriptions (webhook), etc.

  - name: trip execution
    description: supports the complete trip execution process. It contains f.i. getting an available asset, assigning the asset to the leg, starting, pausing, finishing a leg (all by using the POST /legs/{id}/events) or updating an execution (not the state!).

  - name: trip execution [optional]
    description: endpoints that can facilitate processes in the trip execution process, but are not necessary for a minimal viable product.

  - name: general
    description: general operations (e.g. notifications)

  - name: operator information
    description: gives information about systems, stations, operating hours [from GBFS]

  - name: payment
    description: arranges financial settlement for legs

  - name: support
    description: support for the user while the leg is ongoing

  - name: TO
    description: the Transport Operator's endpoints

  - name: MP
    description: the MaaS Service Provider's endpoints

# security. Allowed methods basic (in header: Authorization: Basic ZGVtbzpwQDU1dzByZA==),
#                           bearer (in header: Authorization: Bearer <token>)
#                           Api-key (in header: X-API-Key: abcdef12345)
#                           OAuth2 and OpenId are also available
# The exact ways to authenticate will be described in a later version
security:
  - BasicAuth: []
  - BearerAuth: []
  - ApiKeyAuth: []
  - OAuth: []
  - OpenId: []

paths:
  /plannings/:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
    post:
      description:
        Returns plannings for the given travel plan. <p>Start time can be defined, but is optional. If startTime is not provided, but required by the third party API, a default value of "Date.now()" is used. [from MaaS-API /listing].
        During the routing phase this service can be used to check availability without any state changes. <p>In the final check, just before presenting the alternatives to the user, a call should be made using `booking-intent`, requesting the TO to provide booking IDs to reference to during communication with the MP.
        <p>see (2.1) in the process flow - planning
      tags:
        - planning
        - TO
      parameters:
        - name: booking-intent
          in: query
          description: Specifies whether IDs should be returned for the leg options that can be referred to when booking
          schema:
            type: boolean
            default: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/planningRequest"
      responses:
        "201":
          description: Available transport methods matching the given query parameters. If no transport methods are available, an empty array is returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/planning"
          headers:
            Location:
              description: The URI where the most up to date version of the created planning result can be found. Not required.
              schema:
                type: string
                example: "/plannings/1234"
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
        "202":
          $ref: "#/components/responses/202Accepted"
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"

  /plannings/{id}:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
      - name: id
        in: path
        description: Planning identifier
        required: true
        schema:
          type: string
    get:
      description: Returns the planning result.
      tags:
        - planning [optional]
        - TO
      responses:
        "200":
          description: The planning was found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/planning"
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "404":
          $ref: "#/components/responses/404NotFound"
        "410":
          $ref: "#/components/responses/410Gone"

  /bookings/:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
    post:
      description:
        Creates a new `Booking` for the TO in **Pending** state. The ID of the posted booking should be the ID provided in the previous step (planning).
        <p>The Booking may be modified in the response, e.g. location being adjusted for a more suitable pick-up location.
        In addition, the service may contain a **meta** attribute for arbitrary TO metadata that the TO needs later, and **token** attribute depicting how long the current state is valid.
        <p>The optional webhook can be used to post updates from TO to MP. If it isn't used, the subscription possibility in this API can be used or the events can be posted directly.
        <p> see (3.2) in the process flow - booking
      tags:
        - booking
        - TO
      requestBody:
        description: One of available legs, returned by /plannings, with an ID.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/bookingRequest"

      responses:
        "201":
          description: A new booking was succesfully created, status pending
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/booking"
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
            Expires:
              description: The result is valid until this timestamp. The pending booking is expired after this timestamp. This option can be used, but there is also a facility to use the webhook, mentioned in '#/component/schemas/booking'.
              schema:
                description: A HTTP date string, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expires
                type: string
                format: http-date
              required: true
        "202":
          $ref: "#/components/responses/202Accepted"
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "404":
          $ref: "#/components/responses/404NotFound"
        "409":
          $ref: "#/components/responses/409Conflict"
      callbacks: # webhooks
        # as described in https://swagger.io/docs/specification/callbacks/
        booking-operations:
          "{$request.body#/webhook}":
            patch:
              description: see POST /bookings/{id}/events
              responses:
                "200":
                  description: operation ok
    get:
      description: Optional - Returns bookings that has been created earlier, selected on state.
      tags:
        - booking [optional]
        - TO
      parameters:
        - name: state
          in: query
          required: true
          schema:
            $ref: "#/components/schemas/bookingState"

      responses:
        "200":
          description: The bookings matching the query
          content:
            application/json:
              schema:
                type: array
                description: The bookings that matched the query (zero or more)
                items:
                  $ref: "#/components/schemas/booking"
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"

  /bookings/{id}/events:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
      - name: id
        in: path
        description: Leg identifier
        required: true
        schema:
          type: string
    post:
      description: This endpoint **must** be used to alter the state of a booking:<br>- The operation 'CANCEL' Cancels the booking (see <4> in the process flow - booking), <br>- the operation 'EXPIRE' informs that the booking-option is expired (seel <5> in the process flow - booking) and <br>- the 'COMMIT' actually makes this booking option a real confirmed booking. (see also (3.2) in process flow - booking). This event should also be used to commit in the 'postponed-commit' scenario.<br> - 'DENY' tells the MP that the leg is cancelled in the post-commit scenario. <p> `CANCEL` - Cancels a confirmed booking. Cancelling twice should still return 204. <br> `EXPIRE` - Typically for sending back a signal from TO to MP to tell the pending state is expired. Expiring twide should return 204. Expiring a booking in a non-pending state will result in 403. <BR> `COMMIT` - Turns the booking in a confirmed state, after all legs are in state pending. Committing twice will result in 204. If the booking is in state CANCELLED or EXPIRED, a commit will result a 403. <BR> `DENY` - Used for the 'postponed-commit' scenario. Whenever a TO cannot give garantees directly to fullfil a booking, it can return a 'COMMIT', but the state of the booking object should be 'POSTPONED-COMMIT'. In the conditions returned in the planning phase is stated until when this phase can be. After this time it will be come expired. Otherwise it can be commmitted when the leg is confirmed or denied (using this event).
      tags:
        - booking
        - MP
        - TO
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/bookingOperation"
      responses:
        "200":
          description: The modified booking
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/booking"
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
        "204":
          $ref: "#/components/responses/204NoContent"
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "403":
          $ref: "#/components/responses/403Forbidden"
        "404":
          $ref: "#/components/responses/404NotFound"
        "410":
          $ref: "#/components/responses/410Gone"

  /bookings/{id}:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
      - name: id
        in: path
        description: Booking identifier
        required: true
        schema:
          type: string
    get:
      description: Returns the booking. See (3.5.2) in the process flow - booking. In the 'meta'-field the digital tickes can be returned (see (3.3) in the process flow - booking)
      tags:
        - booking
        - TO
      responses:
        "200":
          description: The booking was found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/booking"
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "404":
          $ref: "#/components/responses/404NotFound"
        "410":
          $ref: "#/components/responses/410Gone"
    put:
      description: Optional - This endpoint should be used to adjust the parameters of the booking. Changes not acceptable to the TO should return 400. If a booking is started and can no longer be adjusted the TO should return 403. The state of the booking should **never** be adjusted using this method. Use /bookings/{id}/events for that. See also (7.2) in the flow diagram - booking.
      tags:
        - booking
        - TO
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/booking"
        description: changed booking
        required: true

      responses:
        "200":
          description: The booking was modified
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/booking"
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "403":
          $ref: "#/components/responses/403Forbidden"
        "404":
          $ref: "#/components/responses/404NotFound"
        "409":
          $ref: "#/components/responses/409Conflict"
        "410":
          $ref: "#/components/responses/410Gone"

  /bookings/{id}/subscription:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
      - name: id
        in: path
        description: Booking identifier
        required: true
        schema:
          type: string
    post:
      description: Optional - subscribe to a specific booking (=leg & (type of) asset). This is an optional endpoint. This endpoint facilitates notifications in all the phases. (see (7.1) in the flow chart - execution)
      tags:
        - booking [optional]
        - TO
        - MP
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/booking"
      responses:
        "204":
          $ref: "#/components/responses/204NoContent"
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "404":
          $ref: "#/components/responses/404NotFound"
        "410":
          $ref: "#/components/responses/410Gone"
      callbacks: # webhooks
        # as described in https://swagger.io/docs/specification/callbacks/
        booking-operations:
          "{$request.body#/webhook}":
            patch:
              description: see POST /booking/{id}/events
              responses:
                "200":
                  description: operation ok
    delete:
      description: Optional - subscribe to a specific booking (=leg & (type of) asset). This is an optional endpoint
      tags:
        - booking [optional]
        - TO
        - MP
      responses:
        "204":
          $ref: "#/components/responses/204NoContent"
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "404":
          $ref: "#/components/responses/404NotFound"
        "410":
          $ref: "#/components/responses/410Gone"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"

  /bookings/{id}/notifications:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
      - name: id
        in: path
        description: Booking identifier
        required: true
        schema:
          type: string
    get:
      description: retrieves all notifications concerning events related to this booking.
      tags:
        - general
        - TO
      responses:
        "200":
          description: The bookings matching the query
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
          content:
            application/json:
              schema:
                type: array
                description: Notifications related to this booking. Later versions of this API will define the types and use more extensively. For now, this is a catch-all for any messages the TO or MP need to send to each other that does not have its own API call.
                items:
                  $ref: "#/components/schemas/notification"
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "404":
          $ref: "#/components/responses/404NotFound"
        "410":
          $ref: "#/components/responses/410Gone"
    post:
      description: notification between MaaS provider and Transport operator in case of user no-show or if specific asset is not available or some other event occurs not covered by other API calls.
      tags:
        - general
        - TO
        - MP
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/notification"
      responses:
        "204":
          $ref: "#/components/responses/204NoContent"
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "404":
          $ref: "#/components/responses/404NotFound"
        "410":
          $ref: "#/components/responses/410Gone"

  /legs/{id}/available-assets:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
      - name: id
        in: path
        description: Leg identifier
        required: true
        schema:
          type: string
    get:
      description: Returns a list of available assets for the given leg. These assets can be used to POST to /legs/{id}/asset if no specific asset is assigned by the TO. If picking an asset is not allowed for this booking, or one already has been, 403 should be returned. If the booking is unknown, 404 should be returned. See (4.7) in the process flow. - trip execution
      tags:
        - trip execution
        - TO
      responses:
        "200":
          description: Available assets for the leg. If no suitable assets are found an empty array is to be returned.
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/asset"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "403":
          $ref: "#/components/responses/403Forbidden"
        "404":
          $ref: "#/components/responses/404NotFound"

  /legs/{id}:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
      - name: id
        in: path
        description: Leg identifier
        required: true
        schema:
          type: string
    get:
      description: Retrieves the latest summary of the leg, being the execution of a portion of a journey travelled using one asset (vehicle). Every leg belongs to one booking, every booking has at least one leg. Where the booking describes the agreement between user/MP and TO, the leg describes the journey as it occured. See (4.3) in the flow chart - trip execution
      tags:
        - trip execution
        - TO
        - MP
      responses:
        "200":
          description: operation successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/leg"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "404":
          $ref: "#/components/responses/404NotFound"
    put:
      description: Updates the leg with new information. Only used for updates about execution to the MP. To request changes as the MP, the booking should be updated and the TO can accept the change and update the leg in turn.
      tags:
        - trip execution
        - MP
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/leg"
        description: changed leg (e.g. with different duration or destination)
        required: true
      responses:
        "204":
          $ref: "#/components/responses/204NoContent"
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "404":
          $ref: "#/components/responses/404NotFound"

  /legs/{id}/events:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
      - name: id
        in: path
        description: Leg identifier
        required: true
        schema:
          type: string
    post:
      description: This endpoint must be used to alter the state of a leg.<br>
        Operations:<br> `PREPARE` the TO can send a message telling the MP that he is preparing the booked leg [To be implemented by the MP] (see (7.2) in the process flow - trip execution),<br>
        `ASSIGN_ASSET` can assign an asset to a leg. Can be to assign an asset in case there is still an asset type assigned [Optionally implementable by the MP]. See (4.7) in the process flow - trip execution<br>
        `RESERVE` will claim an asset ahead in time [Optionally implementable by the TO],<br>
        `SET_IN_USE` will activate the leg or resume the leg [TO and MP] (see (4.6) in process flow),<br>
        `PAUSE` will pause the leg [TO and MP] (see (4.6) in process flow),<br>
        `START_FINISHING` will start the end-of-leg [Optionally implementable by TO and MP],<br>
        `FINISH` will end this leg (see (4.6) in process flow) [TO and MP]
      tags:
        - trip execution
        - MP
        - TO
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/legEvent"
      responses:
        "200":
          description: operation successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/leg"
        "204":
          $ref: "#/components/responses/204NoContent"
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "404":
          $ref: "#/components/responses/404NotFound"

  /legs/{id}/progress:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
      - name: id
        in: path
        description: Leg identifier
        required: true
        schema:
          type: string
    get:
      description: Monitors the current location of the asset and duration & distance of the leg (see (4.7) in process flow)
      tags:
        - trip execution
        - TO
      parameters:
        - name: location-only
          in: query
          description: Specifies if only the location should be returned
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: operation successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/legProgress"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "404":
          $ref: "#/components/responses/404NotFound"
    post:
      description: Monitors the current location of the asset and duration & distance of the leg
      tags:
        - trip execution
        - MP
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/legProgress"
      responses:
        "204":
          $ref: "#/components/responses/204NoContent"
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "404":
          $ref: "#/components/responses/404NotFound"

  /operator/meta:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
    get:
      tags:
        - operator information
        - TO
        - MP
      summary: describes the running implementations
      description: all versions that are implemented on this url, are described in the result of this endpoint. In contains all versions and per version the endpoints, their status
        and the supported scenarios.
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/endpointImplementation"
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true

  /operator/stations:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
    get:
      tags:
        - operator information
        - TO
      summary: describes all available stations
      description: All stations contained in this list are considered public (ie, can be shown on a map for public use). If there are private stations (such as Capital Bikeshare's White House station) these should not be exposed here and their status should not be included [from GBFS]
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/stationInformation"
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"

  /operator/available-assets:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
    get:
      description: Returns a list of available assets.
      tags:
        - operator information
        - TO
      responses:
        "200":
          description: Available assets or asset-types. In case assets are replied, the realtime location is also available.
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/assetType"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "403":
          $ref: "#/components/responses/403Forbidden"
        "404":
          $ref: "#/components/responses/404NotFound"

  /operator/alerts:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
    get:
      tags:
        - operator information
        - TO
      summary: informs customers about changes to the system outside of normal operations
      description: This feed is intended to inform customers about changes to the system that do not fall within the normal system operations. For example, system closures due to weather would be listed here, but a system that only operated for part of the year would have that schedule listed in the system-calendar.json feed. This file is an array of alert objects defined as below. Obsolete alerts should be removed so the client application can safely present to the end user everything present in the feed. The consumer could use the start/end information to determine if this is a past, ongoing or future alert and adjust the presentation accordingly. [from GBFS]
      responses:
        "200":
          description: returns currently active system alerts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/systemAlert"
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"

  /operator/operating-calendar:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
    get:
      tags:
        - operator information
        - TO
      summary: describes the operating calendar for a system. An array of year objects defined as follows (if start/end year are omitted, then assume the start and end months do not change from year to year). [from GFBS]
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/systemCalendar"
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"

  /operator/operating-hours:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
    get:
      tags:
        - operator information
        - TO
      summary: describes the system hours of operation
      description: Describes the hours of operation of all available systems of the transport operator [from GBFS]
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/systemHours"
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"

  /operator/information:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
    get:
      tags:
        - operator information
        - TO
      summary: describes the system
      description: Describes the system including System operator, System location, year implemented, URLs, contact info, time zone. [from GBFS]
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/systemInformation"
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"

  /operator/pricing-plans:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
    get:
      tags:
        - operator information
        - TO
      summary: gives pricing information
      description: Describes pricing of systems or assets [from GBFS]

      responses:
        "200":
          description: returns standard pricing plans for an operator
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/systemPricingPlan"
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"

  /operator/regions:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
    get:
      tags:
        - operator information
        - TO
      summary: describes regions for a system that is broken up by geographic or political region. It is defined as a separate feed to allow for additional region metadata (such as shape definitions). [from GBFS]
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/systemRegion"
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"

  /payment/journal-entry:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
    get:
      tags:
        - payment
        - MP
        - TO
      description: Returns all the journal entries that should be paid per leg
      parameters:
        - name: from
          in: query
          description: start of the selection
          required: true
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          description: end of the selection
          required: true
          schema:
            type: string
            format: date-time
        - name: state
          in: query
          required: true
          schema:
            $ref: "#/components/schemas/journalState"
        - name: category
          in: query
          description: type of booking line (e.g. fare, addition costs, fines, ...)
          required: true
          schema:
            type: string
            enum:
              [
                ALL,
                DAMAGE,
                LOSS,
                STOLEN,
                EXTRA_USAGE,
                REFUND,
                FINE,
                OTHER_ASSET_USED,
                CREDIT,
                VOUCHER,
                DEPOSIT,
                OTHER,
              ]

      responses:
        "200":
          description: journal entries
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/journalEntry"
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"

  /payment/{id}/claim-extra-costs:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
    patch:
      tags:
        - payment
        - MP
      description: extra costs that the TO has to charge to the MP or vice versa.
      parameters:
        - name: id
          in: path
          description: Booking identifier
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/extraCosts"

      responses:
        "200":
          description: journal entry received, will be processed (state = INVOICED)
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/journalEntry"
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"

  /support/:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
    post:
      description: creates a request for support from end user via MP
      tags:
        - support
        - TO
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/supportRequest"
      responses:
        "200":
          description: support request acknowledged
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/supportStatus"
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "404":
          $ref: "#/components/responses/404NotFound"

  /support/{id}/status:
    parameters:
      - $ref: "#/components/parameters/acceptLanguage"
      - $ref: "#/components/parameters/api"
      - $ref: "#/components/parameters/apiVersion"
    get:
      description: Gets the status report of the support request. Last status (highest order number) is the current status
      tags:
        - support
        - TO
      parameters:
        - name: id
          in: path
          description: Booking identifier
          required: true
          schema:
            type: string
      responses:
        "200":
          description: support status delivered
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/supportStatus"
          headers:
            Content-Language:
              description: The language/localization of user-facing content
              example: nl
              schema:
                type: string
                format: One IETF BCP 47 (RFC 5646) language tag
              required: true
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "404":
          $ref: "#/components/responses/404NotFound"

components:
  schemas:
    address:
      type: object
      properties:
        streetAddress:
          description: street address, including number OR PO box number, eventually extended with internal referencce like room number, could match Content-Language
          type: string
          example: example street 18, 2nd floor, 18-B33
        areaReference:
          description: city or town, principal subdivision such as province, state or county, could match Content-Language
          type: string
          example: Smallcity, Pinetree county
        postalCode:
          type: string
        country:
          $ref: "#/components/schemas/country"

    amountOfMoney:
      type: object
      properties:
        amount:
          description: This should be in the base unit as defined by the ISO 4217 currency code with the appropriate number of decimal places and omitting the currency symbol. e.g. if the price is in US Dollars the price would be 9.95. This is inclusive VAT
          type: number
          example: 9.95
        amountExVat:
          type: number
          example: 8.95
        currencyCode:
          description: ISO 4217 currency code
          type: string
          minLength: 3
          maxLength: 3
        vatRate:
          type: number
          description: value added tax rate (percentage of amount)
          example: 21.0
        vatCountryCode:
          $ref: "#/components/schemas/country"

    asset:
      type: object
      required:
        - id
        - properties
      properties:
        id:
          type: string
          description: Unique identifier of an asset
        isReserved:
          type: boolean
          description: true indicates the bike is currently reserved for someone else
        isReservedFrom:
          description: optional addition to determine if an asset is reserved in the future
          type: string
          format: date-time
        isReservedTo:
          description: optional addition to determine when asset is available in the future
          type: string
          format: date-time
        isDisabled:
          type: boolean
          description: true indicates the asset is currently disabled (broken)
        properties:
          $ref: "#/components/schemas/assetProperties"

    assetClass:
      type: string
      description: the class of asset. It's possible to specify it more in the assetSubType in assetType. These classes are taken from the NeTeX standard, but ALL and UNKNOWN are removed. On the other hand OTHER and PARKING are added.
      enum:
        [
          AIR,
          BUS,
          TROLLEYBUS,
          TRAM,
          COACH,
          RAIL,
          INTERCITYRAIL,
          URBANRAIL,
          METRO,
          WATER,
          CABLEWAY,
          FUNICULAR,
          TAXI,
          SELFDRIVE,
          FOOT,
          BICYCLE,
          MOTORCYCLE,
          CAR,
          SHUTTLE,
          OTHER,
          PARKING,
          MOPED,
          STEP,
        ]

    assetType:
      type: object
      required:
        - id
        - amountAvailable
        - assets
        - assetClass
        - sharedProperties
      properties:
        id:
          type: string
          description: Unique identifier of an asset type, 
        nrAvailable:
          type: integer
        assets:
          type: array
          items:
            $ref: "#/components/schemas/asset"
        assetClass:
          $ref: "#/components/schemas/assetClass"
        assetSubClass:
          type: string
          description: a more precise classification of the asset, like 'cargo bike', 'public bus', 'coach bus', 'office bus', 'water taxi',  'segway'. This is mandatory when using 'OTHER' as class.
        sharedProperties:
          $ref: "#/components/schemas/assetProperties"
              
    assetProperties:
      description: what kind of asset is this? Classify it, give the aspects. Most aspects are optional and should be used when applicable.
      properties:
        name:
          description: name of asset (type), required in either assetType or asset, should match Content-Language
          type: string
        location:
          $ref: "#/components/schemas/place"
        fuel:
          type: string
          enum:
            [
              NONE,
              GASOLINE,
              DIESEL,
              ELECTRIC,
              HYBRID_GASOLINE,
              HYBRID_DIESEL,
              HYBRID_GAS,
              HYDROGEN,
              GAS,
              BIO_MASS,
              KEROSINE,
              OTHER,
            ]
        energyLabel:
          description: Energy efficiency
          type: string
          enum: [A, B, C, D, E]
        co2PerKm:
          type: number
        brand:
          type: string
          description: brand of the asset
        model:
          type: string
        buildingYear:
          type: integer
        travelAbroad:
          type: boolean
          description: true indicates asset is allowed to travel abroad
        airConditioning:
          type: boolean
          description: true indicates airconditioning required
        cabrio:
          type: boolean
          description: true indicates cabrio required
        colour:
          type: string
          description: colour of the asset, should match Content-Language
        cargo:
          type: string
          description: describes options to carry cargo, should match Content-Language
        easyAccessibility:
          type: string
          description: describes if asset is or needs to be easily accessible
          enum:
            [
              LIFT,
              ESCALATOR,
              GROUND_LEVEL,
              SIGHTIMPAIRMENT,
              HEARINGIMPAIRMENT,
              WHEELCHAIR,
            ]
        gears:
          type: integer
          description: number of gears of the asset
        gearbox:
          type: string
          description: type of gearbox
          enum: 
            [
              MANUAL, 
              AUTOMATIC, 
              SEMIAUTOMATIC
            ]
        image:
          description: Link to an image of the asset
          type: string
          format: URL
          example: "https://files.fietsersbond.nl/app/uploads/2014/10/30151126/ST2_Men_Side_CityKit-Stromer.jpg"
        rentalUrl:
          type: string
          description: deep-linking option from GBFS+
          format: URL
          example: https://www.rentmyfreebike.com/rental
        infantSeat:
          type: boolean
          description: true indicates infant seat required
        persons:
          type: integer
          description: number of persons able to use the asset
          minimum: 1
        pets:
          type: boolean
          description: true indicates pets are allowed on asset
        propulsion:
          type: string
          description: way in which the asset is powered
          enum: 
            [
              MUSCLE, 
              ELECTRIC, 
              GASOLINE, 
              DIESEL, 
              HYBRID, 
              LPG, 
              HYDROGEN
            ]
        smoking:
          type: boolean
          description: true indicates smoking is allowed on asset
        stateOfCharge:
          type: integer
          minimum: 0
          maximum: 100
          description: percentage of charge available
        towingHook:
          type: boolean
          description: true indicates towing hook required
        undergroundParking:
          type: boolean
          description: true indicates underground parking is allowed with asset
        winterTires:
          type: boolean
          description: true indicates winter tires required
        other:
          type: string
          description: free text to describe asset, should match Content-Language
        meta:
          description: this object can contain extra information about the type of asset. For instance values from the 'Woordenboek Reizigerskenmerken'. [https://github.com/efel85/TOMP-API/issues/17]. These values can also be used in the planning.
          type: object
          additionalProperties: true

    bankAccount:
      type: object
      properties:
        name:
          description: account name
          type: string
        number:
          description: account number
          type: string
        country:
          $ref: "#/components/schemas/country"
        bankIdentification:
          description: bank identification, like BIC code
          type: string

    booking:
      description: The booking information describing the state and details of an agreed upon trip
      type: object
      allOf:
        - $ref: "#/components/schemas/bookingRequest"
        - type: object
          required:
            - legs
          properties:
            state:
              $ref: "#/components/schemas/bookingState"
            legs:
              description: The legs of this booking, generally just one for simple legs, in order of how they will be travelled
              type: array
              items:
                $ref: "#/components/schemas/leg"
            pricing:
              description: The pricing information of the overall booking, in addition to any leg pricing, if not all legs have pricing the booking should have the fare
              $ref: "#/components/schemas/fare"
            extraData:
              description: Arbitrary information that a TO can add
              type: object
              additionalProperties: true

    bookingOperation:
      type: object
      description: operation on the bookingOption
      required:
        - operation
      properties:
        operation:
          type: string
          enum: [CANCEL, EXPIRE, DENY, COMMIT]

    bookingRequest:
      description: A booking requested by the MP
      type: object
      allOf:
        - $ref: "#/components/schemas/planningRequest"
        - type: object
          properties:
            id:
              description: A unique identifier for the TO to know this booking by, required from the point on where booking-intent is true
              type: string
            customer:
              description: The user that wants to make this booking under their name, should contain all the information required in a conditionRequireBookingData
              $ref: "#/components/schemas/customer"

    bookingState:
      description: The life-cycle state of the booking (from NEW to FINISHED)
      type: string
      enum:
        [
          NEW,
          PENDING,
          RELEASED,
          EXPIRED,
          CONDITIONAL_CONFIRMED,
          CONFIRMED,
          CANCELLED,
          STARTED,
          FINISHED,
        ]
      example: CONFIRMED

    card:
      description: Any kind of card that isn't a license, only provide the cards that are required
      allOf:
        - $ref: "#/components/schemas/cardType"
        - type: object
          required:
            - cardNumber
            - validUntil
          properties:
            cardDescription:
              description: description of the card
              type: string
            cardNumber:
              description: number of the card, like ID number, credit card or bank account number
              type: string
            cardAdditionalNumber:
              description: additional number, like CVC code or IBAN code
              type: string
            validUntil:
              type: string
              format: date
            country:
              $ref: "#/components/schemas/country"
    
    cardType:
      description: A generic description of a card, asset class and acceptors is only allowed for DISCOUNT/TRAVEL/OTHER cards
      type: object
      required:
        - type
      properties:
        type:
          description: The broad category of card
          type: string
          enum: 
            [
              ID, 
              DISCOUNT, 
              TRAVEL, 
              BANK, 
              CREDIT, 
              PASSPORT, 
              OTHER
            ]
        subType:
          description: For use in case of OTHER. Can be used in bilateral agreements.
          type: string
        assetClass:
          $ref: "#/components/schemas/assetClass"
        acceptors:
          description: references to accepting parties, only if applicable
          type: array
          items:
            type: string
            format: maas-id

    condition:
      oneOf:
        - $ref: "#/components/schemas/conditionDeposit"
        - $ref: "#/components/schemas/conditionPayWhenFinished"
        - $ref: "#/components/schemas/conditionPostponedCommit"
        - $ref: "#/components/schemas/conditionRequireBookingData"
        - $ref: "#/components/schemas/conditionReturnArea"
        - $ref: "#/components/schemas/conditionUpfrontPayment"
      discriminator:
        propertyName: conditionType
      required:
        - conditionType
      properties:
        conditionType:
          description: The specific subclass of condition, should match the schema name exactly
          type: string
        id:
          description: An identifier for this condition that can be used to refer to this condition
          type: string
          example: deposit50eu

    conditionDeposit:
      description: in case the TO demands a deposit before usage. Requesting and refunding should be done using the /payment/claim-extra-costs endpoint.
      allOf:
        - $ref: "#/components/schemas/condition"
        - $ref: "#/components/schemas/amountOfMoney"

    conditionPayWhenFinished:
      description: in case the TO demands a direct payment after usage.
      allOf:
        - $ref: "#/components/schemas/condition"

    conditionPostponedCommit:
      allOf:
        - $ref: "#/components/schemas/condition"
        - type: object
          required:
            - ultimateResponseTime
          properties:
            ultimateResponseTime:
              type: string
              format: date-time

    conditionRequireBookingData:
      type: object
      allOf:
        - $ref: "#/components/schemas/condition"
        - type: object
          required:
            - requiredFields
          properties:
            requiredFields:
              type: array
              items:
                type: string
                enum:
                  [
                    FROM_ADDRESS,
                    TO_ADDRESS,
                    BIRTHDATE,
                    EMAIL,
                    PERSONAL_ADDRESS,
                    PHONE_NUMBERS,
                    LICENSES,
                    BANK_CARDS,
                    DISCOUNT_CARDS,
                    TRAVEL_CARDS,
                    ID_CARDS,
                    CREDIT_CARDS,
                    NAME,
                    AGE,
                  ]

    conditionReturnArea:
      description: a return area. In the condition list there can be multiple return area's.
      allOf:
        - $ref: "#/components/schemas/condition"
        - type: object
          properties:
            stationId:
              description: station to which the asset should be returned
              type: string
            returnArea:
              description: area in which the asset should be returned as GeoJSON Polygon coordinates
              $ref: "#/components/schemas/geojsonPolygon"
            coordinates:
              $ref: "#/components/schemas/coordinates"
            returnHours:
              description: the return hours of the facility (if different from operating-hours)
              type: array
              items:
                $ref: "#/components/schemas/systemHours"

    conditionUpfrontPayment:
      description: in case the TO demands a upfront payment before usage. The payment should be made in the booking phase.
      allOf:
        - $ref: "#/components/schemas/condition"

    coordinates:
      type: object
      description: a lon, lat (WGS84, EPSG:4326)
      required:
        - lat
        - lng
      properties:
        lng:
          type: number
          example: 6.169639
        lat:
          type: number
          example: 52.253279

    country:
      type: string
      description: two-letter country codes according to ISO 3166-1
      maxLength: 2
      minLength: 2
      example: NL

    customer:
      description: A MaaS user that wishes to make a booking, only use the fields required by booking conditions
      allOf:
        - $ref: "#/components/schemas/traveler"
        - type: object
          required:
            - id
          properties:
            id:
              description: The identifier MaaS uses to identify the customer
              type: string
              example: "A0-123456"
            initials:
              type: string
            firstName:
              description: First name of the customer
              type: string
              example: John
            lastName:
              description: Last name of the customer
              type: string
              example: Doe
            middleName:
              description: Middle name of the customer
              type: string
              example: von
            prefix:
              description: prefix of the customer, like titles
              type: string
            postfix:
              description: postfix of the customer, like titles
              type: string
            phones:
              type: array
              items:
                $ref: "#/components/schemas/phone"
            email:
              description: the email address of the customer
              type: string
            birthDate:
              type: string
              format: date
            address:
              $ref: "#/components/schemas/address"
            photo:
              description: base64 encoded
              type: string
              format: byte
            cards:
              type: array
              items:
                $ref: "#/components/schemas/card"
            licenses:
              type: array
              items:
                $ref: "#/components/schemas/license"

    day:
      type: string
      enum: [MON, TUE, WED, THU, FRI, SAT, SUN]

    distance:
      description: The estimated distance travelled in the leg (in meters)
      type: integer
      minimum: 0
      example: 7250

    duration:
      description: A duration of some time (relative to a time) in milliseconds
      type: integer
      maximum: 2147483647
      minimum: 0
      example: 11112

    endpoint:
      type: object
      description: a formal description of an endpoint.
      required:
        - method
        - path
        - status
      properties:
        method: 
          type: string
          enum: [
            POST, 
            PUT, 
            GET, 
            DELETE, 
            PATCH
          ]
        path:
          description: the exact path of the endpoint, starting after the base URL
          type: string
          example: /planning-options/
        eventType:
          description: in case the path is ending in /events, the event type/operator enum should be added here.
          type: string
          enum: [
            PREPARE, 
            ASSIGN_ASSET, 
            SET_IN_USE, 
            PAUSE, 
            START_FINISHING, 
            FINISH, 
            ISSUE, 
            CANCEL, 
            EXPIRE, 
            DENY, 
            COMMIT
          ]
        status:
          type: string
          enum: [
            NOT_IMPLEMENTED, 
            DIALECT, 
            IMPLEMENTED
          ]
      example:
        { "method": "POST", "path": "/booking/{id}/events", "eventType": "COMMIT", "status": "IMPLEMENTED" }

    endpointImplementation:
      type: object
      description: a complete endpoint description, containing all endpoints, their status, but also the served scenarios and implemented process flows. The identifiers for the process flows can be found at https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers
      required:
        - version
        - baseUrl
        - endpoints
        - scenarios
        - processIdentifiers
      properties:
        version:
          type: string
        baseUrl:
          type: string
        endpoints:
          type: array
          items:
            $ref: "#/components/schemas/endpoint"
        scenarios:
          type: array
          items:
            $ref: "#/components/schemas/scenario"
        processIdentifiers:
          $ref: "#/components/schemas/processIdentifiers"
      example:
        { "version": "0.5.0", "baseUrl": "https://dummy-bikes.org/", "endpoints": [], "scenarios": ["POSTPONED_COMMIT"], "processIdentifiers": { "planning": ["LOCATION_BASED"] }, "booking": ["ACCESS_CODE_QR", "ACCESS_CODE_IN_COMMIT_EVENT"] }
      
    error:
      type: object
      description:
        An error that the service may send, e.g. in case of invalid input,
        missing authorization or internal service error. See https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP for further explanation of error code.
      properties:
        errorcode:
          type: number
          description: The TOMP specific error code. See https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP for more details of this error.
        type:
          type: string
          description: The category of this type of error.
        title:
          type: string
          description: A short, human-readable summary of the problem type.  It SHOULD NOT change from occurrence to occurrence of the problem, except to match Content-Language
        status:
          type: integer
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem, could match Content-Language
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.

    extraCosts:
      description: Costs that the TO is charging the MP; credits are negative
      allOf:
        - $ref: "#/components/schemas/amountOfMoney"
        - type: object
          required:
            - reason
            - description
            - amount
          properties:
            category:
              $ref: "#/components/schemas/journalCategory"
            description:
              description: free text to describe the extra costs. Mandatory in case of 'OTHER', should match Content-Language
              type: string
            number:
              type: number
              description: e.g. number of litres, number of kilowatthour, etc
            numberType:
              type: string
              enum: [LITER, KILOWATTHOUR, CO2_COMPENSATION, OTHER]
            account:
              $ref: "#/components/schemas/bankAccount"
            meta:
              description: Arbitrary metadata that a TO can add, like voucher codes
              type: object
              additionalProperties: true

    fare:
      description: the total fare is the sum of all parts, except for the 'MAX' farePart. This one descripes the maximum price for the complete leg.
      required:
        - estimated
        - parts
      properties:
        estimated:
          description: is this fare an estimation?
          type: boolean
        description:
          description: user friendly description of the fare (e.g. 'full fare'), should match Content-Language
          type: string
        class:
          description: in the future we'll set up an enumeration of possible "fare classes". For now it's free format.
          type: string
        parts:
          type: array
          items:
            $ref: "#/components/schemas/farePart"

    farePart:
      description: this describes a part of the fare (or discount). It contains a for instance the startup costs (fixed) or the flex part (e.g. 1.25 EUR per 2.0 MILES). The amount is tax included. In case of discounts, the values are negative. With 'MAX' you can specify e.g. a maximum of 15 euro per day. Percentage is mainly added for discounts. The `scale` properties create the ability to communicate scales (e.g. the first 4 kilometers you've to pay EUR 0.35 per kilometer, the kilometers 4 until 8 EUR 0.50 and above it EUR 0.80 per kilometer).
      example:
        {
          "amount": 9.96,
          "currencyCode": "EUR",
          "taxRate": 21.0,
          "type": "FLEX",
          "unitType": "HOUR",
          "units": 1,
        }
      allOf:
        - $ref: "#/components/schemas/amountOfMoney"
        - type: object
          required:
            - vatRate
            - unitType
            - amount
          properties:
            type:
              description: type of fare part
              type: string
              enum: [FIXED, FLEX, MAX]
            unitType:
              type: string
              description: in case of 'FLEX' mandatory. E.g. 0.5 EUR per HOUR
              enum: [KM, SECOND, MINUTE, HOUR, MILE, PERCENTAGE]
            units:
              type: number
              description: the number of km, seconds etc in the `per` part. In the first example of the description this should be 2.0
            scaleFrom:
              type: number
            scaleTo:
              type: number
            scaleType:
              type: string
              enum: [KM, MILE, HOUR, MINUTE]
            name:
              type: string
            class:
              type: string
            meta:
              type: object
              additionalProperties: true

    geojsonLine:
      description: An array  of WGS84 coordinate pairs 
      type: array
      example: [[6.169639, 52.253279], [6.05623, 52.63473]]
      items:
        $ref: "#/components/schemas/geojsonPoint"

    geojsonPoint:
      description: Geojson Coordinate 
      type: array
      minItems: 2
      maxItems: 2
      items:
        type: number
      example: [lon, lat]

    geojsonPolygon:
      description: geojson representation of a polygon. First and last point must be equal. See also https://geojson.org/geojson-spec.html#polygon and example https://geojson.org/geojson-spec.html#id4
      type: array
      items:
        $ref: "#/components/schemas/geojsonLine"
      example: [[[lon1, lat1], [lon2,lat2], [lon3,lat3], [lon1,lat1]]]

    journalEntry:
      allOf:
        - $ref: "#/components/schemas/amountOfMoney"
        - type: object
          properties:
            journalId:
              description: id of the entry, leg id can be reused
              type: string
            journalSequenceId:
              description: sequence id of the entry, in combination with journalId unique from TO perspective.
              type: string
            invoiceId:
              description: the number of the invoice. Should be filled in when invoiced.
            invoiceDate:
              type: string
              format: date-time
            state:
              $ref: "#/components/schemas/journalState"
            expirationDate:
              type: string
              format: date-time
            comment:
              type: string
            distance:
              description: the travelled distance. Only if applicable.
              type: number
            distanceType:
              type: string
              enum: [KM, MILE]
            usedTime:
              description: the time in seconds that the assed is used. Only if applicable.
              type: number
            bankAccount:
              $ref: "#/components/schemas/bankAccount"
            details:
              description: the specification of the amount; how is it composed.
              oneOf:
                - $ref: "#/components/schemas/fare"
                - $ref: "#/components/schemas/extraCosts"

    journalState:
      type: string
      enum: [TO_INVOICE, INVOICED]

    journalCategory:
      type: string
      enum:
        [
          ALL,
          DAMAGE,
          LOSS,
          STOLEN,
          EXTRA_USAGE,
          REFUND,
          FINE,
          OTHER_ASSET_USED,
          CREDIT,
          VOUCHER,
          DEPOSIT,
          OTHER,
        ]

    leg:
      description: A planned (segment of) a booked trip using one asset type
      type: object
      required:
        - from
        - assetType
      properties:
        id:
          description: The unique identifier (TO) of this leg
          type: string
        from:
          description: The departure location of this leg, using this asset type
          $ref: "#/components/schemas/place"
        to:
          description: The destination of this leg, using this asset type
          $ref: "#/components/schemas/place"
        departureTime:
          description: The departure time of this leg
          type: string
          format: date-time
        arrivalTime:
          description: The intended arrival time at the to place
          type: string
          format: date-time
        assetType:
          description: The asset type used in this leg as determined during booking
          $ref: "#/components/schemas/assetType"
        asset:
          description: The concrete asset used for the execution of the leg
          $ref: "#/components/schemas/asset"
        pricing:
          description: The leg-specific pricing information, all fares are additive, if the booking does not have pricing set all legs should
          $ref: "#/components/schemas/fare"
        suboperator:
          $ref: "#/components/schemas/suboperator"
        conditions:
              description: The conditions that apply to this leg, there may be more conditions in a parent booking and planning object (if this is returned as part of those)
              type: array
              items:
                $ref: "#/components/schemas/condition"
        state:
          $ref: "#/components/schemas/legState"
        departureDelay:
          $ref: "#/components/schemas/duration"
        arrivalDelay:
          $ref: "#/components/schemas/duration"
        distance:
          $ref: "#/components/schemas/distance"
        progressGeometry:
          description: A list of coordinates describing the progress so far along the leg, as GeoJSON LineString coordinates
          $ref: "#/components/schemas/geojsonLine"
        ticket:
          description: The MaaS user's proof of their right to travel on this leg
          $ref: "#/components/schemas/token"
        assetAccessData:
          description: Data to open a specific asset (e.g. QR code, image base64)
          $ref: "#/components/schemas/token"

    legEvent:
      type: object
      description: event for the execution
      required:
        - time
        - event
      properties:
        time:
          type: string
          format: date-time
        event:
          type: string
          enum:
            [
              PREPARE,
              ASSIGN_ASSET,
              SET_IN_USE,
              PAUSE,
              START_FINISHING,
              FINISH,
              ISSUE,
            ]
        comment:
          type: string
          description: free text, should match Content-Language
        asset:
          $ref: "#/components/schemas/asset"

    legProgress:
      type: object
      description: provides current asset location & duration and distance of the current leg
      required:
        - coordinates
      properties:
        coordinates:
          $ref: "#/components/schemas/coordinates"
        duration:
          $ref: "#/components/schemas/duration"
        distance:
          $ref: "#/components/schemas/distance"

    legState:
      type: string
      description: status of a leg
      enum:
        [
          NOT_STARTED,
          PREPARING,
          IN_USE,
          PAUSED,
          FINISHING,
          FINISHED,
          ISSUE_REPORTED,
        ]

    license:
      description: driver or usage license for a specific user. Contains the number and the assetType you're allowed to operate (e.g. driver license for CAR)
      allOf:
        - $ref: "#/components/schemas/licenseType"
        - type: object
          properties:
            number:
              type: string
              example: "1287948792"
            licenseCode:
              description: in most countries a driver license has also a code. As TO you can exactly verify, based on this code if the license allows to operate it's assets, if the assetType too generic.
              example: D4
              type: string
            validUntil:
              type: string
              format: date

    licenseType:
      description: A category of license to use a certain asset class
      type: object
      required:
        - assetClass
      properties:
        assetClass:
          $ref: "#/components/schemas/assetClass"
        issuingCountry:
          $ref: "#/components/schemas/country"

    notification:
      type: object
      description: notifies the MaaS operator of issues with a booking [addendum]
      properties:
        type:
          type: string
          enum: [VEHICLE_NOT_AVAILABLE, USER_NO_SHOW, ETA, OTHER]
          example: VEHICLE_NOT_AVAILABLE
        comment:
          type: string
          description: free text, should match Content-Language

    phone:
      type: object
      properties:
        preferred:
          description: only one phone in this array can have a true in this property
          type: boolean
        number:
          description: phone number. In case of international usage, always provide the country code.
          type: string
          pattern: '^[+]*[(]{0,1}[0-9]{1,4}[)]{0,1}[-\s\./0-9]*$'
          example: +31-48934758 or +(0075)-834923384 or 020 1234 1234
        kind:
          type: string
          enum: [LANDLINE, MOBILE]
        type:
          type: string
          enum: [PRIVATE, BUSINESS, OTHER]

    place:
      type: object
      description: a origin or destination of a leg, non 3D. lon/lat in WGS84.
      required:
        - coordinates
      properties:
        name:
          description: Human readable name of the place, could match Content-Language
          type: string
        stopReference:
          type: array
          items:
            $ref: "#/components/schemas/stopReference"
        stationId:
          description: reference to /operator/stations
          type: string
        coordinates:
          $ref: "#/components/schemas/coordinates"
        physicalAddress:
          $ref: "#/components/schemas/address"
        extraInfo:
          type: object
          additionalProperties: true

    planningRequest:
      description: A travel planning for which bookable options are requested
      type: object
      required:
        - from
        - nrOftravelers
      properties:
        from:
          $ref: "#/components/schemas/place"
        radius:
          description: Maximum distance in meters a user wants to travel to reach the travel option
          type: number
        to:
          $ref: "#/components/schemas/place"
        departureTime:
          description: The intended departure time. If left out and no arrivalTime is set, the current time should be assumed.
          type: string
          format: date-time
        arrivalTime:
          description: The intended arrival time, at the to place if set otherwise the time the user intends to stop using the asset.
          type: string
          format: date-time
        nrOfTravelers:
          description: The number of people that intend to travel, including the customer.
          type: integer
          minimum: 1
        travelers:
          description: Extra information about the people that intend to travel if relevant, length must be less than or equal to nrOftravelers.
          type: array
          items:
            $ref: "#/components/schemas/traveler"
        useAssets:
          description: The specific asset(s), the user wishes to receive leg options for
          type: array
          items:
            type: string
            format: an asset id for this operator

    planning:
      description: A travel planning with bookable options that fulfil the constraints of the planning
      type: object
      required:
        - validUntil
        - options
      properties:
        validUntil:
          description: The time until which the presented options are (likely) available
          type: string
          format: date-time
        options:
          type: array
          items:
            $ref: "#/components/schemas/booking"

    processIdentifiers:
      type: object
      required:
        - operatorInformation
        - planning
        - booking
        - tripExecution
        - support
        - payment
        - general
      properties:
        operatorInformation:
          type: array
          items:
            type: string
        planning: 
          type: array
          items:
            type: string
        booking:
          type: array
          items:
            type: string
        tripExecution:
          type: array
          items: 
            type: string
        support:
          type: array
          items: 
            type: string
        payment:
          type: array
          items: 
            type: string
        general:
          type: array
          items: 
            type: string

    requirements:
      description: Requirements the users has ((dis)abilities, share [TRUE|FALSE], preferences [TBD]). See also 'https://github.com/efel85/TOMP-API/blob/master/documents/Woordenboek%20Reizigerskenmerken%20CROW%20Eindversie%208%20mei%202019.pdf' [https://github.com/efel85/TOMP-API/issues/17 and https://github.com/efel85/TOMP-API/issues/27]
      type: object
      additionalProperties: true

    scenario:
      type: string
      enum: [
        POSTPONED_COMMIT, 
        DEPOSIT, 
        PAY_WHEN_FINISHED, 
        REQUIRE_BOOKING_DATA, 
        RETURN_AREA, 
        UPFRONT_PAYMENT
      ]

    stationInformation:
      type: object
      required:
        - stationId
        - name
        - coordinates
      properties:
        stationId:
          type: string
          description: unique identifier of a station
          example: XX:Y:12345678
        name:
          type: string
          description: public name of the station, could match Content-Language
          example: Island Central
        coordinates:
          $ref: "#/components/schemas/coordinates"
        physicalAddress:
          $ref: "#/components/schemas/address"
        crossStreet:
          type: string
          description: Cross street of where the station is located. This field is intended to be a descriptive field for human consumption. In cities, this would be a cross street, but could also be a description of a location in a park, etc, should match Content-Language
          example: on the corner with Secondary Road
        regionId:
          type: string
          description: ID of the region where the station operates (see "systemRegions")
        rentalMethods:
          type: array
          description: Array of enumerables containing the payment methods accepted at this station.
          items:
            type: string
            enum:
              [
                KEY,
                CREDITCARD,
                PAYPASS,
                APPLEPAY,
                ANDROIDPAY,
                TRANSITCARD,
                ACCOUNTNUMBER,
                PHONE,
                OTHER,
              ]
          example: [CREDITCARD, PAYPASS, APPLEPAY]
        rentalUrl:
          type: string
          format: URL
          example: https://www.rentmyfreebike.com

    stopReference:
      type: object
      description: reference to a stop (can be nation specific). This can help to specific pinpoint a (bus) stop. Extra information about the stop is not supplied; you should find it elsewhere.
      required:
        - type
        - id
        - country
      properties:
        type:
          type: string
          description: type of external reference (GTFS, CHB).
          enum:
            [
              GTFS_STOP_ID,
              GTFS_STOP_CODE,
              GTFS_AREA_ID,
              CHB_STOP_PLACE_CODE,
              CHB_QUAY_CODE,
              NS_CODE,
            ]
        id:
          type: string
          description: this field should contain the complete ID. E.g. NL:S:13121110 or BE:S:79640040
        country:
          $ref: "#/components/schemas/country"

    suboperator:
      type: object
      description: The operator of a leg or asset, in case this is not the TO itself but should be shown to the user
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the operator, could match Content-Language
        maasId:
          type: string
          description: the maasId from the operator
        description:
          type: string
          description: short description of the operator, should match Content-Language
        contact:
          type: string
          description: contact information, should match Content-Language

    supportRequest:
      description: request for support
      type: object
      properties:
        id:
          type: string
          description: the booking id
        supportType:
          type: string
          enum: [BROKEN_DOWN, NOT_AT_LOCATION, NOT_CLEAN, NOT_AVAILABLE, UNABLE_TO_OPEN, UNABLE_TO_CLOSE, API_TECHNICAL, API_FUNCTIONAL, ACCIDENT, OTHER]
        location:
          $ref: '#/components/schemas/place'
        time:
          type: string
          format: date-time
        priority:
          description: the priority of the support request. 
          type: string
          enum: [ERROR_CANNOT_CONTINUE, ERROR_CAN_CONTINUE, DISTURBING_ISSUE, QUESTION, OTHER]
        contactInformationEndUser:
          description: contact information of the end user in case of direct response requests, like phone number
          type: string
        comment:
          type: string
        requestedResponseTime:
          type: number
          description: time to respond in minutes.

    supportStatus:
      description: the current status of support
      type: object
      allOf:
        - $ref: '#/components/schemas/supportRequest'
      properties:
        status:
          type: string
          enum: [PROCESSING, UPDATE_REQUESTED, RESOLVED, CANCELLED]
          example: PROCESSING
        timeToResolution:
          type: integer
          description: time in minutes to expected resolution of support request
          example: 9
        order:
          type: integer
          description: the sequence number of status of the support issue
        comment:
          type: string
          description: free text to send to the end user.

    systemAlert:
      type: object
      required:
        - alertId
        - alertType
        - summary
      properties:
        alertId:
          type: string
          description: a unique identifier for this alert
        alertType:
          type: string
          enum: [SYSTEM_CLOSURE, STATION_CLOSURE, STATION_MOVE, OTHER]
        startAndEndTimes:
          description: Array of hashes with the keys "start" and "end" indicating when the alert is in effect (e.g. when the system or station is actually closed, or when it is scheduled to be moved). If this array is omitted then the alert should be displayed as long as it is in the feed.
          type: array
          items:
            type: array
            items:
              type: string
              format: date-time
              minItems: 2
              maxItems: 2
        stationIds:
          type: array
          items:
            type: string
          description: Array of strings - If this is an alert that affects one or more stations, include their ids, otherwise omit this field. If both stationIDs and regionIDs are omitted, assume this alert affects the entire system
          example: stationID0001
        regionId:
          type: array
          items:
            type: string
          description: Array of strings - If this system has regions, and if this alert only affects certain regions, include their ids, otherwise, omit this field. If both stationIDs and regionIDs are omitted, assume this alert affects the entire system
          example: regionID0001
        url:
          type: string
          format: hostname
          description: URL where the customer can learn more information about this alert, if there is one
          example: http://www.rentmyfreebike.com/alerts
        summary:
          type: string
          description: A short summary of this alert to be displayed to the customer, should match Content-Language
          example: station closed
        description:
          type: string
          description: Detailed text description of the alert, should match Content-Language
          example: station closed indefinitely due to vandalism
        lastUpdated:
          type: string
          format: date-time

    systemCalendar:
      type: object
      required:
        - startMonth
        - startDay
        - endMonth
        - endDay
      properties:
        startMonth:
          type: integer
          minimum: 1
          maximum: 12
          description: Starting month for the system operations (1-12)
          example: 1
        startDay:
          type: integer
          minimum: 1
          maximum: 31
          description: Starting day for the system operations (1-31)
          example: 1
        startYear:
          type: integer
          description: Starting year for the system operations
          example: 2019
        endMonth:
          type: integer
          minimum: 1
          maximum: 12
          description: Ending month for the system operations (1-12)
          example: 12
        endDay:
          type: integer
          minimum: 1
          maximum: 31
          description: Ending day for the system operations (1-31)
          example: 31
        endYear:
          type: integer
          description: Ending year for the system operations
          example: 2099

    systemHours:
      type: object
      required:
        - days
        - startTime
        - endTime
      properties:
        userType:
          type: string
          description: This indicates that this set of rental hours applies to either members or non-members only.
          enum: [MEMBER, NON_MEMBERS]
          example: MEMBER
        startTime:
          type: string
          format: HH:MM time
        endTime:
          type: string
          format: HH:MM time
        days:
          type: array
          description: An array of abbreviations (first 3 letters) of English names of the days of the week that this hour object applies to (i.e. ["mon", "tue"]). Each day can only appear once within all of the hours objects in this feed.
          items:
            $ref: "#/components/schemas/day"

    systemInformation:
      required:
        - systemId
        - language
        - name
        - timezone
        - typeOfSystem
      properties:
        systemId:
          description: identifier for this transport system. This should be globally unique (even between different systems)
          type: string
          example: XXTO0001
        language:
          description: The languages supported by this operator for user-facing text. These can be requested using the Accept-Language header and should then be returned in Content-Language
          type: array
          items:
            type: string
            format: One IETF BCP 47 (RFC 5646) language tag
            example: fr-FR
        name:
          description: Full name of the system to be displayed to customers, could match Content-Language
          type: string
          example: FreeBike
        shortName:
          description: Optional abbreviation for a system
          type: string
          example: FB
        operator:
          description:  Name of the operator of the system, could match Content-Language
          type: string
          example: FreeBike
        url:
          description: The URL of the transport operator. The value must be a fully qualified URL that includes http:// or https://, and any special characters in the URL must be correctly escaped.
          type: string
          example: https://www.rentmyfreebike.com
        purchaseUrl:
          description: A fully qualified URL where a customer can purchase a membership or learn more about purchasing memberships
          type: string
          example: https://www.rentmyfreebike.com/purchase
        startDate:
          type: string
          format: date
        phoneNumber:
          description: A single voice telephone number for the specified system. This field is a string value that presents the telephone number as typical for the system's service area. It can and should contain punctuation marks to group the digits of the number.
          type: string
          example: 555-12345
        email:
          description: A single contact email address for customers to address questions about the system
          type: string
          format: email
          example: rent@freebike.com
        timezone:
          description: The time zone where the system is located. Time zone names never contain the space character but may contain an underscore. Please refer to the "TZ" value in https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for a list of valid values
          type: string
          example: IST
        licenseUrl:
          description: A fully qualified URL of a page that defines the license terms for the GBFS data for this system, as well as any other license terms the system would like to define (including the use of corporate trademarks, etc)
          type: string
          example: https://www.rentmyfreebike.com/license
        typeOfSystem:
          description: Describes the type of system
          type: string
          enum: [FREE_FLOATING, STATION_BASED, VIRTUAL_STATION_BASED]
          example: FREE_FLOATING
        conditions:
          description: Added to include possibility to communicatie general rental conditions like minimum age, max. reservation time etc. [amended]
          type: string

    systemPricingPlan:
      type: object
      required:
        - planId
        - name
        - isTaxable
        - description
        - fare
      properties:
        planId:
          type: string
          description: a unique identifier for this plan in the system
          example: freeplan1
        url:
          type: string
          description: a fully qualified URL where the customer can learn more about this particular scheme
          example: https://www.rentmyfreebike.com/freeplan
        name:
          type: string
          description: name of this pricing scheme, could match Content-Language
          example: Free Plan
        fare:
          $ref: "#/components/schemas/fare"
        isTaxable:
          type: boolean
          description: false indicates that no additional tax will be added (either because tax is not charged, or because it is included) true indicates that tax will be added to the base price
        description:
          type: string
          description: Text field describing the particular pricing plan in human readable terms. This should include the duration, price, conditions, etc. that the publisher would like users to see. This is intended to be a human-readable description and should not be used for automatic calculations, should match Content-Language
          example: Unlimited plan for free bikes, as long as you don't break them!

    systemRegion:
      type: object
      required:
        - regionId
        - name
      properties:
        regionId:
          type: string
          description: Unique identifier for this region
          example: BikeRegion
        name:
          type: string
          description: Public name for this region, could match Content-Language
          example: BikeTown
        serviceArea:
          description: The area served by the region (i.e. where one may travel using the service's assets) as GeoJSON Polygon coordinates
          $ref: "#/components/schemas/geojsonPolygon"

    token:
      description: The validity token (such as booking ID, travel ticket etc.) that MaaS clients will display to show their right to travel, or use to access an asset
      type: object
      required:
        - validFrom
        - validUntil
        - tokenType
        - tokenData
      properties:
        validFrom:
          type: string
          format: date-time
        validUntil:
          type: string
          format: date-time
        tokenType:
          description: The type of data held in this token, will later be an enum
          type: string
          example: QR-code
        tokenData:
          description: Arbitrary data the TO may pass along the ticket to the client (e.g. a booking code, base64 encoded binary, QR code), later will be one of several types
          type: object
          additionalProperties: true

    traveler:
      description: A generic description of a traveler, not including any identifying information
      type: object
      properties:
        isValidated:
          description: Whether this traveler's identity and properties have been verified by the MaaS provider
          type: boolean
        age:
          description: Age of the traveler, may be approximate
          type: integer
        cardTypes:
          description: The kind of cards this traveler possesses
          type: array
          items:
            $ref: "#/components/schemas/cardType"
        licenseTypes:
          description: The kind of licenses this traveler possesses
          type: array
          items:
            $ref: "#/components/schemas/licenseType"
        requirements:
          $ref: "#/components/schemas/requirements"

  parameters:
    acceptLanguage:
      in: header
      name: Accept-Language
      required: true
      schema:
        type: string
        format: A comma-separated list of BCP 47 (RFC 5646) language tags and optional weights as described in IETF RFC7231 section 5.3.5
      description: A list of the languages/localizations the user would like to see the results in. For user privacy and ease of use on the TO side, this list should be kept as short as possible, ideally just one language tag from the list in operator/information
      example: nl, de;q=0.7
    api:
      in: header
      name: Api
      required: true
      schema:
        type: string
      description: API description, can be TOMP or maybe other (specific/derived) API definitions
      example: TOMP
    apiVersion:
      in: header
      name: Api-Version
      required: true
      schema:
        type: string
      description: Version of the API.
      example: 0.6.0
    maasId:
      in: header
      name: maas-id
      required: true
      schema:
        type: string
      description: The ID of the sending maas operator
      example: 1324A-DFB3482-32ACD
    addressedTo:
      in: header
      name: addressed-to
      required: false
      schema:
        type: string
      description: The ID of the maas operator that has to receive this message
      example: 1324A-DFB3482-32ACD

  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    OAuth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes: {}
    OpenId:
      type: openIdConnect
      openIdConnectUrl: https://unknownserver/.well-known/openid-configuration

  responses:
    202Accepted:
      description: Request was successfully accepted for processing but has not yet completed.
      headers:
        Location:
          schema:
            type: string
          description: The URI where the created or updated resource will eventually be found.
          example: "/bookings/1234"
    204NoContent:
      description: Request was successful, no content to return.
    400BadRequest:
      description: Bad request. See https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP for further explanation of error code.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/error"
    401Unauthorized:
      description: Authorization error (invalid API key) or insufficient access rights given current authorization. See https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP for further explanation of error code.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/error"
    403Forbidden:
      description: The request will not be fulfilled, because the request is not legal in the current state. Authorization will not help. See https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP for further explanation of error code.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/error"
    404NotFound:
      description: The requested resources does not exist or the requester is not authorized to see it or know it exists.
    409Conflict:
      description: The request will not be fulfilled. The request itself is legal, but the content conflicts with the server and might be stale. The user might try again after looking up the current state of the resource.
    410Gone:
      description: The requested resource is no longer available. This is permanent.