TOMP-API-0-DISCOVERY.yaml

openapi: 3.1.0
info:
  title: Transport Operator MaaS Provider API
  description: "<h2>Context</h2>
    <p>This API allows technical communication between Transport Operators (TO) and MaaS providers (MP, and other resellers), to fulfill a complete MaaS user journey<br>
    For more information: <a href='https://github.com/TOMP-WG/TOMP-API/wiki/OpenAPI-entry-page'>TOMP-API wiki</a>, and <a href='https://github.com/TOMP-WG/TOMP-API/wiki/OpenAPI-code-convention'>Coding conventions</a>"
  version: "2.0.0"
  contact:
    name: TOMP working group
    url: https://github.com/TOMP-WG/TOMP-API
  license:
    name: Apache 2.0
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
tags:
- name: discovery
  description: URLS to comply to OGC, to describe the interface

paths:
  /:
    get:
      security:
      - OpenData: []
      tags:
        - discovery
      operationId: landingPage
      summary: "Landing page"
      description: "Gives a (technical & human readable) output describing how this API must be used. If 
        the parameter f=html is supplied, a human readable page must be responded."
      externalDocs:
        url: https://app.swaggerhub.com/apis/OGC/ogcapi-features-1-example-1/1.0.1
      parameters:
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/f"
      responses:
        "200":
          $ref: "#/components/responses/landingPageResponse"
        default:
          $ref: "TOMP-API-1-CORE.yaml#/components/responses/errorResponse"

  /api:
    get:
      description: This document
      parameters:
        - $ref: 'TOMP-API-1-CORE.yaml#/components/parameters/f'
      responses:
        '200':
          description: General Success response.
        default:
          $ref: "TOMP-API-1-CORE.yaml#/components/responses/errorResponse"
      summary: This document
      operationId: openApi
      security:
      - OpenData: []
      tags:
        - discovery

  /conformance:
    get:
      description: >-
        A list of all conformance classes specified in a standard that the
        server conforms to.
      parameters:
        - $ref: 'TOMP-API-1-CORE.yaml#/components/parameters/f'
      operationId: getConformanceDeclaration
      responses:
        '200':
          $ref: '#/components/responses/conformanceDeclarationResponse'
        default:
          $ref: "TOMP-API-1-CORE.yaml#/components/responses/errorResponse"
      summary: API conformance definition
      security:
      - OpenData: []
      tags:
        - discovery

  /collections:
    get:
      security:
      - OpenData: []
      tags:
        - discovery
      summary: the feature collections in the dataset
      description: returns a collection of available collection (like offers, packages, legs, support-requests and payments)
      operationId: getCollections
      responses:
        "200":
          description: A list of available collections
          headers:
            Content-Language:
              $ref: "TOMP-API-1-CORE.yaml#/components/headers/contentLanguage"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/collections"
        default:
          $ref: "TOMP-API-1-CORE.yaml#/components/responses/errorResponse"

  /collections/{collectionId}:
    get:
      security:
      - OpenData: []
      tags:
        - discovery
      summary: describe the feature collection with id `collectionId`
      operationId: describeCollection
      description: a (machine or human) readable description of this collection
      parameters:
        - $ref: "#/components/parameters/collectionId"
      responses:
        "200":
          description: description of data delivered by this collection
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/collection"
            text/html:
              schema:
                type: string
        default:
          $ref: "TOMP-API-1-CORE.yaml#/components/responses/errorResponse"

  /processes:
    get:
      security:
      - OpenData: []
      tags:
      - discovery
      summary: retrieve the list of available processes
      description: The list of processes contains a summary of each process the OGC
        API - Processes offers, including the link to a more detailed description
        of the process. For more information, see <a href="https://docs.ogc.org/is/18-062/18-062.html#sc_process_list">Section 7.9</a>.
      operationId: getProcesses
      responses:
        "200":
          description: Information about the available processes
          headers:
            Version:
              $ref: "TOMP-API-1-CORE.yaml#/components/headers/version"
            Content-Language:
              $ref: "TOMP-API-1-CORE.yaml#/components/headers/contentLanguage"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/processList'
        default:
          $ref: "TOMP-API-1-CORE.yaml#/components/responses/errorResponse"

  /processes/{processID}:
    get:
      security:
      - OpenData: []
      tags:
      - discovery
      summary: retrieve a process description
      description: The process description contains information about inputs and
        outputs and a link to the execution-endpoint for the process. The Core does
        not mandate the use of a specific process description to specify the interface
        of a process. That said, the Core requirements class makes the following
        _recommendation_ implementations SHOULD consider supporting the OGC process
        description. For more information, see <a href="https://docs.ogc.org/is/18-062/18-062.html#sc_process_description">Section 7.10</a>.
      operationId: getProcessDescription
      parameters:
      - name: processID
        in: path
        required: true
        schema:
          type: string
          enum: 
          - search-offers
          - update-traveller
          - update-travel-specification
          - remove-offer
          - assign-asset
          - assign-ancillary
          - purchase-offer
          - release-package
          - purchase-package
          - confirm-purchase
          - rollback-purchase
          - extend-expiry-time
          - start-leg
          - pause-leg
          - resume-leg
          - end-leg
          - postpone-leg
          - extend-leg
          - request-support
          - cancel-package
          - claim-redress-option
          - confirm-redress-option
          - refund-deposit
          - confirm-payment
      responses:
        "200":
          description: A process description.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/process'
        default:
          $ref: 'TOMP-API-1-CORE.yaml#/components/responses/errorResponse'

components:
  parameters:
    collectionId:
      name: collectionId
      in: path
      description: local identifier of a collection
      required: true
      schema:
        type: string
        description: these are all collections exposed when fully implemented
        enum: [packages, offers, assets, ancillaries, support-tickets, payments, refund-options]

  responses:
    landingPageResponse:
      description: The reponse containing a landing page
      headers:
        Version:
          $ref: "TOMP-API-1-CORE.yaml#/components/headers/version"
        Content-Language:
          $ref: "TOMP-API-1-CORE.yaml#/components/headers/contentLanguage"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/landingPage"
        text/html:
          schema:
            type: string

    conformanceDeclarationResponse:
      description: |-
        The URIs of all conformance classes supported by the server.

        To support "generic" clients that want to access multiple
        OGC API Features implementations - and not "just" a specific
        API / server, the server declares the conformance
        classes it implements and conforms to.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/conformance'
        text/html:
          schema:
            type: string

  schemas:
    landingPage:
      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<br>
      additionalProperties: false
      required:
        - title
        - description
        - links
      properties:
        title:
          type: string
        description:
          type: string
        links:
          type: array
          items:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/link"
        processIdentifiers:
          type: array
          description: an array with 'care labels', indiacting how this implementation wants to be treated.
          maxItems: 10
          items:
            $ref: "#/components/schemas/processIdentifier"

    processIdentifier:
      type: object
      required:
        - module
        - identifiers
      properties:
        module:
          type: string
          enum: [offers, pre-sales, purchase, execute, support, after-sales]
        identifiers:
          type: array
          maxItems: 25
          items:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/shortString"

    conformance:
      type: object
      required:
        - conformsTo
      properties:
        conformsTo:
          type: array
          items:
            type: string

    collection:
      type: object
      required:
        - id
        - links
      properties:
        id:
          description: identifier of the collection used, for example, in URIs
          type: string
        title:
          description: human readable title of the collection
          type: string
        description:
          description: a description of the features in the collection
          type: string
        links:
          type: array
          items:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/link"
        extent:
          $ref: "#/components/schemas/extent"
        crs:
          description: the list of coordinate reference systems supported by the service
          type: array
          items:
            type: string
          default:
          - http://www.opengis.net/def/crs/OGC/1.3/CRS84

    extent:
      type: object
      description: |-
        The extent of the features in the collection. In the Core only spatial and temporal
        extents are specified. Extensions may add additional members to represent other
        extents, for example, thermal or pressure ranges.
      properties:
        spatial:
          description: |-
            The spatial extent of the features in the collection.
          type: object
          properties:
            bbox:
              description: |-
                One or more bounding boxes that describe the spatial extent of the dataset.
                In the Core only a single bounding box is supported. Extensions may support
                additional areas. If multiple areas are provided, the union of the bounding
                boxes describes the spatial extent.
              type: array
              minItems: 1
              items:
                description: |-
                  Each bounding box is provided as four or six numbers, depending on
                  whether the coordinate reference system includes a vertical axis
                  (height or depth):

                  * Lower left corner, coordinate axis 1
                  * Lower left corner, coordinate axis 2
                  * Minimum value, coordinate axis 3 (optional)
                  * Upper right corner, coordinate axis 1
                  * Upper right corner, coordinate axis 2
                  * Maximum value, coordinate axis 3 (optional)

                  The coordinate reference system of the values is WGS 84 longitude/latitude
                  (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless a different coordinate
                  reference system is specified in `crs`.

                  For WGS 84 longitude/latitude the values are in most cases the sequence of
                  minimum longitude, minimum latitude, maximum longitude and maximum latitude.
                  However, in cases where the box spans the antimeridian the first value
                  (west-most box edge) is larger than the third value (east-most box edge).

                  If the vertical axis is included, the third and the sixth number are
                  the bottom and the top of the 3-dimensional bounding box.

                  If a feature has multiple spatial geometry properties, it is the decision of the
                  server whether only a single spatial geometry property is used to determine
                  the extent or all relevant geometries.
                type: array
                oneOf:
                  - minItems: 4
                    maxItems: 4
                  - minItems: 6
                    maxItems: 6
                items:
                  type: number
            crs:
              description: |-
                Coordinate reference system of the coordinates in the spatial extent
                (property `bbox`). The default reference system is WGS 84 longitude/latitude.
                In the Core this is the only supported coordinate reference system.
                Extensions may support additional coordinate reference systems and add
                additional enum values.
              type: string
              enum: [ "http://www.opengis.net/def/crs/OGC/1.3/CRS84" ]
              default: "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
        temporal:
          description: |-
            The temporal extent of the features in the collection.
          type: object
          properties:
            interval:
              description: |-
                One or more time intervals that describe the temporal extent of the dataset.
                The value `null` is supported and indicates an unbounded interval end.
                In the Core only a single time interval is supported. Extensions may support
                multiple intervals. If multiple intervals are provided, the union of the
                intervals describes the temporal extent.
              type: array
              minItems: 1
              items:
                description: |-
                  Begin and end times of the time interval. The timestamps are in the
                  temporal coordinate reference system specified in `trs`. By default
                  this is the Gregorian calendar.
                type: array
                minItems: 2
                maxItems: 2
                items:
                  $ref: "TOMP-API-1-CORE.yaml#/components/schemas/dateTime"
            trs:
              description: |-
                Coordinate reference system of the coordinates in the temporal extent
                (property `interval`). The default reference system is the Gregorian calendar.
                In the Core this is the only supported temporal coordinate reference system.
                Extensions may support additional temporal coordinate reference systems and add
                additional enum values.
              type: string
              enum: [ "http://www.opengis.net/def/uom/ISO-8601/0/Gregorian" ]
              default: "http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"

    collections:
      type: object
      required:
        - links
        - collections
      properties:
        links:
          type: array
          items:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/link"
        collections:
          type: array
          items:
            $ref: "#/components/schemas/collection"

    processList:
      required:
      - links
      - processes
      type: object
      properties:
        processes:
          type: array
          items:
            $ref: '#/components/schemas/processSummary'
        links:
          type: array
          items:
            $ref: 'TOMP-API-1-CORE.yaml#/components/schemas/link'

    process:
      allOf:
      - $ref: '#/components/schemas/processSummary'
      - type: object
        properties:
          inputs:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/inputDescription'
          outputs:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/outputDescription'
          subscriber:
            type: object
            properties:
              successUri:
                $ref: "TOMP-API-1-CORE.yaml#/components/schemas/url"
              inProgressUri:
                $ref: "TOMP-API-1-CORE.yaml#/components/schemas/url"
              failedUri:
                $ref: "TOMP-API-1-CORE.yaml#/components/schemas/url"

    inputDescription:
      allOf:
      - $ref: '#/components/schemas/descriptionType'
      - required:
        - schema
        type: object
        properties:
          minOccurs:
            type: integer
            default: 1
          maxOccurs:
            oneOf:
            - type: integer
              default: 1
            - type: string
              enum:
              - unbounded
          schema:
            type: object

    processSummary:
      allOf:
      - $ref: '#/components/schemas/descriptionType'
      - required:
        - id
        - version
        type: object
        properties:
          id:
            type: string
          version:
            type: string
          jobControlOptions:
            type: array
            items:
              $ref: '#/components/schemas/jobControlOptions'
          outputTransmission:
            type: array
            items:
              $ref: '#/components/schemas/transmissionMode'
          links:
            type: array
            items:
              $ref: 'TOMP-API-1-CORE.yaml#/components/schemas/link'

    outputDescription:
      allOf:
      - $ref: '#/components/schemas/descriptionType'
      - required:
        - schema
        type: object
        properties:
          schema:
            type: object

    jobControlOptions:
      type: string
      enum:
      - sync-execute
      - async-execute
      - dismiss

    transmissionMode:
      type: string
      default: value
      enum:
      - value
      - reference

    descriptionType:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        keywords:
          type: array
          items:
            type: string
        metadata:
          type: array
          items:
            $ref: '#/components/schemas/metadata'
        additionalParameters:
          allOf:
          - $ref: '#/components/schemas/metadata'
          - type: object
            properties:
              parameters:
                type: array
                items:
                  $ref: '#/components/schemas/additionalParameter'
    metadata:
      type: object
      properties:
        title:
          type: string
        role:
          type: string
        href:
          type: string

    additionalParameter:
      required:
      - name
      - value
      type: object
      properties:
        name:
          type: string
        value:
          type: array
          items:
            oneOf:
            - type: string
            - type: number
            - type: integer
            - type: array
              items:
                type: object
            - type: object