# Copyright (C) 2020 Daniel Friesel
#
# SPDX-License-Identifier: CC0-1.0
openapi: 3.0.3
info:
  title: travelynx
  version: 0.0.0
  description: DB Zugbildungsplan to JSON
servers:
  - url: 'https://lib.finalrewind.org/dbdb'
paths:
  '/db_zugbildung_v0.json':
    get:
      summary: Retrieve train composition
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/traincomposition'
components:
  schemas:
    traincomposition:
      type: object
      properties:
        deprecated:
          type: boolean
          example: false
          description: if true, this JSON export version is no longer supported and will be removed in the future
        source:
          type: string
          example: "2021_ZpAR_Wi_Endstück.pdf"
          description: PDF file used to generate this JSON export
        valid:
          type: string
          example: "2020-12-13/2021-06-12"
          description: ISO 8601 interval describing when this train composition dataset is valid
        train:
          type: object
          description: dict mapping train numbers to probably valid train objects
          additionalProperties:
            $ref: '#/components/schemas/train'
        train_variants:
          type: object
          description: dict mapping train numbers to list of possible train objects
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/train'
    train:
      type: object
      properties:
        rawType:
          type: string
          example: ICE-W
          description: train type as specified in train composition PDF
        type:
          type: string
          example: ICE 3
          description: scheduled train type as estimated from rawType and wagon data
        shortType:
          type: string
          example: "3"
          description: A short identifier useful to differentiate between train types such as ICE 3 / ICE 3 Redesign or IC1 / IC2 KISS
        name:
          type: string
          example: ICE International
          description: train name / line name / description as specified in PDF
        empty:
          type: boolean
          example: false
          description: true if this is an empty train without passenger service ("Leerfahrt")
        route:
          $ref: '#/components/schemas/route'
        commonAttr:
          $ref: '#/components/schemas/trainAttr'
        attrVariants:
          type: array
          items:
            $ref: '#/components/schemas/trainAttr'
        cycle:
          $ref: '#/components/schemas/cycle'
        hasWagon:
          $ref: '#/components/schemas/hasWagon'
        wagons:
          $ref: '#/components/schemas/wagons'
    route:
      type: object
      properties:
        preStart:
          type: string
          example: Berlin-Rummelsburg (Triebzuganlage)
          description: station where the train is prepared / provisioned
        start:
          type: string
          example: Berlin-Gesundbrunnen (05:53)
          description: first station(s) with passenger service. may contain scheduled departure time.
        middle:
          type: array
          items:
            type: string
        end:
          type: string
          example: München (10:02)
          description: terminal station(s) with passenger service. may contain scheduled arrival time.
        postEnd:
          type: string
          description: station where the train is parked
    trainAttr:
      type: object
      properties:
        brakingPercentage:
          type: integer
          example: 177
          description: Bremshundertstel
        length:
          type: integer
          example: 402
          description: train length (including powercar)
        series:
          type: string
          example: "406"
          description: powercar series
        series2:
          type: string
          description: series of second powercar (if present)
        station:
          type: string
          example: "Basel SBB"
          description: station name, may be prefixed with a plus sign
        vmax:
          type: integer
          example: 300
          description: rated maximum speed in km/h
    cycle:
      type: object
      additionalProperties:
        type: object
        properties:
          from:
            type: array
            items:
              type: string
          to:
            type: array
            items:
              type: string
    hasWagon:
      type: object
      additionalProperties:
        type: boolean
        description: true iff the wagon or locomotive type described by the key is scheduled for the train
      example:
        "174.5": true
        DApza: true
        DBpbzfa: true
        PBpza: true
    wagons:
      type: array
      items:
        type: object
        properties:
          type:
            type: string
            example: DBpbzfa
            description: wagon or locomotive type
          number:
            type: integer
            example: 1
            description: wagon number